notes
cmdhub adapter

Notion CLI
for cmdhub.

Databases, pages, blocks, and search with command-level schema.

lock Auth: Private session
Quick Install cmdhub get notion

data_object Agent Contract

Agents should start with auth/status and discovery commands, inspect schemas before composition, and treat commands marked as mutating as state-changing operations.

catalog.json Markdown

Output

Use human output for reading, `--json` for one object, and `--jsonl` for pipes.

Auth

Notion private session. Stored locally by the CLI for the selected Notion workspace.

Refs

Prefer list/search, then short refs or piped JSONL. Use `resolve` to inspect cached refs.

Schemas

Use `notion schema` and `catalog.json` to inspect fields, flags, examples, and side effects.

Auth scopes

Notion private session token

terminal Command Reference

Generated from source. Global flags apply to all commands.

Global Flags

--json bool Emit JSON machine output
--jsonl bool Emit JSONL records for piping
--output, -o string Compatibility output mode: json|jsonl. Prefer --json or --jsonl
--view string = summary View mode: summary|full
--profile string = default Config/auth profile
--config string Config path override
--quiet, -q bool Suppress non-essential diagnostics
--debug bool Enable debug diagnostics
--limit int = 50 Maximum items to emit
--page-size int = 50 Requested upstream page size
--cursor string Continuation cursor
--no-paginate bool Fetch only one page
--version, -v bool Print version information
notion auth Manage Notion PAT authentication
#cmd-notion-auth discovery safe

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 Store a Notion Personal Access Token
#cmd-notion-auth-login mutates state

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.

--pat string read the Notion PAT from stdin when set to -
--pat-env string read the Notion PAT from this environment variable
$ notion auth login
$ notion auth login --pat-env NOTION_API_TOKEN
$ printf '%s' "$NOTION_API_TOKEN" | notion auth login --pat -
notion auth logout Remove stored Notion credentials
#cmd-notion-auth-logout mutates state
$ notion auth logout
notion auth refresh Validate the stored Notion PAT
#cmd-notion-auth-refresh mutates state
$ notion auth refresh
notion auth status Show Notion auth status
#cmd-notion-auth-status discovery safe
$ notion auth status
notion auth whoami Show the current Notion user and workspace
#cmd-notion-auth-whoami discovery safe
$ notion auth whoami
notion block Work with Notion blocks
#cmd-notion-block discovery safe

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 Append a block to a Notion page
#cmd-notion-block-append discovery safe

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

--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 = paragraph Block type: paragraph, heading_1, heading_2, heading_3, bulleted_list, numbered_list, to_do, code, quote
$ notion block append --page p1 --body "New block"
notion block delete Delete (trash) one or more Notion blocks
#cmd-notion-block-delete mutates state

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.

--all bool Confirm batch block deletion
--yes bool Confirm destructive batch block deletion
$ notion block list --page p1 --limit 1 --jsonl | notion block delete
notion block get Get one or more Notion blocks by ref
#cmd-notion-block-get discovery safe

Get a Notion block by local marker, URL, or UUID.

Run block list first to populate local block markers from a page.

$ notion block get b1
notion block list List blocks in a Notion page
#cmd-notion-block-list discovery safe

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).

--depth int Max nesting depth (0 = unlimited)
--page string Page reference (marker, URL, or UUID)
$ notion block list --page p1
notion capabilities Describe capabilities
#cmd-notion-capabilities discovery safe
$ notion capabilities
notion config Inspect local configuration
#cmd-notion-config discovery safe
notion config explain Explain resolved configuration
#cmd-notion-config-explain discovery safe
$ notion config explain --help
notion data-source Work with Notion data sources
#cmd-notion-data-source discovery safe

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 Get one or more Notion data sources by ref
#cmd-notion-data-source-get discovery safe

Get a Notion data source by local marker, URL, or UUID.

Returns metadata including title, collection ID, and property schema.

$ notion data-source get ds1
notion data-source list List accessible Notion data sources
#cmd-notion-data-source-list discovery safe

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.

--limit int = 20 Maximum number of results to return
--query string Text query to match database titles
$ notion data-source list --limit 10
notion data-source query Query rows in a Notion data source
#cmd-notion-data-source-query discovery safe

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).

--filter string Filter as raw Notion query JSON
--limit int = 50 Maximum number of rows to return
--query string Text query to match returned page titles and properties
--sort string Sort as raw Notion query JSON
$ notion data-source query ds1 --limit 10
notion database Work with Notion databases
#cmd-notion-database discovery safe

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 Get one or more Notion databases by ref
#cmd-notion-database-get discovery safe

