notion-cli

Original：🇺🇸 English
Translated

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

6installs
Source4ier/notion-cli
Added on

NPX Install

npx skill4agent add 4ier/notion-cli notion-cli

Tags

Translated version includes tags in frontmatter
notion-cliterminal-toolnotion-apiproductivity-toolcommand-line-interface

SKILL.md Content

View Translation Comparison →

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

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

bash
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

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

Pages

bash
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

bash
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

SyntaxMeaning
=
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

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

Blocks

bash
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

bash
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

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

Files

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

Raw API (escape hatch)

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