Work with Notion from the CLI

How to use

Prefer the official ntn CLI; use curl only when ntn is unavailable or a raw request is clearer.

Prefer the official ntn CLI; fall back to curl only when ntn is unavailable or a raw request is clearer.

For content input, use --content, stdin, or an editor in a TTY.

Parent references can be given as page:<id>, database:<id>, or data-source:<id>.

For properties, templates, and the full Pages API, use ntn api v1/pages.

Raw API input syntax: path=value is a string body field, path:=json a typed JSON body field, name==value a query parameter, Header:Value a request header, and --data '<json>' or stdin JSON serves larger bodies.

path=value is a string body field.

path:=json is a typed JSON body field.

name==value is a query parameter.

Header:Value is a request header.

Use --data '<json>' or stdin JSON for larger bodies.

Current latest API version: 2026-03-11.

Use in_trash, not archived.

For append block positioning, use position, not flat after.

The transcription block has been renamed to meeting_notes.

Databases can contain multiple data sources, and page parents generally use data_source_id.

Install the CLI globally with npm, verify the version, and log in.

npm install -g ntn
ntn --version
ntn login

For script or headless authentication, export the API token and API version as environment variables.

export NOTION_API_TOKEN=secret_or_ntn_token
export NOTION_API_VERSION=2026-03-11

Check the CLI health, list available API endpoints, and view help, specs, or docs for a specific endpoint.

ntn doctor
ntn api ls
ntn api ls --json
ntn api v1/comments --help
ntn api v1/comments --spec -X POST
ntn api v1/comments --docs -X POST

Read, create, update, or trash pages; these helpers are Markdown-first.

The page helpers are Markdown-first.

ntn pages get <page-id>
ntn pages get <page-id> --json
ntn pages create --parent page:<page-id> --content '# Title\n\nBody'
ntn pages create --parent data-source:<data-source-id> < page.md
ntn pages update <page-id> --content '# Updated'
ntn pages update <page-id> < page.md
ntn pages trash <page-id> --yes

Resolve a database ID to its data sources and query a data source, optionally with limits, sorting, and filters.

ntn datasources resolve <database-id>
ntn datasources resolve <database-id> --json
ntn datasources query <data-source-id>
ntn datasources query <data-source-id> --limit 50 --json
ntn datasources query <data-source-id> --sort 'Date desc'
ntn datasources query <data-source-id> --filter '{"property":"Done","checkbox":{"equals":true}}'

Use resolve when you have a database ID; querying requires a data source ID.

Call arbitrary Notion API endpoints directly with the inline input syntax.

ntn api v1/users/me
ntn api v1/search query=roadmap page_size:=10
ntn api v1/pages 'parent[data_source_id]='"$DS_ID" 'properties[Name][title][0][text][content]=New item'
ntn api "v1/pages/$PAGE_ID" -X PATCH in_trash:=true
ntn api "v1/blocks/$PAGE_ID/children" -X PATCH \
  'children[0][type]=paragraph' \
  'children[0][paragraph][rich_text][0][text][content]=Hello'

Use only one body source per request.

Upload files from stdin, a file with an explicit name and content type, or an external URL, then get or list uploads.

ntn files create < image.png
ntn files create --filename photo.png --content-type image/png < /tmp/photo
ntn files create --external-url https://example.com/photo.png
ntn files get <upload-id>
ntn files list

Create, deploy, and list workers, and inspect worker runs and their logs.

ntn workers new
ntn workers deploy
ntn workers list --json
ntn workers runs list --json
ntn workers runs logs <run-id>

Workers may require a Business or Enterprise plan and workspace enablement.

As a fallback, call the Notion API directly with curl, passing the auth token, API version, and content type headers.

curl -sS "https://api.notion.com/v1/users/me" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2026-03-11" \
  -H "Content-Type: application/json"

Current latest API version: 2026-03-11.