Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

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-agent

About 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:

  1. NOTION_TOKEN env var
  2. NOTION_API_KEY env var
  3. ~/.config/notion/api_key ← source of truth
  4. ~/.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

  1. Sync workspace — notion sync (once per session, or notion list if already synced)
  2. Understand schema — notion inspect context "Tasks" or notion inspect schema "Tasks" --llm
  3. Query deterministically first — prefer db query --title, search --exact --db --first, or --llm over fuzzy workspace-wide search when you know the target DB
  4. Write with --dry-run first 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 ↗