notion-cli

# 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 pages get <page-id>` — retrieve a page as Markdown. Use this to read page content. - `ntn <command> --help` — help for any command or subcommand. ## Always sync before and after every edit Notion lives in the cloud: there's no local copy and no `sync` command. Syncing here means fetching fresh state right before writing and reading it back right after: 1. **Before:** `ntn pages get <page-id>` immediately before the edit, and build the change on that output. Never edit from Markdown fetched earlier in the session. Someone may have edited the page since. 2. **Edit:** `ntn pages edit <page-id> < page.md` (see below). 3. **After:** `ntn pages get <page-id>` again and confirm the change landed and nothing else changed. ## Install If `ntn` is missing, get user permission before installing it. Follow the current official package-manager instructions from <https://ntn.dev>; do not pipe a remote installer directly to a shell. Verify the installed binary with `ntn --version` before authenticating. ## Authentication - The CLI automatically uses `NOTION_API_TOKEN` when it is set. `ntn pages` currently requires it. - Check `NOTION_API_TOKEN` first. If it is already set, prefer using it instead of telling the user to run `ntn login`. - `ntn login` / `ntn logout` — log the CLI in or out (only use if not using `NOTION_API_TOKEN`). `ntn login` requires the user to visit a URL in a web browser. - Explain the transfer and get approval before uploading private, unpublished, personal, or secret-bearing local content to a new Notion workspace. ## `ntn api` Run `ntn api --help` for full syntax. Quick summary: ```bash # 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`. ### Markdown for pages and comments Prefer `ntn pages create` / `ntn pages edit` for Markdown page content. Use the `markdown` field when creating or updating comments via `ntn api`. `ntn pages edit` **replaces the whole page content**. Start from fresh `ntn pages get` output: it prints properties as frontmatter, and `edit` strips that back off. Change only what was asked, and feed the file back in. Pass `--allow-deleting-content` only when the user has agreed to removing child pages or databases. ```bash # Comment with markdown ntn api v1/comments -d '{"parent":{"page_id":"abc123"},"markdown":"Here is a [link](https://example.com) and **bold text**."}' # Page with markdown body ntn pages create --parent page:abc123 --content '## Heading\n\nSome *formatted* content.' ``` The `markdown` field supports inline formatting (bold, italic, code, links, etc.). Only fall back to `rich_text` if you need features that Markdown cannot express (e.g. mentions, custom emoji, or colors). ## `ntn files` Convenience wrapper around the File Uploads API. ```bash 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. Confirm before deploying to production, executing a capability with destructive or costly effects, or changing account-level worker configuration. ```bash 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 ```