Notion CLI

Look things up before answering

The CLI is self-documenting. Always prefer running these commands over guessing syntax or relying on memorized knowledge:

• ntn api ls — list every public API endpoint.
• ntn api <path> --help — show methods, doc links, and usage for an endpoint.
• ntn api <path> --docs — print the full official docs for an endpoint.
• ntn api <path> --spec — print a reduced OpenAPI fragment (useful for understanding request/response schemas).
• ntn <command> --help — help for any command or subcommand.

Install

npm i -g ntn@latest

Authentication

• NOTION_API_TOKEN — required for ntn api and ntn files. Set this env var to a Notion integration token.
• ntn login / ntn logout — session auth for ntn workers and ntn tokens. This does not authenticate ntn api or ntn files today.

ntn api

Run ntn api --help for full syntax. Quick summary:

# GET with query param
ntn api v1/users page_size==100

# POST with inline body fields
ntn api v1/pages parent[page_id]=abc123

# POST with JSON body
ntn api v1/pages -d '{"parent":{"page_id":"abc123"}}'

The method is inferred (GET by default, POST when a body is present). Override with -X METHOD.

ntn files

Convenience wrapper around the File Uploads API.

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

ntn workers

Manage Notion workers (deploy, list, execute, etc.). Run ntn workers --help for subcommands.

ntn workers new my-worker        # scaffold a new project
ntn workers deploy               # deploy from current directory
ntn workers ls                   # list workers
ntn workers exec <capability>    # execute a capability

ntn tokens

Manage tokens used by ntn workers. Requires ntn login. These are separate from NOTION_API_TOKEN integration tokens.

ntn tokens create
ntn tokens ls
ntn tokens revoke <token-id>