Notion CLI for the Notion API

notion-cli is an open source Go CLI for the Notion API. It helps developers and LLM agents search Notion, manage pages, read and replace markdown content, query data sources, append blocks, create comments, and call raw endpoints from the terminal.

Features

• Easy-to-use Notion CLI with stable --json output
• Multi-profile support for multiple workspaces and tokens
• Markdown-first page content workflows
• Search, pages, page markdown, blocks, comments, data sources, and users me
• raw escape hatch for uncovered Notion API endpoints
• LLM-friendly behavior with predictable machine-readable results

Scope

• Notion API only
• Compatible with the official Notion API and official Notion OpenAPI spec
• The bundled sources include the official openapi.json and llms.txt
• Internal integration token auth is the primary v1 mode

Install

Go

go install github.com/techinpark/notion-cli@latest

Homebrew

brew tap techinpark/tap
brew install techinpark/tap/notion-cloud-cli

Homebrew should install the binary as notion-cloud-cli to avoid name collisions if notion-cli is already taken.

Authentication

notion-cli uses Notion internal integration tokens and supports multiple named profiles.

Environment variables:

• NOTION_TOKEN
• NOTION_PROFILE
• NOTION_DEFAULT_PAGE_ID
• NOTION_DEFAULT_DATA_SOURCE_ID
• NOTION_VERSION

Create a local profile:

notion auth init --profile work \
  --token $NOTION_TOKEN \
  --default-page-id 195de9221179449fab8075a27c979105 \
  --default-data-source-id f336d0bcb841465b8045024475c079dd

Switch profiles:

notion auth list
notion auth use work
notion auth check --profile work

Config file location:

~/.config/notion-cli/config.yaml

Usage

notion search --query 'release notes' --json
notion pages get 195de9221179449fab8075a27c979105
notion pages create --parent-page 195de9221179449fab8075a27c979105 --title 'Release Notes' --markdown '# v1.0'
notion pages markdown get 195de9221179449fab8075a27c979105
notion pages markdown replace 195de9221179449fab8075a27c979105 --file ./page.md
notion blocks children 195de9221179449fab8075a27c979105
notion comments create --page 195de9221179449fab8075a27c979105 --markdown 'Looks good'
notion data-sources query f336d0bcb841465b8045024475c079dd --json

Page properties can be passed as --property key=value. JSON values are supported:

notion pages create \
  --data-source f336d0bcb841465b8045024475c079dd \
  --title 'Prepare release notes' \
  --property Status='{"status":{"name":"In Progress"}}'

Raw API Calls

Use raw when the direct command set does not cover an endpoint yet.

notion raw GET /v1/users/me
notion raw POST /v1/search --body '{"query":"tasks","page_size":20}'

LLM Guide

For LLM agents and automation:

• Prefer --json
• Prefer direct commands for page, markdown, search, and data source workflows
• Use notion raw for uncovered endpoints
• Treat write commands as side-effectful and require explicit IDs and content
• Use named profiles when multiple workspaces or tokens are involved

More details: LLM_GUIDE.md

Security

• Integration tokens may be stored in the local config for convenience
• Use local file permissions and OS account security
• For CI, prefer environment variables over checked-in config
• Never commit real Notion credentials

See SECURITY.md.

Development

go test ./...
go test ./... -cover
go build ./...

Release Automation

Tag pushes matching v* run GoReleaser through GitHub Actions.

Required repository secret:

• TAP_GITHUB_TOKEN: a GitHub personal access token with permission to create releases in techinpark/notion-cli and push formula updates to techinpark/homebrew-tap

Example:

git tag v0.1.1
git push origin v0.1.1

Open Source

• CONTRIBUTING.md
• CHANGELOG.md
• LICENSE