notion-cli-agent
Local Notion CLI for shell-based access to pages, databases, tasks, content blocks; bulk/batch ops. Prefer over Notion MCP or direct API.
Balneario-de-Cofrentes · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add Balneario-de-Cofrentes/notion-cli-agent --skill notion-cli-agentAbout this skill
name: notion-cli-agent description: Local Notion CLI for shell-based access to pages, databases, tasks, content blocks; bulk/batch ops. Prefer over Notion MCP or direct API.
notion-cli-agent
Local CLI for full Notion access.
Binary
notion <args> # globally installed via npm
Auth — just run notion <cmd>
That's it. The CLI handles auth automatically. Do not prefix with NOTION_TOKEN=... unless notion doctor reports a 401 (see Troubleshooting below).
Token resolution order inside the CLI:
NOTION_TOKENenv varNOTION_API_KEYenv var~/.config/notion/api_key← source of truth~/.notion/token
The recommended setup keeps ~/.config/notion/api_key and the NOTION_TOKEN env var in lock-step by sourcing the file from .zshrc:
# in ~/.zshrc — single source of truth for the token
export NOTION_TOKEN="$(cat ~/.config/notion/api_key 2>/dev/null)"
With this, env var and file can't diverge — the stale-token gotcha disappears. Run notion doctor to verify (5/5 green).
Troubleshooting (only if notion doctor reports 401)
Symptom: notion doctor shows ✅ Token: Token found but ❌ API Connection: Token is invalid or expired.
Means: the env var is stale (a parent process exported an outdated token). Fix:
# One-shot bypass (uses the file directly):
NOTION_TOKEN=$(cat ~/.config/notion/api_key) notion <cmd>
# Permanent fix: update .zshrc to the dynamic export above, restart shell.
Workspace sync (do this first)
notion sync # cache all databases locally
notion list # show cached databases
notion list --json # for parsing
After sync, use database names instead of UUIDs in ALL commands:
notion db query "Tasks" --limit 5 --llm
notion find "Tasks" "overdue" --llm
notion stats overview "Projects"
If ~/.config/notion/workspace.json exists (from sync or the notion-onboarding skill), names resolve automatically. Falls back to UUIDs if no cache.
Agent Workflow
- Sync workspace —
notion sync(once per session, ornotion listif already synced) - Understand schema —
notion inspect context "Tasks"ornotion inspect schema "Tasks" --llm - Query deterministically first — prefer
db query --title,search --exact --db --first, or--llmover fuzzy workspace-wide search when you know the target DB - Write with
--dry-runfirst on bulk/batch ops, then confirm with user
Core Commands
Discover
notion sync # cache databases for name lookup
notion list # show cached databases
notion inspect ws --compact # all databases, names + ids
notion inspect schema "Tasks" --llm # property types + valid values
notion inspect context "Tasks" # workflow context + examples
notion ai prompt "Tasks" # DB-specific agent instructions
Users & guests
notion user list # members + bots + cached guests
notion user resolve-guests # discover guests, cache them
notion user get <user_id> # works for guests too (by id)
Guests are NOT in notion user list. Notion's GET /v1/users returns only
members and bots — guests are invisible — so you can't list them or look up
their id to assign them. Run notion user resolve-guests once: it walks search
results, reads every page's created_by/last_edited_by, resolves the unknown
ids via GET /v1/users/{id}, and caches the guests in
~/.config/notion/guests.json. After that, user list shows them flagged
[guest], and you can assign them in --prop "Field:people=…" by email or
name (see Property type hints). notion sync also fishes guests as a side
effect.
Query
# Exact lookup in a known DB (deterministic — uses database query API)
notion db query "Tasks" --title "Known Page" --json
notion db query "Tasks" --limit 20 --llm # compact output
# Fuzzy search (workspace-wide, best-effort — Notion may miss long titles)
notion search "keyword" --limit 10
notion search "keyword" --db <db_id> --llm # filter by parent DB
notion search "short title" --exact --first --json # best-effort exact match
# Natural language
notion find "overdue tasks unassigned" -d <db_id> --llm
notion find "high priority" -d <db_id> --explain # preview filter, don't run
For exact lookup by title in a known DB, always use db query --title — not search --exact. Notion's search API is fuzzy and may miss pages with long or common-word titles.
Read pages
notion page get <page_id> # properties
notion page get <page_id> --content # + content blocks
notion page get <page_id> --json # raw JSON
notion page read <page_id> # content as Markdown (native API, 1 call)
notion page read <page_id> --blocks # legacy block-by-block conversion
notion page read <page_id> -o page.md # save to file
notion ai summarize <page_id> # concise summary
notion ai extract <page_id> --schema "email,phone,date"
Write pages
notion page create --parent <db_id> --title "Task Name"
notion page create --parent <db_id> --title "Task" --prop "Status:status=Todo" --prop "Priority:select=High"
notion page update <page_id> --prop "Status:status=Done"
notion page update <page_id> --clear-prop "Assignee" # type-aware clear
notion page update <page_id> --clear-prop "Tags" --clear-prop "Deadline"
notion page write <page_id> -f content.md # write Markdown to page
notion page write <page_id> -f doc.md --replace # replace all content
notion page edit <page_id> --at 3 --delete 2 # surgical block editing
notion page edit <page_id> --at 5 --markdo
Read the complete source ↗