Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.notion.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Log in

Authenticate with your Notion workspace: 
ntn login
This opens your browser to an authorization page. Confirm that the code in the browser matches the code printed in your terminal before approving. This prevents another page from completing the login in your name. Your workspace-scoped token will be stored securely in your system’s keychain. If you’ve already logged in to one or more workspaces, you can pick existing workspace to switch the default, or pick Authenticate with new workspace to start a fresh browser flow and add another workspace.
ntn login requires full workspace membership. Guests and restricted members cannot log in with the Notion CLI. If you need CLI access, ask a workspace admin to upgrade your role. See Personal access tokens for more on who can create tokens.

​
Log in without a browser

On a remote machine, container, or CI runner that can’t open a browser, ntn login automatically falls back to a two-step flow:
  1. Run ntn login on the headless machine. It prints a URL, a verification code, and a ntn login poll command.
  2. Open the URL in any browser, sign in, and confirm the verification code.
  3. Run ntn login poll on the original machine to redeem the token.
Login sessions expire after a short window. If polling fails because the session expired, run ntn login again to start over. For unattended use (CI, scripts, bots), prefer a personal access token instead.

​
Target a specific workspace

To run a single command against a non-default workspace without switching defaults, set NOTION_WORKSPACE_ID: 
NOTION_WORKSPACE_ID=<workspace-id> ntn api v1/users/me
Workspace IDs are listed in the output of ntn debug.

​
Use a personal access token

For unattended use, authenticate with a personal access token (PAT) by exporting it as NOTION_API_TOKEN: 
export NOTION_API_TOKEN=ntn_xxx...
ntn api v1/users/me
NOTION_API_TOKEN takes precedence over anything stored in the keychain, so the same shell can mix ntn login-based commands and PAT-based commands depending on what’s exported.

​
Inspect your session

ntn doctor

​
Log out

ntn logout
This forgets every cached workspace, deletes each one’s token from the keychain, and clears the default workspace. The config.json and workspaces.json files themselves stay in place — run ntn login to repopulate them.

​
Where credentials are stored

Tokens live in your OS credential store (Keychain on macOS, Secret Service on Linux) under the service name notion-cli, with the workspace ID as the account. Two files sit alongside them in the CLI config directory:
  • config.json — CLI version, default workspace per, and the optional keyring toggle.
  • workspaces.json — cached workspace IDs and names for the interactive picker.
The config directory is NOTION_HOME if set, otherwise $XDG_CONFIG_HOME/notion, $HOME/.config/notion, or $HOME/.notion as fallbacks.

​
Opt out of the OS keychain

On systems without a usable keychain, ntn login fails with a keychain error. Common examples include Docker containers, CI runners, SSH sessions to a Linux server, etc. Set NOTION_KEYRING=0 to store tokens in plain JSON at auth.json in the config directory instead. Treat that file like any other secret. 
NOTION_KEYRING=0 ntn login
To make it permanent, set "keyring": false in config.json. The env var always wins.

​
Environment variables

VariablePurpose
NOTION_API_TOKENWhen this is set, it’ll take precedence over ntn login’s keychain entry. Handy for scripts and CI.
NOTION_WORKSPACE_IDOverride the default workspace for a single command.
NOTION_KEYRINGSet to 0 to use file-based storage instead of the OS keychain.
NOTION_HOMEOverride the config directory.
NOTION_ENVSame as --env. Rarely needed.
Run ntn login --help for the full list.