notioncli

A CLI for the Notion API. Aliases instead of UUIDs, property names as flags, full CRUD, automatic pagination, rate limit retry. Built for humans and AI agents.

npm install -g @jordancoin/notioncli

---

Setup

1. Create a Notion Integration

Go to notion.so/profile/integrations → New integration → copy the API key (ntn_...)

2. Share Your Databases

In Notion, open each database → ••• menu → Connections → add your integration.

3. Initialize

notion init --key ntn_your_api_key_here

✅ API key saved

Found 3 databases:
  ✅ project-tracker  → Project Tracker
  ✅ reading-list     → Reading List
  ✅ meeting-notes    → Meeting Notes

3 aliases saved. Try: notion query project-tracker

Aliases are created automatically from database names. Rename them anytime:

notion alias rename project-tracker projects

---

Commands

Command	Description	Example
query	Query a database	notion query projects --filter Status=Active
add	Create a page	notion add projects --name "Ship it" --status "Todo"
update	Update a page	notion update projects --filter "Name=Ship it" --status "Done"
delete	Archive a page	notion delete projects --filter "Name=Old task"
get	View page details	notion get projects --filter "Name=Ship it"
props	Quick property view	notion props projects --filter "Name=Ship it"
blocks	View page content	notion blocks projects --filter "Name=Ship it" --ids
block-edit	Edit a block	notion block-edit <block-id> "New text"
block-delete	Delete a block	notion block-delete <block-id>
append	Add content to a page	notion append projects "Update: shipped!" --filter "Name=Ship it"
search	Search everything	notion search "meeting"
dbs	List all databases	notion dbs
relations	Explore linked pages	notion relations tasks --filter "Name=Ship it"
comments	View page comments	notion comments tasks --filter "Name=Ship it"
comment	Add a comment	notion comment tasks "Done! 🚀" --filter "Name=Ship it"
users	List workspace users	notion users
me	Show bot identity	notion me
move	Move page between DBs	notion move tasks --filter "Name=Done" --to archive
templates	List DB templates	notion templates projects
db-create	Create a database	notion db-create <parent-id> "Tasks" --prop "Name:title"
db-update	Update DB schema	notion db-update projects --add-prop "Rating:number"
upload	Upload file to page	notion upload tasks --filter "Name=Ship it" ./file.png
import	Import file as pages	notion import projects ./data.csv
export	Export page as markdown	notion export projects --filter "Name=Ship it"
alias	Manage aliases	notion alias list
workspace	Manage workspaces	notion workspace list

---

Examples

Query with filters and sorting

$ notion query projects --filter Status=Active --sort Date:desc --limit 5

Date       │ Name            │ Status │ Priority
───────────┼─────────────────┼────────┼──────────
2026-02-09 │ Launch CLI      │ Active │ High
2026-02-08 │ Write Docs      │ Active │ Medium

2 results

Rich filter operators

# Comparison operators
notion query tasks --filter "Priority>3"
notion query tasks --filter "Count>=10"
notion query tasks --filter "Status!=Draft"

# Multiple filters (AND)
notion query tasks --filter Status=Active --filter Priority=High

# Relative dates
notion query tasks --filter "Due=today"
notion query tasks --filter "Created>=last_week"

# Values containing operators (parsed correctly)
notion query tasks --filter "Description=score>=90"
notion query tasks --filter 'Notes="contains quotes"'

Dynamic property flags

Property names from your database schema become CLI flags automatically:

# Instead of --prop "Name=Ship it" --prop "Status=Done":
notion add projects --name "Ship it" --status "Done" --priority "High"
notion update projects --filter "Name=Ship it" --status "Complete"

Import data

# CSV or JSON → database pages
notion import projects ./tasks.csv
notion import projects ./data.json

# Markdown → page with content blocks
notion add projects --name "My Notes" --from notes.md

Export content

# Page content → markdown
notion export projects --filter "Name=Ship it"
# Outputs: # Ship it\n\nPage content as markdown...

View page details (relations auto-resolved)

$ notion get tasks --filter "Name=Implement relations"

Page: a1b2c3d4-5678-90ab-cdef-1234567890ab
URL:  https://www.notion.so/...

Properties:
  Name: Implement relations
  Project: Build CLI              ← relation resolved to title
  Done: ✓
  Task Count: 3                   ← rollup parsed to number

Multi-workspace

notion workspace add work --key ntn_work_key
notion workspace add personal --key ntn_personal_key
notion workspace use work
notion init   # discovers databases for active workspace

# Per-command override
notion query tasks --workspace personal
notion -w work add projects --name "Q2 Plan"

Output formats

notion query tasks --output table   # default
notion query tasks --output csv
notion query tasks --output json
notion query tasks --output yaml
notion --json query tasks           # raw API response (pipe to jq)

---

AI Agent Usage

notioncli works well as a tool for LLMs and coding agents — no API key juggling, no JSON formatting, just shell commands:

notion dbs                                    # discover databases
notion alias list                             # see available aliases
notion query tasks --filter Status=Todo       # read data
notion add tasks --name "Fix bug" --status "In Progress"   # write data
notion --json query tasks --limit 10          # structured output for parsing

Every page-targeted command accepts alias + --filter instead of UUIDs:

# No UUIDs needed — ever
notion update projects --filter "Name=Ship it" --status "Done"
notion delete projects --filter "Name=Old task"
notion blocks projects --filter "Name=Ship it" --ids

---

Configuration

Config lives at ~/.config/notioncli/config.json. API key resolution: NOTION_API_KEY env var → config file.

notion alias list       # see aliases
notion alias add tasks <database-id>   # manual alias
notion workspace list   # see workspaces

---

Reliability

• Automatic pagination — All list endpoints fetch every result by default. Use --limit to cap.
• Rate limit retry — 429 responses trigger exponential backoff with jitter (up to 5 attempts). Transparent — no flags needed.
• Input validation — Numbers, dates, URLs, and emails are validated before hitting the API. Clear error messages instead of cryptic 400s.

Technical Details

For API internals, the 2025 dual-ID system, modular architecture, and testing (213 tests): see TECHNICAL.md.

---

License

MIT © JordanCoin