Discover and map a user's Notion workspace for the first time. Run this before any Notion workflows when no workspace state exists. Identifies key databases (projects, tasks, OKRs, home page, etc.) through guided discovery and saves them to a persistent state file so future interactions don't need to re-discover. Use when: first Notion setup, user says "set up Notion", "map my workspace", "onboard Notion", or when ~/.config/notion/workspace.json is missing.
Maps the user's Notion workspace and saves a state file that all future Notion skills read.
State file: ~/.config/notion/workspace.json
cat ~/.config/notion/workspace.json 2>/dev/null
If it exists: show the current mapping, ask the user if they want to update it or continue. If absent: proceed with full onboarding.
notion user me
Confirm the integration is working. Note the workspace name.
If this returns 401 API token is invalid, you're almost certainly hitting a stale NOTION_TOKEN env var inherited from the parent process — the CLI prefers env vars over ~/.config/notion/api_key. Use the file-token workaround from the skill for the rest of this onboarding:
NOTION_TOKEN=$(cat ~/.config/notion/api_key) notion user me
If that works, apply the same NOTION_TOKEN=$(cat ~/.config/notion/api_key) prefix to every notion call in the steps below.
notion inspect ws --compact
notion inspect ws --json
This lists all databases the integration can see. Present the list clearly to the user (name + ID).
Ask the user to identify which databases correspond to each role. Be conversational — not all workspaces have all of these:
I found these databases in your workspace:
[list from step 2]
Can you tell me:
1. Which one is your main Tasks / To-do database? (where day-to-day work lives)
2. Which one is your Projects database? (higher-level work containers)
3. Do you have a Goals, OKRs, or Objectives database?
4. Is there a main Home or Dashboard page (not a database) I should know about?
5. Any other databases that are central to how you work? (e.g., CRM, Notes, Areas)
For each confirmed database, run:
notion inspect context <db_id>
notion inspect schema <db_id> --llm
Extract from the output:
titleProp name (the property of type title)statusProp name and valid status values (if any)Write ~/.config/notion/workspace.json following the schema in references/state-schema.md.
mkdir -p ~/.config/notion
# write the JSON file
Example minimal state:
{
"version": 1,
"onboardedAt": "YYYY-MM-DD",
"updatedAt": "YYYY-MM-DD",
"workspace": { "name": "Acme" },
"databases": {
"tasks": {
"id": "abc-123",
"title": "Tasks",
"titleProp": "Name",
"statusProp": "Status",
"statuses": ["Todo", "In Progress", "Done"]
}
}
}
Show a human-readable summary of what was saved. Ask: "Does this look right? Anything to adjust?"
Apply any corrections, save the final file.
Tell the user: "Your workspace is now mapped. Any Notion task I do will use these databases by default — no need to look up IDs. Run this onboarding again anytime to update."
For full state schema see: references/state-schema.md