# Notion CLI Databases, pages, blocks, and search with command-level schema. ## Install ```bash cmdhub get notion ``` ## Authentication Private session ## Agent-Readable Catalog - Machine-readable command catalog: `/cli/notion/catalog.json` - Stable command anchors use the `cmd-...` IDs listed under each command. - Inspect this catalog before planning tool use for command paths, examples, flags, mutation markers, and dry-run support. ## Overview ```bash # Review a database row, then inspect the page it points at notion database query d1 --limit 1 --jsonl \ | notion page get ``` ## CLI Overview Notion adapter CLI Work with Notion databases, data sources, pages, blocks, and workspace search. The intended workflow is: - list or workspace search first - follow up with a short ref such as d1, p1, or b1, or pipe jsonl into the next command - use resolve when you need to inspect what a short ref expands to Use --jsonl for self-pipe flows such as: notion database list --limit 1 --jsonl | notion database get notion workspace search --query 'roadmap' --type page --jsonl | notion page get ## Generated Coverage - Command groups: `15` - Total documented command nodes: `43` - Live examples: `7` - Lifecycle surfaces: `auth`, `doctor`, `capabilities`, `schema`, `resolve`, `version` - Machine-readable output: `--json`, `--jsonl` - Human views: `summary`, `full` ## Auth Contract - Auth mode: Private session - Provider permission model: Notion private session - Auth scopes: `Notion private session token` - Scope note: Stored locally by the CLI for the selected Notion workspace. - Standard commands: `auth login`, `auth logout`, `auth refresh`, `auth status`, `auth whoami` - `auth status --json` reports `tool`, `profile`, `provider`, `authenticated`, and `suggested_next_step`. - `auth whoami --json` is the stable way to answer identity questions. ## Agent Safety Notes - Discovery commands such as `list`, `search`, `get`, `resolve`, `schema`, `doctor`, `capabilities`, `status`, and `whoami` are the safest commands to run first. - Treat commands marked as mutating as state-changing local or provider operations. - Mutating command paths: `notion auth login`, `notion auth logout`, `notion auth refresh`, `notion block delete`, `notion login`, `notion logout`, `notion page create`, `notion page trash`, `notion page update`, `notion profile create`, `notion profile delete`, `notion profile use` - No generated `--dry-run` flag was detected for this CLI. Use discovery commands before mutating commands. ## Global Flags - `--json` (bool): Emit JSON machine output - `--jsonl` (bool): Emit JSONL records for piping - `--output` (string): Compatibility output mode: json|jsonl. Prefer --json or --jsonl - `--view` (string): View mode: summary|full Default: `summary`. - `--profile` (string): Config/auth profile Default: `default`. - `--config` (string): Config path override - `--quiet` (bool): Suppress non-essential diagnostics - `--debug` (bool): Enable debug diagnostics - `--limit` (int): Maximum items to emit Default: `50`. - `--page-size` (int): Requested upstream page size Default: `50`. - `--cursor` (string): Continuation cursor - `--no-paginate` (bool): Fetch only one page - `--version` (bool): Print version information ## Command Reference ### `notion auth` - Anchor: `cmd-notion-auth` - Mutates state: `no` - Supports dry run: `no` Manage Notion PAT authentication Manage Notion Personal Access Token authentication for the active profile. Use auth status when commands fail with AUTH_REQUIRED. Use auth login to store a Notion PAT. Use auth whoami to confirm which user or bot the profile points at. #### `notion auth login` - Anchor: `cmd-notion-auth-login` - Mutates state: `yes` - Supports dry run: `no` Store a Notion Personal Access Token Store a Notion Personal Access Token (PAT) for the active profile. This validates the PAT against the Notion REST API and caches the returned identity metadata. Example: ```bash notion auth login notion auth login --pat-env NOTION_API_TOKEN printf '%s' "$NOTION_API_TOKEN" | notion auth login --pat - ``` Flags: - `--pat` (string): read the Notion PAT from stdin when set to - - `--pat-env` (string): read the Notion PAT from this environment variable #### `notion auth logout` - Anchor: `cmd-notion-auth-logout` - Mutates state: `yes` - Supports dry run: `no` Remove stored Notion credentials Example: ```bash notion auth logout ``` #### `notion auth refresh` - Anchor: `cmd-notion-auth-refresh` - Mutates state: `yes` - Supports dry run: `no` Validate the stored Notion PAT Example: ```bash notion auth refresh ``` #### `notion auth status` - Anchor: `cmd-notion-auth-status` - Mutates state: `no` - Supports dry run: `no` Show Notion auth status Example: ```bash notion auth status ``` #### `notion auth whoami` - Anchor: `cmd-notion-auth-whoami` - Mutates state: `no` - Supports dry run: `no` Show the current Notion user and workspace Example: ```bash notion auth whoami ``` ### `notion block` - Anchor: `cmd-notion-block` - Mutates state: `no` - Supports dry run: `no` Work with Notion blocks Get, list, append, and delete Notion blocks within a page. Blocks are referred to by --page where ref is a local marker (p1), URL, or UUID. #### `notion block append` - Anchor: `cmd-notion-block-append` - Mutates state: `no` - Supports dry run: `no` Append a block to a Notion page Append a new block to the end of a Notion page. Use --body to supply text directly, @file to read from a file, or - to read from stdin. When --body - is used, --page must be provided explicitly (stdin is consumed for body text). When --page is omitted, a piped item from a previous command is used as the page reference. Supported block types: paragraph, heading_1, heading_2, heading_3, bulleted_list, numbered_list, to_do, code, quote Example: ```bash notion block append --page p1 --body "New block" ``` Flags: - `--body` (string): Block text content; use @file to read from a file, - to read from stdin - `--checked` (bool): Mark to_do block as checked (only meaningful with --type to_do) - `--page` (string): Page reference (marker, URL, or UUID) - `--type` (string): Block type: paragraph, heading_1, heading_2, heading_3, bulleted_list, numbered_list, to_do, code, quote Default: `paragraph`. #### `notion block delete` - Anchor: `cmd-notion-block-delete` - Mutates state: `yes` - Supports dry run: `no` Delete (trash) one or more Notion blocks Delete a block by local block ref or a piped item from block list. This moves the block to trash (alive=false). It does not permanently delete. Use notion block list --page p1 --jsonl to pipe block items into this command. Example: ```bash notion block list --page p1 --limit 1 --jsonl | notion block delete ``` Flags: - `--all` (bool): Confirm batch block deletion - `--yes` (bool): Confirm destructive batch block deletion #### `notion block get` - Anchor: `cmd-notion-block-get` - Mutates state: `no` - Supports dry run: `no` Get one or more Notion blocks by ref Get a Notion block by local marker, URL, or UUID. Run block list first to populate local block markers from a page. Example: ```bash notion block get b1 ``` #### `notion block list` - Anchor: `cmd-notion-block-list` - Mutates state: `no` - Supports dry run: `no` List blocks in a Notion page List the blocks contained in a Notion page. Returns a structured list of block types and their text content. Use --depth to control how many levels of nesting are returned (default: all). Example: ```bash notion block list --page p1 ``` Flags: - `--depth` (int): Max nesting depth (0 = unlimited) - `--page` (string): Page reference (marker, URL, or UUID) ### `notion capabilities` - Anchor: `cmd-notion-capabilities` - Mutates state: `no` - Supports dry run: `no` Describe capabilities Example: ```bash notion capabilities ``` ### `notion config` - Anchor: `cmd-notion-config` - Mutates state: `no` - Supports dry run: `no` Inspect local configuration #### `notion config explain` - Anchor: `cmd-notion-config-explain` - Mutates state: `no` - Supports dry run: `no` Explain resolved configuration Example: ```bash notion config explain --help ``` ### `notion data-source` - Anchor: `cmd-notion-data-source` - Mutates state: `no` - Supports dry run: `no` Work with Notion data sources List, inspect, and query Notion data sources. Data sources are the queryable tables that live under Notion databases. Run data-source list first to populate local markers for follow-up commands. #### `notion data-source get` - Anchor: `cmd-notion-data-source-get` - Mutates state: `no` - Supports dry run: `no` Get one or more Notion data sources by ref Get a Notion data source by local marker, URL, or UUID. Returns metadata including title, collection ID, and property schema. Example: ```bash notion data-source get ds1 ``` #### `notion data-source list` - Anchor: `cmd-notion-data-source-list` - Mutates state: `no` - Supports dry run: `no` List accessible Notion data sources List Notion data sources accessible to the current PAT. This searches the workspace for queryable database-like content and assigns local markers (ds1, ...) for follow-up commands. Use --query to narrow results by title. Example: ```bash notion data-source list --limit 10 ``` Flags: - `--limit` (int): Maximum number of results to return Default: `20`. - `--query` (string): Text query to match database titles #### `notion data-source query` - Anchor: `cmd-notion-data-source-query` - Mutates state: `no` - Supports dry run: `no` Query rows in a Notion data source Query rows in a Notion database or data source. Returns page rows with their titles and properties. Use --query for simple text matching across titles/properties. Use --filter and --sort for advanced queries (raw Notion query JSON). Example: ```bash notion data-source query ds1 --limit 10 ``` Flags: - `--filter` (string): Filter as raw Notion query JSON - `--limit` (int): Maximum number of rows to return Default: `50`. - `--query` (string): Text query to match returned page titles and properties - `--sort` (string): Sort as raw Notion query JSON ### `notion database` - Anchor: `cmd-notion-database` - Mutates state: `no` - Supports dry run: `no` Work with Notion databases List, inspect, and query Notion databases. Databases are referred to by local marker (d1), Notion URL, or UUID. Run database list first to populate local markers. #### `notion database get` - Anchor: `cmd-notion-database-get` - Mutates state: `no` - Supports dry run: `no` Get one or more Notion databases by ref Get a Notion database by local marker, URL, or UUID. Returns metadata including title, collection ID, and property schema. Example: ```bash notion database get d1 ``` #### `notion database list` - Anchor: `cmd-notion-database-list` - Mutates state: `no` - Supports dry run: `no` List accessible Notion databases List Notion databases accessible to the current PAT. This searches the workspace for queryable database-like content and assigns local markers (d1, ...) for follow-up commands. Use --query to narrow results by title. Example: ```bash notion database list --limit 10 ``` Flags: - `--limit` (int): Maximum number of results to return Default: `20`. - `--query` (string): Text query to match database titles #### `notion database query` - Anchor: `cmd-notion-database-query` - Mutates state: `no` - Supports dry run: `no` Query rows in a Notion database Query rows in a Notion database or data source. Returns page rows with their titles and properties. Use --query for simple text matching across titles/properties. Use --filter and --sort for advanced queries (raw Notion query JSON). Example: ```bash notion database query d1 --limit 10 ``` Flags: - `--filter` (string): Filter as raw Notion query JSON - `--limit` (int): Maximum number of rows to return Default: `50`. - `--query` (string): Text query to match returned page titles and properties - `--sort` (string): Sort as raw Notion query JSON ### `notion doctor` - Anchor: `cmd-notion-doctor` - Mutates state: `no` - Supports dry run: `no` Run Notion adapter diagnostics Example: ```bash notion doctor ``` ### `notion login` - Anchor: `cmd-notion-login` - Mutates state: `yes` - Supports dry run: `no` Store a Notion Personal Access Token Store a Notion Personal Access Token (PAT) for the active profile. This validates the PAT against the Notion REST API and caches the returned identity metadata. Example: ```bash notion auth login notion auth login --pat-env NOTION_API_TOKEN printf '%s' "$NOTION_API_TOKEN" | notion auth login --pat - ``` Flags: - `--pat` (string): read the Notion PAT from stdin when set to - - `--pat-env` (string): read the Notion PAT from this environment variable ### `notion logout` - Anchor: `cmd-notion-logout` - Mutates state: `yes` - Supports dry run: `no` Remove stored Notion credentials Example: ```bash notion auth logout ``` ### `notion page` - Anchor: `cmd-notion-page` - Mutates state: `no` - Supports dry run: `no` Work with Notion pages Get and modify Notion pages. Pages are referred to by local marker (p1), Notion URL, or UUID. Run database query or workspace search first to populate local page markers. #### `notion page create` - Anchor: `cmd-notion-page-create` - Mutates state: `yes` - Supports dry run: `no` Create a new Notion page Create a new Notion page within a database. Use --body to append a paragraph block to the new page. Supports inline text, @file to read from a file, or - to read body from stdin (parent is always explicit). Creating child pages directly under top-level pages is not supported by the current Notion REST write path; create the page in a database contained by that page. Example: ```bash notion page create --parent d1 --title "New page" ``` Flags: - `--body` (string): Body paragraph text; use @file to read from file, - to read from stdin - `--parent` (string): Parent page or database reference - `--properties` (string): Raw Notion properties JSON object - `--title` (string): Page title #### `notion page get` - Anchor: `cmd-notion-page-get` - Mutates state: `no` - Supports dry run: `no` Get one or more Notion pages by ref Get a Notion page by local marker, URL, or UUID. Returns page metadata, parent information, and a block summary. Example: ```bash notion page get p1 ``` #### `notion page list` - Anchor: `cmd-notion-page-list` - Mutates state: `no` - Supports dry run: `no` List Notion pages List Notion pages from the workspace, a database, or a parent page. With no selector, this lists recent pages from workspace search. Use --database to list rows from a database. Use --parent-page to list direct child pages under a parent page. Use --query to narrow returned pages by title or property text. Example: ```bash notion page list --limit 10 ``` Flags: - `--database` (string): Database reference (marker, URL, or UUID) - `--limit` (int): Maximum number of results to return Default: `20`. - `--parent-page` (string): Parent page reference (marker, URL, or UUID) - `--query` (string): Text query to match returned page titles and properties #### `notion page restore` - Anchor: `cmd-notion-page-restore` - Mutates state: `no` - Supports dry run: `no` Restore one or more Notion pages from trash Restore a Notion page from trash by local marker, URL, or UUID. Use this only after selecting the exact trashed page ref. Example: ```bash notion page restore p1 --yes ``` Flags: - `--all` (bool): Confirm batch page restore - `--yes` (bool): Confirm batch page restore #### `notion page trash` - Anchor: `cmd-notion-page-trash` - Mutates state: `yes` - Supports dry run: `no` Move one or more Notion pages to trash Move a Notion page to trash by local marker, URL, or UUID. This is an idempotent operation. Trashed pages can be restored with notion page restore. Example: ```bash notion page trash p1 ``` Flags: - `--all` (bool): Confirm batch page trash - `--yes` (bool): Confirm destructive batch page trash #### `notion page update` - Anchor: `cmd-notion-page-update` - Mutates state: `yes` - Supports dry run: `no` Update a Notion page Update a Notion page title and optionally append body text. Use --body to append a paragraph block to the page. Supports inline text, @file to read from a file, or - to read body from stdin (page ref must then be a positional argument — stdin cannot carry both the ref and body text). Example: ```bash notion page update p1 --title "Updated title" ``` Flags: - `--body` (string): Body paragraph to append; use @file to read from file, - to read from stdin - `--properties` (string): Raw Notion properties JSON object - `--title` (string): New page title ### `notion profile` - Anchor: `cmd-notion-profile` - Mutates state: `no` - Supports dry run: `no` Manage provider profiles #### `notion profile create` - Anchor: `cmd-notion-profile-create` - Mutates state: `yes` - Supports dry run: `no` Create an unauthenticated provider profile Example: ```bash notion profile create --help ``` #### `notion profile delete` - Anchor: `cmd-notion-profile-delete` - Mutates state: `yes` - Supports dry run: `no` Delete a local provider profile Example: ```bash notion profile delete --help ``` #### `notion profile list` - Anchor: `cmd-notion-profile-list` - Mutates state: `no` - Supports dry run: `no` List provider profiles Example: ```bash notion profile list --help ``` #### `notion profile rename` - Anchor: `cmd-notion-profile-rename` - Mutates state: `no` - Supports dry run: `no` Rename a local provider profile Example: ```bash notion profile rename --help ``` #### `notion profile use` - Anchor: `cmd-notion-profile-use` - Mutates state: `yes` - Supports dry run: `no` Set the default provider profile Example: ```bash notion profile use --help ``` ### `notion resolve` - Anchor: `cmd-notion-resolve` - Mutates state: `no` - Supports dry run: `no` Resolve a Notion local marker or shortened canonical reference Resolve a Notion short reference into its canonical payload. Use this when you have a marker such as d1, p1, or b1, or a shortened canonical id, and want to inspect what it refers to. Resolution is profile-scoped. If a marker does not resolve, verify --profile and rerun the relevant list command. Example: ```bash notion resolve p1 ``` ### `notion schema` - Anchor: `cmd-notion-schema` - Mutates state: `no` - Supports dry run: `no` Emit Notion adapter schema hints Show schema hints for the Notion resource payloads emitted by this CLI. Use this when you need to understand structured output fields for automation or downstream parsing. Example: ```bash notion schema ``` Flags: - `--in` (bool): Show input schema - `--input` (bool): Show input schema - `--out` (bool): Show output schema ### `notion version` - Anchor: `cmd-notion-version` - Mutates state: `no` - Supports dry run: `no` Show notion version information Example: ```bash notion version ``` ### `notion workspace` - Anchor: `cmd-notion-workspace` - Mutates state: `no` - Supports dry run: `no` Search and inspect the Notion workspace Search workspace content visible to the current Notion PAT. Use workspace search when you need mixed page and database discovery before selecting a local ref. #### `notion workspace search` - Anchor: `cmd-notion-workspace-search` - Mutates state: `no` - Supports dry run: `no` Search Notion for pages, databases, and data sources Search the Notion workspace for pages, databases, and data sources matching a query. Assigns local markers (p1, d1, ds1, ...) for follow-up commands. Example: ```bash notion workspace search --query "roadmap" --limit 10 ``` Flags: - `--in-trash` (string): Filter by trash state: true or false - `--limit` (int): Maximum number of results to return Default: `20`. - `--query` (string): Search query text - `--type` (string): Filter by type: page, database, or data-source ## Live Examples ### Auth #### Check current identity Returns the authenticated user and workspace. _Example metadata: requires auth; provider state: live._ ```bash notion auth whoami ``` ```text Authenticated as kestrelphilip@gmail.com Next steps: - Pages: notion page list --limit 10 - Databases: notion database list --limit 10 - Capabilities: notion capabilities - Schema: notion schema ``` ### Databases #### List accessible databases Lists all databases visible to the current PAT profile. _Example metadata: requires auth; provider state: live._ ```bash notion database list ``` ```text REF SOURCE_REFS WHEN d1 ds1 Fri 24 Apr 16:31 d2 ds2 Wed 15 Apr 10:27 d3 ds3 Wed 15 Apr 09:28 Next steps: - Open: notion database get d1 - Pages: notion page list --limit 10 - Databases: notion database list --limit 10 - Capabilities: notion capabilities ``` #### Inspect a database Shows schema and metadata for a database. _Example metadata: requires auth; provider state: live._ ```bash notion database get d1 ``` Error: ```text NOT_FOUND: database reference "d1" not found Next steps: - Pages: notion page list --limit 10 - Databases: notion database list --limit 10 exit status 50 ``` #### Query a database Returns rows from a database and assigns page refs. _Example metadata: requires auth; provider state: live._ ```bash notion database query d1 --limit 3 ``` Error: ```text NOT_FOUND: database reference "d1" not found Next steps: - Pages: notion page list --limit 10 - Databases: notion database list --limit 10 exit status 50 ``` ### Pages #### Get a page Returns title, parent, properties, and block count. _Example metadata: requires auth; provider state: live._ ```bash notion page get p1 ``` Error: ```text NOT_FOUND: page reference "p1" not found Next steps: - Pages: notion page list --limit 10 - Databases: notion database list --limit 10 exit status 50 ``` ### Blocks #### List page blocks Lists the blocks inside a page as a readable outline. _Example metadata: requires auth; provider state: live._ ```bash notion block list --page p1 ``` Error: ```text NOT_FOUND: page reference "p1" not found Next steps: - Pages: notion page list --limit 10 - Databases: notion database list --limit 10 exit status 50 ``` ### Search #### Search the workspace Full-text search across pages, databases, and data sources. _Example metadata: requires auth; provider state: live._ ```bash notion workspace search --query eval ``` ```text No search found. Next steps: - Pages: notion page list --limit 10 - Databases: notion database list --limit 10 - Capabilities: notion capabilities - Schema: notion schema ```