Notion CLI - Notion Docs
Key Points
- 1The `ntn` CLI tool provides a comprehensive command-line interface for Notion, enabling users to install, authenticate, and manage their workspace directly from the terminal.
- 2It facilitates the creation, deployment, and operation of Notion Workers, which are small TypeScript programs extending Notion with syncs, tools, and webhooks, alongside direct Notion API requests with JSON support.
- 3Users can also manage and query data sources, upload static assets like images and PDFs, and debug Notion functionalities, all via concise `ntn` commands.
The provided document describes ntn, a command-line interface (CLI) tool designed to extend and manage Notion workspaces programmatically. The core purpose of ntn is to enable developers to deploy, operate, and debug Notion Workers, execute Notion API requests, manage data sources, and upload static assets directly from the terminal.
The installation process for ntn is straightforward, typically involving a curl command to download and execute an installation script (curl -fsSL https://ntn.dev bash), followed by verification via ntn --version. Post-installation, users authenticate the CLI by logging into their Notion workspace using ntn login, which links the tool to their account.
A central functionality of ntn is the management of Notion Workers. These are defined as small TypeScript programs engineered to extend Notion's capabilities by introducing custom sync mechanisms, utility tools, and webhook integrations. Developers can initiate new Workers using ntn workers new, deploy them to their Notion workspace with ntn workers deploy, and list existing Workers via ntn workers list.
The CLI also facilitates direct interaction with the Notion API. It supports authenticated API requests, providing features like inline JSON construction for request bodies and shell completion to streamline command input. Examples include fetching user data (ntn api v1/users), querying pages based on a parent ID (), and performing updates, such as patching a page's archived status (). The syntax demonstrates a specific assignment mechanism for boolean properties within the inline JSON structure.
Furthermore, ntn provides utilities for file management, allowing users to upload static assets like images and PDFs. These files can be local, uploaded directly from the file system (ntn files create photo.png), or referenced from an external URL (ntn files create --external-url https://example.com/photo.png), enabling them to be embedded or referenced within Notion pages. A listing of uploaded files is available through ntn files list.
In addition to these primary functionalities, the ntn CLI offers capabilities for managing login sessions and credentials, provides alternative installation methods, supports shell completions for various commands, and includes a comprehensive command reference. Its design aims to provide a robust developer experience for extending and automating Notion workflows.