You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Foundation document for building a comprehensive Notion CLI tool.
Based on ntn CLI v0.18.1 (Beta) analysis and Notion API (version 2026-03-11) reference.
1. ntn CLI Capabilities & Limitations
What ntn Does
Area
Commands
Notes
Auth
login, logout, whoami
OAuth browser flow; keychain or file-based storage
Pages
pages get/create/edit/trash
Markdown-centric CRUD with frontmatter properties
Data Sources
datasources query/resolve
Query via data source ID (not database ID directly)
Files
files create/get/list
Upload from stdin or URL; list has no pagination
Generic API
api ls, api <PATH>
Call any public endpoint; inline body/query syntax
Explicit filters: --filter-json accepts the exact Notion filter contract
Rate-limit aware: built-in retry with exponential backoff
Command Tree
notion
├── auth
│ ├── login # Store token (prompt or --token flag)
│ ├── logout # Remove stored token
│ ├── whoami # Show current user/workspace info
│ └── switch <profile> # Switch named profile
│
├── search <query> # POST /v1/search
│ ├── --filter page|data_source
│ ├── --sort relevance|last_edited
│ └── --limit N / --all
│
├── page
│ ├── get <page_id> # Retrieve page properties
│ ├── content <page_id> # Get page content as markdown
│ ├── create # Create page (--parent, --parent-type page|data-source)
│ ├── update <page_id> # Update properties, icon, cover, lock, archive
│ ├── edit <page_id> # Replace content (markdown via stdin or --content)
│ ├── move <page_id> # Move to page/data-source parent (--parent, --parent-type)
│ ├── trash <page_id> # Soft-delete
│ ├── restore <page_id> # Restore from trash
│ └── prop <page_id> <property_id> # Get single property (paginated)
│
├── db
│ ├── get <db_id> # Retrieve database schema
│ ├── create # Create database (--parent, --title, --props-json)
│ ├── update <db_id> # Update schema, title, description
│ ├── query <ds_id> # Query a data source with filters and sorts
│ │ ├── --filter-json <JSON>
│ │ ├── --sort <prop> [asc|desc]
│ │ ├── --props <prop1,prop2> # filter_properties
│ │ └── --limit N / --all
│ ├── list # List data sources via search
│ └── trash <db_id> # Archive database
│
├── block
│ ├── get <block_id> # Retrieve single block
│ ├── children <block_id> # List children (--recursive for full tree)
│ ├── append <block_id> # Append children (--content markdown, or --blocks-json)
│ ├── update <block_id> # Update block content
│ ├── delete <block_id> # Soft-delete
│ └── move <block_id> # Move block (--after, --parent)
│
├── comment
│ ├── list # List comments (--block-id or --page-id)
│ ├── get <comment_id> # Retrieve comment
│ ├── create # Create comment (--page, --block, or --discussion for reply)
│ ├── update <comment_id> # Update comment text
│ └── delete <comment_id> # Delete comment
│
├── user
│ ├── me # Current bot/user
│ ├── get <user_id> # Retrieve user
│ └── list # List workspace users
│
├── file
│ ├── upload <path> # Upload file (or stdin)
│ ├── get <file_id> # Retrieve file metadata
│ └── list # List uploads
│
├── view
│ ├── list <db_id> # List views for database
│ ├── get <view_id> # Retrieve view
│ ├── create <db_id> # Create view
│ ├── update <view_id> # Update view
│ ├── delete <view_id> # Delete view
│ └── query <view_id> # Query view results
│
├── datasource
│ ├── get <ds_id> # Retrieve data source
│ ├── query <ds_id> # Query data source
│ ├── resolve <db_id> # Map database ID to data source IDs
│ └── templates # List data source templates
│
├── api <method> <path> # Raw API escape hatch (like ntn api)
│ ├── --data <JSON>
│ ├── --header <K:V>
│ └── --query <K=V>
│
└── config
├── get <key> # Read config value
├── set <key> <value> # Set config value
└── list # Show all config
Filter DSL (planned)
The current CLI intentionally accepts only --filter-json. A future DSL may compile
human-friendly expressions to Notion filter JSON once property-type resolution is defined.
# Current syntax
--filter-json '{"property": "Status", "status": {"equals": "Done"}}'
Output Formats
All commands support:
--json -- full API response JSON
--plain -- human-readable text (default for TTY)
--yaml -- YAML output
--csv -- CSV (for db query, user list, etc.)
--tsv -- TSV variant
--id-only -- just print IDs (for piping)
Global Flags
--token <TOKEN> # Override auth token
--workspace <ID> # Override workspace
--profile <NAME> # Use named profile
--api-version <VER> # Override Notion-Version header
--verbose # Debug output to stderr
--dry-run # Show what would be sent without executing
--no-color # Disable color output