ntion CLI

Notion CLI. Run via npx ntion (or ntion if installed globally).

Authentication

Authentication is a one-time setup stored in ~/.config/ntion/config.json. If a command fails with exit code 6 (auth error), prompt the user to run ntion auth.

ntion auth --token "secret_xxx"
# Or interactive: ntion auth
# Verify: ntion doctor

Token is created at https://www.notion.so/profile/integrations.

Commands

search

ntion search --query "meeting notes"
ntion search --query "tasks" --object page --limit 10
ntion search --query "Q1" --created-after 2026-01-01T00:00:00Z

Options: --query (required), --scope <id>, --object page|data_source, --created-after/--created-before, --edited-after/--edited-before, --created-by <user_id>, --limit, --cursor, --scan-limit, --view compact|full, --pretty.

data-sources (databases)

ntion data-sources list --query "tasks"
ntion data-sources get --id <id> --view full
ntion data-sources schema --id <id>
ntion data-sources query --id <id> \
  --filter-json '{"property":"Status","status":{"equals":"In Progress"}}' \
  --sort-json '{"property":"Created","direction":"descending"}' \
  --limit 50

Use schema to discover property names and types before querying or creating pages. Filter/sort JSON follows the Notion API filter format.

pages

# Read
ntion pages get --id <id>
ntion pages get --id <id> --include-content --content-format markdown

# Create
ntion pages create \
  --parent-data-source-id <ds_id> \
  --properties-json '{"Name":"New task","Status":"Not started"}'

# Bulk create (up to 100)
ntion pages create-bulk \
  --parent-data-source-id <ds_id> \
  --items-json '[{"properties":{"Name":"A"}},{"properties":{"Name":"B"}}]'

# Update
ntion pages update --id <id> --patch-json '{"Status":"Done"}'

# Archive / restore
ntion pages archive --id <id>
ntion pages unarchive --id <id>

# Relations
ntion pages relate --from-id <id> --property "Project" --to-id <target_id>
ntion pages unrelate --from-id <id> --property "Project" --to-id <target_id>

blocks (page content)

# Read content as markdown
ntion blocks get --id <page_or_block_id>
ntion blocks get --id <id> --depth 2 --format compact

# Append to end
ntion blocks append --id <id> --markdown $'## Section\n\nContent here'
ntion blocks append --id <id> --markdown-file ./notes.md

# Insert at position
ntion blocks insert --parent-id <id> --markdown "Intro text" --position start
ntion blocks insert --parent-id <id> --markdown "Middle" --after-id <block_id>

# Find blocks
ntion blocks select \
  --scope-id <id> \
  --selector-json '{"where":{"type":"paragraph","text_contains":"TODO"}}'

# Replace block range
ntion blocks replace-range \
  --scope-id <id> \
  --start-selector-json '{"where":{"text_contains":"## Old Section"}}' \
  --end-selector-json '{"where":{"text_contains":"## Next Section"}}' \
  --markdown "## New Section\n\nUpdated content"

# Delete blocks
ntion blocks delete --ids <block_id>
ntion blocks delete --ids <id1> <id2> <id3>

Workflow patterns

Discover → Query → Act

1. Find the database: ntion data-sources list --query "tasks"
2. Get its schema: ntion data-sources schema --id <id>
3. Query with filters: ntion data-sources query --id <id> --filter-json '...'
4. Create/update pages using the discovered property names

Read → Edit page content

1. Read current content: ntion blocks get --id <page_id>
2. Append new content: ntion blocks append --id <page_id> --markdown "..."
3. Or replace a section: use blocks replace-range with selectors
4. Delete specific blocks: ntion blocks delete --ids <id1> <id2>

Output format

All commands return JSON envelopes:

{"ok": true, "data": {...}, "meta": {"request_id": "..."}}
{"ok": false, "error": {"code": "not_found", "message": "...", "retryable": false}, "meta": {...}}

Exit codes: 0=success, 1=failure, 2=invalid input, 3=not found, 4=conflict, 5=retryable, 6=auth error.

Notes

• --view compact (default) returns minimal data. Use --view full when complete details are needed.
• Mutations are idempotent with verify-first recovery on ambiguous outcomes. Re-read before retrying when the CLI reports uncertainty.
• Bulk create supports --concurrency (default 5) for parallel operations.
• Use --pretty on any command for human-readable JSON output.