Like gh for GitHub, but for Notion. 47 commands. One binary.
A full-featured command-line interface for Notion. 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.
npm install -g @vibelabsio/notion-agent-cligo install github.com/MaxMa04/notion-agent-cli@latestcurl -fsSL https://raw.githubusercontent.com/MaxMa04/notion-agent-cli/main/install.sh | shDownload from GitHub Releases — available for Linux, macOS, and Windows (amd64/arm64).
# Authenticate
notion-agent auth login
# Or pipe token directly
echo "ntn_xxxxx" | notion-agent auth login --with-token
# Search your workspace
notion-agent search "meeting notes"
# Query a database with filters
notion-agent db query <db-id> --filter 'Status=Done' --sort 'Date:desc'
# Create a page in a database
notion-agent page create <db-id> --db "Name=Weekly Review" "Status=Todo"
# Apply a template to a new page
notion-agent page apply-template <page-id> <template-page-id>
# Read page content as Markdown
notion-agent block list <page-id> --depth 3 --md
# Append blocks from a Markdown file
notion-agent block append <page-id> --file notes.md
# Create a table
notion-agent block table <page-id> "Name,Status,Date" "Task 1,Done,2026-03-10"
# Raw API escape hatch
notion-agent api GET /v1/users/me| Group | Commands | Description |
|---|---|---|
| auth | login logout status doctor switch |
Authentication, diagnostics & profile management |
| search | search |
Search pages and databases |
| page | view list create delete restore move open set props edit link unlink apply-template |
Full page lifecycle + templates |
| db | list view query create update add add-bulk export open |
Database CRUD, query & export |
| block | list get append insert update delete move table table-add |
Content blocks + native tables |
| comment | list add get reply |
Discussion threads |
| user | me list get |
Workspace members |
| file | list upload |
File management |
| api | <METHOD> <path> |
Raw API escape hatch |
47 subcommands covering 100% of the Notion API.
Manage multiple Notion workspaces with named profiles:
# Login with a named profile
notion-agent auth login --profile work
notion-agent auth login --profile personal
# Switch active profile
notion-agent auth switch work
# Use a profile for a single command
notion-agent search "project" --profile work
# Or set via environment variable
export NOTION_PROFILE=workPriority: NOTION_TOKEN env > --profile flag > NOTION_PROFILE env > current profile in config.
No JSON needed for 90% of queries:
notion-agent db query <id> --filter 'Status=Done' --filter 'Priority=High' --sort 'Date:desc'For complex queries (OR, nesting), use the JSON escape hatch:
notion-agent db query <id> --filter-json '{"or":[{"property":"Status","status":{"equals":"Done"}},{"property":"Status","status":{"equals":"Cancelled"}}]}'Property types are auto-detected from the database schema:
notion-agent page create <db-id> --db "Name=Sprint Review" "Date=2026-03-01" "Points=8" "Done=true"Copy the content structure from any page to another — useful for applying task templates, meeting note formats, etc.:
# Create a task and apply a template
notion-agent db add <db-id> "Name=New Task" "Status=Backlog"
notion-agent page apply-template <new-page-id> <template-page-id>Recursively copies all blocks including nested children (tables, toggle content, etc.).
Create and extend tables directly:
# Create a table (first arg = headers, rest = rows)
notion-agent block table <page-id> "Name,Status,Due" "Task 1,Done,2026-03-10" "Task 2,Open,2026-03-15"
# Add rows to an existing table
notion-agent block table-add <table-block-id> "Task 3,In Progress,2026-03-20"- Terminal: Colored tables, formatted text
- Pipe/Script: Clean JSON for
jq, scripts, and AI agents
# Pretty table in terminal
notion-agent db query <id>
# JSON when piped
notion-agent db query <id> | jq '.results[].properties.Name'# Read blocks as Markdown
notion-agent block list <page-id> --md --depth 3
# Write Markdown to Notion
notion-agent block append <page-id> --file document.mdSupports headings, bullets, numbered lists, todos, quotes, code blocks, tables, and dividers.
Open a page in your text editor, edit as Markdown, save to sync back:
notion-agent page edit <page-id>
notion-agent page edit <page-id> --editor codenotion-agent db export <db-id> --format csv > tasks.csv
notion-agent db export <db-id> --format json > tasks.json
notion-agent db export <db-id> --format md > tasks.mdnotion-agent block list <page-id> --depth 5 --all# Both work
notion-agent page view abc123def
notion-agent page view https://notion.so/My-Page-abc123def456object_not_found: Could not find page with ID abc123
-> Check the ID is correct and the page/database is shared with your integration
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
- Template support — apply consistent page structures automatically
- Multi-profile — agents can target specific workspaces via
--profileorNOTION_PROFILE - Single binary — no runtime dependencies
- Exit codes — 0 for success, non-zero for errors
# Interactive login
notion-agent auth login
# Pipe token (non-interactive, CI-friendly)
echo "ntn_xxxxx" | notion-agent auth login --with-token
# Or use environment variable (no config needed)
export NOTION_TOKEN=ntn_xxxxx
# Config stored in ~/.config/notion-agent-cli/config.json (mode 0600)
# Legacy path ~/.config/notion-cli/ is auto-detected
# Check authentication
notion-agent auth status
notion-agent auth doctor
# Manage profiles
notion-agent auth login --profile work
notion-agent auth switch work
notion-agent auth logout workThis project is based on notion-cli by 4ier.
Issues and PRs welcome at github.com/MaxMa04/notion-agent-cli.