ntion-cli

Original：🇺🇸 English
Translated

Use the ntion CLI to interact with Notion workspaces — searching, reading, creating, updating, and managing pages, databases (data sources), and block content. Use when the user wants to: (1) search their Notion workspace, (2) query or list databases, (3) read, create, update, archive, or relate pages, (4) read, append, insert, replace, or delete block content on pages, (5) manage Notion authentication, or (6) perform any Notion workspace operation from the terminal. Trigger on mentions of "Notion", "ntion", page/database IDs, or requests involving workspace content management.

12installs
Sourcembroton/notion-cli
Added on

NPX Install

npx skill4agent add mbroton/notion-cli ntion-cli

Tags

Translated version includes tags in frontmatter
notion-cliworkspace-managementdatabase-operationspage-editingblock-manipulation

SKILL.md Content

View Translation Comparison →

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
.
bash
ntion auth --token "secret_xxx"
# Or interactive: ntion auth
# Verify: ntion doctor
Token is created at https://www.notion.so/profile/integrations.

Commands

search

bash
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)

bash
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

bash
# 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)

bash
# 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:
json
{"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.