| name | notion-cli |
| description | Use the Notion CLI (`ntn`) to interact with the Notion API, manage workers, and upload files. Use when the user asks to "call the Notion API", "deploy a worker", "upload a file to Notion", "create a page", "query a database", or any task involving the `ntn` command. |
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:
ntn api v1/users page_size==100
ntn api v1/pages parent[page_id]=abc123
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
ntn workers deploy
ntn workers ls
ntn workers exec <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>
