terrylica Notion CLI
Fast, agent-friendly access to Notion via the 4ier/notion-cli Go binary. Single static binary, sub-second startup, auto-JSON when piped.
Self-Evolving Skill: Fix this file immediately if instructions drift. Do not defer.
When to Use
Use this skill when the user wants to interact with Notion from the command line — searching pages, querying databases, reading content, exporting data, managing blocks, or adding comments. This wraps the Go binary notion (installed via brew install 4ier/tap/notion-cli).
Do NOT use this skill for programmatic Python automation with the Notion SDK — use productivity-tools:notion-sdk instead. This skill is for CLI-first, pipe-friendly operations.
Preflight
Before any operation, verify the CLI is authenticated:
notion auth status
If not authenticated, retrieve the token from Doppler and authenticate:
doppler secrets get NOTION_API_TOKEN --project claude-config --config prd --plain | notion auth login --with-token
Fallback: prompt the user for their integration token.
Output Formats
The CLI auto-detects context:
- TTY (interactive terminal): colored tables
- Piped (to
jq, file, etc.): clean JSON
Force a format with --format:
| Flag | Output |
|---|---|
--format json |
JSON |
--format table |
ASCII table |
--format md |
Markdown |
--format text |
Plain text |
For agent consumption, always pipe or use --format json to get structured output.
Core Commands
Search
notion search "meeting notes" # Search by title
notion search --type page "roadmap" # Pages only
notion search --type database # List all databases
notion search --all # Fetch all results (paginated)
notion search --limit 20 "query" # Limit results
Pages
notion page view <page-id|url> # View page content (blocks as markdown)
notion page props <page-id|url> # Show page properties
notion page create --parent <id> --title "X" # Create a page
notion page set <id> --prop 'Status=Done' # Set property
notion page edit <id> # Edit in $EDITOR
notion page move <id> --to <parent-id> # Move page
notion page delete <id> # Archive page
notion page restore <id> # Restore archived page
notion page open <id> # Open in browser
notion page list # List accessible pages
Databases
notion db list # List all databases
notion db view <db-id|url> # Show schema
notion db query <db-id|url> # Query all rows
notion db query <id> --filter 'Status=Done' # Simple filter
notion db query <id> --filter 'Date>=2026-01-01' --sort 'Date:desc'
notion db query <id> --filter-json '{"or":[...]}' # Complex filters
notion db query <id> --all # Fetch all pages
notion db export <id> --format csv -o data.csv # Export to CSV
notion db export <id> --format json # Export to JSON
notion db export <id> --format md # Export to Markdown table
notion db add <id> --prop 'Name=Task' --prop 'Status=Todo' # Add row
notion db add-bulk <id> --file rows.json # Bulk add from JSON
Filter operators: = != > >= < <= ~= (contains)
Multiple --filter flags are AND-combined. For OR logic, use --filter-json.
Blocks
notion block list <page-id|url> # List child blocks
notion block list <id> --depth 3 # Recursive (3 levels)
notion block get <block-id> # Get specific block
notion block append <page-id> --md "# Hello" # Append markdown
notion block insert <after-block-id> --md "X" # Insert after block
notion block delete <block-id> # Delete block
notion block move <block-id> --to <parent-id> # Move block
Comments
notion comment list <page-id> # List comments
notion comment add <page-id> --body "text" # Add comment
notion comment reply <comment-id> --body "X" # Reply to comment
Users
notion user me # Current bot user
notion user list # Workspace users
notion user get <user-id> # User details
Files
notion file upload <file-path> # Upload file
notion file list # List uploads
Raw API (escape hatch)
notion api GET /v1/users/me
notion api POST /v1/search --body '{"query":"test"}'
echo '{"query":"test"}' | notion api POST /v1/search
ID Resolution
The CLI accepts both Notion URLs and raw IDs interchangeably:
notion page view https://www.notion.so/My-Page-abc123def456
notion page view abc123def456
Common Patterns
Export entire database to JSON
notion db export <db-id> --format json -o database.json
Search and pipe to jq
notion search "project" --format json | jq '.results[] | {title: .properties.title.title[0].plain_text, url: .url}'
List all databases with their IDs
notion search --type database --all --format json | jq '.results[] | {id: .id, title: .title[0].plain_text}'
Recursive page content dump
notion block list <page-id> --depth 10 --format md
Credential Storage
| Store | Location | Purpose |
|---|---|---|
| Doppler | claude-config/prd:NOTION_API_TOKEN |
SSoT for token |
| CLI | ~/.config/notion/credentials.json |
Local auth cache |
Token format: ntn_* (Notion internal integration token).
Troubleshooting
| Issue | Fix |
|---|---|
unauthorized |
Token expired/revoked — regenerate at notion.so/profile/integrations |
object not found |
Page not connected to integration — add via page menu > Connections |
rate_limited |
CLI auto-retries; for bulk ops use --limit to reduce batch size |
validation_error |
Check property names match schema: notion db view <id> |
Post-Execution Reflection
After this skill completes, check before closing:
- Did the command succeed? If not, fix the instruction or error table that caused the failure.
- Did parameters or output change? If the CLI interface drifted, update usage examples and command tables.
- Was a workaround needed? If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.
Only update if the issue is real and reproducible — not speculative.