/notion-cli

name: notion-cli
description: |
  Work with Notion from the terminal using the `notion` CLI. Use when the user needs to read, create, update, query, or manage Notion pages, databases, blocks, comments, users, or files programmatically. Covers the entire Notion API with 50+ commands. Triggers: Notion workspace automation, database queries, page creation, block manipulation, comment threads, file uploads, relation management, database export, multi-workspace management, or any Notion API interaction from the command line.

Notion CLI

`notion` is a CLI for the Notion API. Single Go binary, full API coverage, dual output (pretty tables for humans, JSON for agents). Current: **v0.7.0**.

Install

# Homebrew
brew install 4ier/tap/notion-cli

# npm
npm install -g @4ier/notion-cli

# Go
go install github.com/4ier/notion-cli@latest

# Or download a binary from https://github.com/4ier/notion-cli/releases

Auth

notion auth login --with-token <<< "ntn_xxxxxxxxxxxxx"
notion auth login --with-token --profile work <<< "ntn_xxx"  # named profile
export NOTION_TOKEN=ntn_xxxxxxxxxxxxx                        # env var alternative
notion auth status        # shows workspace + integration type (internal/public)
notion auth switch        # interactive profile picker
notion auth switch work   # direct switch
notion auth doctor        # health check — warns if internal integration

`auth status` / `doctor` surface the integration type, so it's easy to spot when you need to share a parent page before creating workspace-root content.

Search

notion search "query"                    # everything
notion search "query" --type page        # pages only
notion search "query" --type database    # databases only

Pages

notion page view <id|url>                # render page content
notion page list                         # list workspace pages
notion page create <parent> --title "X" --body "content"
notion page create <db-id> --db "Name=Review" "Status=Todo"  # database row

# Archive / restore (soft-delete)
notion page archive <id>                 # canonical
notion page trash <id>                   # alias
notion page delete <id>                  # alias (legacy)
notion page restore <id>                 # reverse

# Move / open / edit
notion page move <id> --to <parent>
notion page open <id>                    # open in browser
notion page edit <id|url>                # edit in $EDITOR (markdown round-trip)

# Properties (type-aware)
notion page set <id> Key=Value ...
notion page props <id>                   # show all (summary; paginated values may be truncated)
notion page props <id> <prop-id>         # single raw JSON

# NEW in v0.7: paginated single-property fetch (fixes >25-item truncation)
notion page property <id> <prop-id>
notion page property <id> --name "References"         # resolve id by display name
notion page property <id> <prop-id> --format json

# Relations
notion page link <id> --prop "Rel" --to <target-id>
notion page unlink <id> --prop "Rel" --from <target-id>

# NEW in v0.7: server-side markdown I/O (preferred for full-page dumps)
notion page markdown <id>                # print to stdout
notion page markdown <id> --out page.md  # write to file
notion page markdown <id> --format json  # full response (truncated flag, unknown_block_ids)

notion page set-markdown <id> --file new.md           # replace whole page (default)
cat new.md | notion page set-markdown <id> --file -   # stdin
notion page set-markdown <id> --append --text "\n\n> Appended"
notion page set-markdown <id> --after "Status...pending" --text "Now: done"
notion page set-markdown <id> --range "old...stale" --text "fresh" --allow-deleting-content

**`page markdown` vs `block list --md`**: prefer `page markdown` for whole pages — it uses the server renderer and handles toggles, columns, synced blocks, and databases-as-pages correctly. Use `block list --md` only when you need a single sub-block.

Databases

notion db list                           # list databases
notion db view <id>                      # show schema
notion db query <id>                     # all rows
notion db query <id> -F 'Status=Done' -s 'Date:desc'
notion db query <id> --filter-json '{"or":[...]}'
notion db query <id> --all
notion db create <parent> --title "X" --props "Status:select,Date:date"
notion db update <id> --title "New Name" --add-prop "Priority:select"
notion db add <id> "Name=Task" "Status=Todo" "Priority=High"
notion db add-bulk <id> --file items.json
notion db export <id>                    # CSV (default)
notion db export <id> --format json
notion db export <id> --format md -o report.md
notion db open <id>

Filter operators

| Syntax | Meaning | |--------|---------| | `=` | equals | | `!=` | not equals | | `>` / `>=` | greater than (or equal) | | `<` / `<=` | less than (or equal) | | `~=` | contains |

Multiple `-F` flags combine with AND. Property types are auto-detected from schema.

Sort: `-s 'Date:desc'` or `-s 'Name:asc'`

Bulk add file format

[{"Name": "Task A", "Status": "Todo"}, {"Name": "Task B", "Status": "Done"}]

Blocks

notion block list <parent-id>            # list child blocks
notion block list <parent-id> --all
notion block list <parent-id> --depth 3  # recursive
notion block list <parent-id> --md       # markdown; prefer 'page markdown' for pages
notion block get <id>

# Append / insert — both handle >100 children and >2000-char code blocks automatically
notion block append <parent> "text"
notion block append <parent> "text" -t bullet
notion block append <parent> "text" -t code --lang ts        # 'ts' / 'sh' / 'yml' etc. normalized
notion block append <parent> --file notes.md                 # any length, auto-batched
notion block append <parent> --file big.md --on-oversize=truncate
notion block insert <parent> "text" --after <block-id>

# Update — now with markdown support
notion block update <id> --text "plain