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 normal reads, `--json` for scripting or complete structured fields, and `--jsonl` for upstream pipe inputs.

Auth

Notion Personal Access Token. 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 Personal Access 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 --help

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 --help

notion block append Append a block to a Notion page or block

#cmd-notion-block-append discovery safe

Append a new block to a Notion page or block.

Use –body to supply text directly, @file to read from a file, or - to read from stdin. When –body - is used, –parent or –page must be provided explicitly (stdin is consumed for body text). When –parent is omitted, a piped item from a previous command is used as the parent reference.

Supported block types: paragraph, heading_1, heading_2, heading_3, bulleted_list_item, numbered_list_item, to_do, code, quote, callout, divider, toggle

--after-block string Block ref used when --position after-block

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

--parent string Parent page or block reference (marker, URL, or UUID)

--position string = end Insert position: start, end, or after-block

--type string = paragraph Block type: paragraph, heading_1, heading_2, heading_3, bulleted_list_item, numbered_list_item, to_do, code, quote, callout, divider, toggle

$ notion block append --page p1 --body "New block"

notion block delete Delete (trash) one or more Notion blocks

#cmd-notion-block-delete mutates state dry-run

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

--dry-run bool Preview block deletion without changing Notion

--yes bool Confirm destructive 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. By default this lists direct children with provider pagination. Use –depth >1 for recursive page-chunk inspection.

--depth int = 1 Max nesting depth (1 = direct children; >1 uses recursive page chunk)

--page string Page reference (marker, URL, or UUID)

$ notion block list --page p1

notion block update Update a Notion block

#cmd-notion-block-update mutates state

Update text-like Notion block content or a to-do checked state.

--body string Updated block text; use @file or -

--set-checked bool Set to-do checked state to true

--type string = paragraph Block type to update

--unset-checked bool Set to-do checked state to false

$ notion block update b1 --body "Updated block"

notion capabilities Describe capabilities

#cmd-notion-capabilities discovery safe

--section string Show one capability section: scopes, schemas, or commands

$ notion capabilities

notion comment Work with Notion comments

#cmd-notion-comment mutates state

$ notion comment --help

notion comment create Create a Notion comment

#cmd-notion-comment-create mutates state

--body string Comment body text; use @file or -

--page string Page or block reference

$ notion comment create --page p1 --body "Looks good"

notion comment list List comments on a Notion page or block

#cmd-notion-comment-list discovery safe

--page string Page or block reference

$ notion comment list --page p1

notion config Inspect local configuration

#cmd-notion-config discovery safe

$ notion config --help

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 --help

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.

--database string Database reference to list data sources under

--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 data-source trash Move one or more Notion data sources to trash

#cmd-notion-data-source-trash mutates state dry-run

Trash an exact data-source ref. Single-target calls preview by default and require –yes to mutate.

--all bool Confirm batch data-source trash

--dry-run bool Preview data-source trash without changing Notion

--yes bool Confirm destructive data-source trash

$ notion data-source trash ds1 --yes

notion data-source update Update a Notion data source

#cmd-notion-data-source-update mutates state

Update data-source metadata such as title, icon, or property schema. Destructive schema removals preview first and require –yes.

--icon string Data-source icon as emoji or raw Notion icon JSON

--schema string Raw Notion data-source properties patch JSON

--title string New data-source title

--yes bool Confirm destructive schema removals

$ notion data-source update ds1 --title "Updated tasks"

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 --help

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 file List Notion file references

#cmd-notion-file discovery safe

$ notion file --help

notion file list List file references on a Notion page

#cmd-notion-file-list discovery safe

--page string Page reference

$ notion file list --page p1

notion mcp Run the MCP server

#cmd-notion-mcp discovery safe

Run a stdio Model Context Protocol server for this adapter.

The server exposes read-only resource commands by default. Mutating commands are listed only when explicitly allowed with –allow and remain gated by the command contract safety class.

--allow stringArray = [] Allow mutating command keys such as gmail.message.archive or gmail.message.label.*

--allow-dangerous bool Allow --allow wildcards to include destructive or sends_external commands

--concurrency int Maximum concurrent MCP subprocesses

--max-output int64 = 0 Maximum stdout/stderr bytes captured per MCP command

--print-config bool Print MCP tool configuration and exit

--timeout duration = 0s Per-command MCP subprocess timeout, for example 45s or 2m

$ mcp

$ mcp --print-config

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 --help

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. Use –body-file as the explicit file input form (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

--body-file string Read body paragraph text from a file

--parent string Parent page or data-source reference

--properties string Raw Notion properties JSON object

--title string Page title

$ notion page create --parent ds1 --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 –parent to list rows from a data source or direct child pages under a page. Use –database and –parent-page as compatibility selectors. 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 string Parent page or data-source reference (marker, URL, or UUID)

--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 dry-run

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

--dry-run bool Preview page trash without changing Notion

--yes bool Confirm destructive page trash

$ notion page trash p1

notion page update Update a Notion page

#cmd-notion-page-update mutates state

Update Notion page metadata 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. Use –body-file as the explicit file input form. When reading body from stdin, page ref must be a positional argument because stdin cannot carry both the ref and body text. Use –icon with an emoji, external URL, or raw Notion icon JSON. Use –cover with an external URL or raw Notion cover JSON.

--body string Body paragraph to append; use @file to read from file, - to read from stdin

--body-file string Read body paragraph to append from a file

--cover string Page cover as external URL or raw Notion cover JSON

--icon string Page icon as emoji, external URL, or raw Notion icon JSON

--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 --help

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 property Inspect Notion page properties

#cmd-notion-property discovery safe

$ notion property --help

notion property get Get a page property item

#cmd-notion-property-get discovery safe

--page string Page reference

--property string Property name or id

$ notion property get --page p1 --property Status

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 user Inspect Notion users

#cmd-notion-user discovery safe

$ notion user --help

notion user get Get a Notion user

#cmd-notion-user-get discovery safe

$ notion user get usr1

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.

$ notion workspace --help

notion workspace search Search Notion for pages, databases, and data sources

#cmd-notion-workspace-search discovery safe

Search the Notion workspace for pages, databases, and data sources matching a query.

Assigns local markers (p1, d1, ds1, …) for follow-up commands.

--in-trash string Filter by trash state: true or false

--limit int = 20 Maximum number of results to return

--query string Search query text

--type string Filter by type: page, database, or data-source

$ notion workspace search --query "roadmap" --limit 10

play_circle Live Examples

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

auth

Check current identity Returns the authenticated user and workspace.

$ 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 Lists all databases visible to the current PAT profile.

$ 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 Shows schema and metadata for 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 Returns rows from a database and assigns page refs.

$ 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 Returns title, parent, properties, and block count.

$ 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 Lists the blocks inside a page as a readable outline.

$ 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 Full-text search across pages, databases, and data sources.

$ 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

Notion CLIfor cmdhub.

data_object Agent Contract

Output

Auth

Refs

Schemas

Auth scopes

terminal Command Reference

Global Flags

play_circle Live Examples

auth

databases

pages

blocks

search

alt_route Composition Patterns

Notion CLI
for cmdhub.