ntn: The Notion CLI

A command-line interface for Notion.

Installation

macOS and Linux:

curl -fsSL https://ntn.dev | bash

Windows:

winget install --exact --id Notion.ntn

Verify the Windows installation:

Get-Command ntn
ntn --version
winget list --exact --id Notion.ntn

PowerShell completions

Enable completions for the current PowerShell session:

ntn completions powershell | Out-String | Invoke-Expression

To enable them for future sessions, add the same command to your PowerShell profile:

$completionSetup = 'ntn completions powershell | Out-String | Invoke-Expression'
if (-not (Test-Path $PROFILE)) {
    New-Item -ItemType File -Path $PROFILE -Force | Out-Null
}
if (-not (Select-String -Path $PROFILE -SimpleMatch $completionSetup -Quiet)) {
    Add-Content -Path $PROFILE -Value $completionSetup
}
. $PROFILE

Windows PowerShell 5.1 and PowerShell 7 use different $PROFILE files. Run the setup in each shell if you use both.

WinGet installs ntn but does not modify your PowerShell profile.

What this is for

ntn is the Notion CLI for authenticating with Notion and managing Notion Workers from your terminal. It is focused on Workers development and operation.

Basic command overview

Use these commands to authenticate:

ntn login
ntn logout

Workers functionality is nested under the workers command namespace:

ntn workers --help
ntn workers list
ntn workers deploy

The public Notion API is available under the api command namespace:

ntn api ls
ntn api v1/pages --spec -X POST
ntn api v1/pages --docs -X POST

There is also a convenience wrapper for the File Uploads API:

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

ntn files create is intentionally quiet on success. For byte uploads it only shows a progress bar when stderr is a TTY.

Public API request syntax

ntn api supports inline request inputs:

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

# JSON body string assignment
ntn api v1/pages parent[page_id]=abc123

# Typed JSON assignment
ntn api v1/pages archived:=true properties[count]:=10

# Query params and headers
ntn api v1/users page_size==100 Accept:application/json

Supported forms:

• Header:Value for request headers
• name==value for query params
• path=value for JSON string body fields
• path:=json for typed JSON body fields

Body paths support nested objects and arrays:

ntn api v1/pages \
  parent[page_id]=abc123 \
  children[][paragraph][rich_text][0][text][content]=Hello

Method selection stays simple:

• GET by default
• POST automatically when stdin JSON, --data, or inline body fields are present
• -X/--method always wins

Shell completion can also suggest public API paths and, for -X/--method, only the methods supported by the selected path.

Use exactly one request-body source at a time: stdin JSON, --data, or inline body fields.

See docs/PUBLIC_API_REQUESTS.md for the full reference, including:

• the complete inline parser syntax
• body path and array rules
• multipart upload behavior
• ls, --spec, and --docs
• verbose logging and environment variables

Building from source

Clone the repository and install mise, which manages toolchains and task running. Then build:

git clone https://github.com/makenotion/cli.git
cd cli
mise build

To rebuild automatically when files change:

mise watch build

To rebuild and refresh /usr/local/bin/ntnd automatically when files change:

mise watch release:local

mise watch uses watchexec; this repository declares it in mise.toml, so mise will install it if needed.

To do a one-time install of the current debug build:

mise release:local

By default this installs the debug build as ntnd at /usr/local/bin/ntnd, which avoids colliding with a production ntn install.

To replace the ntn binary already on your PATH instead:

mise release:local --overwrite

Design

See this page for some of our design goals and inspiration with ntn (built by Claude).

Documentation

See the docs/ directory for additional documentation:

• docs/PUBLIC_API_REQUESTS.md for the complete ntn api request reference
• docs/HIDDEN.md for hidden commands and flags not shown in --help output