https://github.com/4ier/notion-cli
Work seamlessly with Notion from the command line. Full Notion API coverage in a single binary.
https://github.com/4ier/notion-cli
ai-agents cli developer-tools go notion notion-api terminal
Last synced: 3 months ago
JSON representation
Work seamlessly with Notion from the command line. Full Notion API coverage in a single binary.
- Host: GitHub
- URL: https://github.com/4ier/notion-cli
- Owner: 4ier
- License: mit
- Created: 2026-02-18T15:40:23.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-04-06T22:37:11.000Z (3 months ago)
- Last Synced: 2026-04-07T00:28:22.603Z (3 months ago)
- Topics: ai-agents, cli, developer-tools, go, notion, notion-api, terminal
- Language: Go
- Homepage: https://github.com/4ier/notion-cli
- Size: 5.88 MB
- Stars: 109
- Watchers: 0
- Forks: 9
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-notion - Notion CLI - A fast, full-featured command-line interface for Notion with support for pages, databases, blocks, comments, and more. (APIs)
README
notion-cli
Like gh for GitHub, but for Notion. 39 commands. One binary.
---
A full-featured command-line interface for [Notion](https://notion.so). Manage pages, databases, blocks, comments, users, and files — all from your terminal. Built for developers and AI agents who need programmatic access without the browser.
## Install
### Homebrew (macOS/Linux)
```sh
brew install 4ier/tap/notion-cli
```
### Go
```sh
go install github.com/4ier/notion-cli@latest
```
### npm
```sh
npm install -g notion-cli-go
```
### Scoop (Windows)
```powershell
scoop bucket add 4ier https://github.com/4ier/scoop-bucket
scoop install notion-cli
```
### Docker
```sh
docker run --rm -e NOTION_TOKEN ghcr.io/4ier/notion-cli search "meeting"
```
### Binary
Download from [GitHub Releases](https://github.com/4ier/notion-cli/releases) — available for Linux, macOS, and Windows (amd64/arm64).
## Quick Start
```sh
# Authenticate
echo "ntn_xxxxx" | notion auth login --with-token
# Search your workspace
notion search "meeting notes"
# Query a database with filters
notion db query --filter 'Status=Done' --sort 'Date:desc'
# Create a page in a database
notion page create --db "Name=Weekly Review" "Status=Todo"
# Read page content as Markdown
notion block list --depth 3 --md
# Append blocks from a Markdown file
notion block append --file notes.md
# Raw API escape hatch
notion api GET /v1/users/me
```
## Commands
| Group | Commands | Description |
|-------|----------|-------------|
| **auth** | `login` `logout` `status` `switch` `doctor` | Authentication & diagnostics |
| **search** | `search` | Search pages and databases |
| **page** | `view` `list` `create` `delete` `restore` `move` `open` `set` `props` `link` `unlink` | Full page lifecycle |
| **db** | `list` `view` `query` `create` `update` `add` `add-bulk` `open` | Database CRUD + query |
| **block** | `list` `get` `append` `insert` `update` `delete` | Content block operations |
| **comment** | `list` `add` `get` | Discussion threads |
| **user** | `me` `list` `get` | Workspace members |
| **file** | `list` `upload` | File management |
| **api** | ` ` | Raw API escape hatch |
**39 subcommands** covering 100% of the Notion API.
## Features
### Human-Friendly Filters
No JSON needed for 90% of queries:
```sh
notion db query --filter 'Status=Done' --filter 'Priority=High' --sort 'Date:desc'
```
For complex queries (OR, nesting), use the JSON escape hatch:
```sh
notion db query --filter-json '{"or":[{"property":"Status","status":{"equals":"Done"}},{"property":"Status","status":{"equals":"Cancelled"}}]}'
```
### Schema-Aware Properties
Property types are auto-detected from the database schema:
```sh
notion page create --db "Name=Sprint Review" "Date=2026-03-01" "Points=8" "Done=true"
```
### Smart Output
- **Terminal**: Colored tables, formatted text
- **Pipe/Script**: Clean JSON for `jq`, scripts, and AI agents
```sh
# Pretty table in terminal
notion db query
# JSON when piped
notion db query | jq '.results[].properties.Name'
```
### Markdown I/O
```sh
# Read blocks as Markdown
notion block list --md --depth 3
# Write Markdown to Notion
notion block append --file document.md
```
Supports headings, bullets, numbered lists, todos, quotes, code blocks, and dividers.
### Recursive Block Reading
```sh
notion block list --depth 5 --all
```
### URL or ID — Your Choice
```sh
# Both work
notion page view abc123def
notion page view https://notion.so/My-Page-abc123def456
```
### Actionable Error Messages
```
object_not_found: Could not find page with ID abc123
→ Check the ID is correct and the page/database is shared with your integration
```
## For AI Agents
This CLI is designed to be agent-friendly:
- **JSON output** when piped — no parsing needed
- **Schema-aware** — agents don't need to know property types
- **URL resolution** — paste Notion URLs directly
- **Single binary** — no runtime dependencies
- **Exit codes** — 0 for success, non-zero for errors
Install as an agent skill:
```sh
npx skills add 4ier/notion-cli
```
## Configuration
```sh
# Token is stored in ~/.config/notion-cli/config.json (mode 0600)
echo "ntn_xxxxx" | notion auth login --with-token
# Or use environment variable
export NOTION_TOKEN=ntn_xxxxx
# Check authentication
notion auth status
notion auth doctor
```
## Troubleshooting
### Windows: MSYS / Git Bash path mangling
In MSYS-based shells (Git Bash, MSYS2), arguments starting with `/` are silently rewritten to Windows paths. This breaks API path arguments:
```sh
# ✗ /v1/users/me becomes C:/Program Files/Git/v1/users/me
notion api GET /v1/users/me
```
**Fix:** disable MSYS path conversion:
```sh
MSYS_NO_PATHCONV=1 notion api GET /v1/users/me
```
Or export it for the session: `export MSYS_NO_PATHCONV=1`
> This is a shell-level issue, not a bug in notion-cli. PowerShell and cmd.exe are not affected.
## Contributing
Issues and PRs welcome at [github.com/4ier/notion-cli](https://github.com/4ier/notion-cli).
## License
[MIT](LICENSE)