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

Install

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

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

# npm
npm install -g notion-cli-go

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

Auth

notion auth login --with-token <<< "ntn_xxxxxxxxxxxxx"   # or interactive
notion auth login --with-token --profile work <<< "ntn_xxx"  # save as named profile
export NOTION_TOKEN=ntn_xxxxxxxxxxxxx                     # env var alternative
notion auth status                                        # show current profile
notion auth switch                                        # interactive profile picker
notion auth switch work                                   # switch to named profile
notion auth doctor                                        # health check

Command Reference

Search

notion search "query"                    # search 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
notion page delete <id>                  # archive page
notion page restore <id>                 # unarchive page
notion page move <id> --to <parent>
notion page open <id>                    # open in browser
notion page edit <id|url>                # edit in $EDITOR (Markdown round-trip)
notion page edit <id> --editor nano      # specify editor
notion page set <id> Key=Value ...       # set properties (type-aware)
notion page props <id>                   # show all properties
notion page props <id> <prop-id>         # get specific property
notion page link <id> --prop "Rel" --to <target-id>    # add relation
notion page unlink <id> --prop "Rel" --from <target-id> # remove relation

Databases

notion db list                           # list databases
notion db view <id>                      # show schema
notion db query <id>                     # query all rows
notion db query <id> -F 'Status=Done' -s 'Date:desc'  # filter + sort
notion db query <id> --filter-json '{"or":[...]}'     # complex JSON filter
notion db query <id> --all               # fetch all pages
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              # bulk create from JSON
notion db export <id>                    # export all rows as CSV (default)
notion db export <id> --format json      # export as JSON
notion db export <id> --format md -o report.md  # export as Markdown table to file
notion db open <id>                      # open in browser

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      # paginate through all
notion block list <parent-id> --depth 3  # recursive nested blocks
notion block list <parent-id> --md       # output as Markdown
notion block get <id>                    # get single block
notion block append <parent> "text"      # append paragraph
notion block append <parent> "text" -t bullet          # bullet point
notion block append <parent> "text" -t code --lang go  # code block
notion block append <parent> --file notes.md           # from file
notion block insert <parent> "text" --after <block-id> # positional insert
notion block update <id> --text "new"    # update content
notion block delete <id1> [id2] [id3]    # delete one or more
notion block move <id> --after <target>  # reposition after target block
notion block move <id> --before <target> # reposition before target block
notion block move <id> --parent <new-parent>  # move to different parent

Block types: paragraph/p, h1, h2, h3, bullet, numbered, todo, quote, code, callout, divider

Comments

notion comment list <page-id>
notion comment add <page-id> "comment text"
notion comment get <comment-id>
notion comment reply <comment-id> "reply text"  # reply in same thread

Users

notion user me                           # current bot info
notion user list                         # all workspace users
notion user get <user-id>

Files

notion file list                         # list uploads
notion file upload ./path/to/file        # upload (auto MIME detection)

Raw API (escape hatch)

notion api GET /v1/users/me
notion api POST /v1/search '{"query":"test"}'
notion api PATCH /v1/pages/<id> '{"archived":true}'

Output Modes

• Terminal (TTY): colored tables, readable formatting
• Piped/scripted: JSON automatically
• Explicit: --format json or --format table
• --debug: show HTTP request/response details

All output includes full Notion UUIDs. All commands accept Notion URLs or IDs.

Tips

• notion db add and notion page set auto-detect property types from schema
• Multi-select: Tags=tag1,tag2,tag3
• Checkbox: Done=true
• Pipe to jq: notion db query <id> -F 'Status=Done' --format json | jq '.results[].id'