Get a Notion database by local marker, URL, or UUID.

Returns metadata including title, collection ID, and property schema.

$ notion database get d1
notion database list List accessible Notion databases
#cmd-notion-database-list discovery safe

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.

--limit int = 20 Maximum number of results to return
--query string Text query to match database titles
$ notion database list --limit 10
notion database query Query rows in a Notion database
#cmd-notion-database-query discovery safe

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).

--filter string Filter as raw Notion query JSON
--limit int = 50 Maximum number of rows to return
--query string Text query to match returned page titles and properties
--sort string Sort as raw Notion query JSON
$ notion database query d1 --limit 10
notion doctor Run Notion adapter diagnostics
#cmd-notion-doctor discovery safe
$ notion doctor
notion login Store a Notion Personal Access Token
#cmd-notion-login mutates state

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.

--pat string read the Notion PAT from stdin when set to -
--pat-env string read the Notion PAT from this environment variable
$ notion auth login
$ notion auth login --pat-env NOTION_API_TOKEN
$ printf '%s' "$NOTION_API_TOKEN" | notion auth login --pat -
notion logout Remove stored Notion credentials
#cmd-notion-logout mutates state
$ notion auth logout
notion page Work with Notion pages
#cmd-notion-page discovery safe

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 Create a new Notion page
#cmd-notion-page-create mutates state

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.

--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 create --parent d1 --title "New page"
notion page get Get one or more Notion pages by ref
#cmd-notion-page-get discovery safe

Get a Notion page by local marker, URL, or UUID.

Returns page metadata, parent information, and a block summary.

$ notion page get p1
notion page list List Notion pages
#cmd-notion-page-list discovery safe

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.

--database string Database reference (marker, URL, or UUID)
--limit int = 20 Maximum number of results to return
--parent-page string Parent page reference (marker, URL, or UUID)
--query string Text query to match returned page titles and properties
$ notion page list --limit 10
notion page restore Restore one or more Notion pages from trash
#cmd-notion-page-restore discovery safe

Restore a Notion page from trash by local marker, URL, or UUID.

Use this only after selecting the exact trashed page ref.

--all bool Confirm batch page restore
--yes bool Confirm batch page restore
$ notion page restore p1 --yes
notion page trash Move one or more Notion pages to trash
#cmd-notion-page-trash mutates state

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.

--all bool Confirm batch page trash
--yes bool Confirm destructive batch page trash
$ notion page trash p1
notion page update Update a Notion page
#cmd-notion-page-update mutates state

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).

--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 page update p1 --title "Updated title"
notion profile Manage provider profiles
#cmd-notion-profile discovery safe
notion profile create Create an unauthenticated provider profile
#cmd-notion-profile-create mutates state
$ notion profile create --help
notion profile delete Delete a local provider profile
#cmd-notion-profile-delete mutates state
$ notion profile delete --help
notion profile list List provider profiles
#cmd-notion-profile-list discovery safe
$ notion profile list --help
notion profile rename Rename a local provider profile
#cmd-notion-profile-rename discovery safe
$ notion profile rename --help
notion profile use Set the default provider profile
#cmd-notion-profile-use mutates state
$ notion profile use --help
notion resolve Resolve a Notion local marker or shortened canonical reference
#cmd-notion-resolve discovery safe

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.

$ notion resolve p1
notion schema Emit Notion adapter schema hints
#cmd-notion-schema discovery safe

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.

--in bool Show input schema
--input bool Show input schema
--out bool Show output schema
$ notion schema
notion version Show notion version information
#cmd-notion-version discovery safe
$ notion version
notion workspace Search and inspect the Notion workspace
#cmd-notion-workspace discovery safe

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.

play_circle Live Examples

Output captured from a real workspace. Regenerate with scripts/gen-docs.sh --update.

auth

Check current identity
$ notion auth whoami
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
$ notion database list
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
$ notion database get d1
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
$ notion database query d1 --limit 3
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
$ notion page get p1
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
$ notion block list --page p1
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
$ notion workspace search --query eval
Empty state
No search found.

Next steps:
- Pages:        notion page list --limit 10
- Databases:    notion database list --limit 10
- Capabilities: notion capabilities
- Schema:       notion schema

alt_route Composition Patterns

Bridge your ecosystem with zero middleware.

# Review a database row, then inspect the page it points at
notion database query d1 --limit 1 --jsonl \
  | notion page get