ntn

Read and edit Notion page bodies as Markdown, query data sources, or call the Notion API directly. Mirage implements the command subset below using the official ntn grammar.

Setup

Create an integration and grant it access to the relevant pages using Notion setup.

import { NTN, Workspace } from '@struktoai/mirage-node'

const config = { apiKey: 'secret_...' }
const ws = new Workspace({})
ws.registerCli('ntn', NTN, config)

No service mount is required. For YAML and multiple accounts, see the CLI overview.

Supported commands

Run ntn <command> --help for the supported flags and operands. This list is generated from Mirage’s registered command tree.

Command	Description
`ntn api`	Call the public Notion API (beta)
`ntn auth token`	Print the current authentication token
`ntn datasources query`	Query pages in a data source
`ntn datasources resolve`	Resolve a Notion database ID to its data source IDs
`ntn pages get`	Retrieve a page as Markdown
`ntn pages create`	Create a page from Markdown content
`ntn pages edit`	Edit a page’s content from Markdown
`ntn pages trash`	Trash a page
`ntn whoami`	Show the authenticated Notion user

Read and edit pages

ntn whoami
ntn pages get PAGE_ID
ntn pages get PAGE_ID --json
ntn pages create --parent page:PARENT_ID --content '# Release notes'
echo '# Release notes' | ntn pages create --parent data-source:SOURCE_ID
ntn pages edit PAGE_ID --content '# Updated body'
ntn pages trash PAGE_ID --yes

Page IDs are positional. Bodies are Markdown; the first heading becomes the title when creating a page. --parent accepts page:, database: or data-source: followed by an ID. pages edit replaces the entire body. Trashing requires confirmation; pass --yes for noninteractive use. To update database-row properties, use the API rather than page-body editing:

ntn api v1/pages/PAGE_ID -X PATCH -d '{"properties":{"Stage":{"select":{"name":"Draft"}}}}'

Query data sources

ntn datasources resolve DATABASE_ID
ntn datasources query SOURCE_ID --limit 10 -s 'Priority desc'
ntn datasources query SOURCE_ID --filter '{"property":"Stage","select":{"equals":"Done"}}'
ntn datasources query SOURCE_ID --filter-file /work/filter.json --json

resolve returns a database’s data source IDs. query accepts a data source or database ID/URL. Its default output is tab-separated: page ID followed by property values, with columns sorted by name from the returned rows. --json returns the API response. --filter-file reads through the workspace VFS, relative to the session’s working directory.

Call the API

ntn api v1/users/me
ntn api v1/search -d '{"query":"Roadmap"}'
ntn api v1/blocks/PAGE_ID/children page_size==10
ntn api v1/blocks/BLOCK_ID -X DELETE
printf '{"query":"Roadmap"}' | ntn api v1/search

Input	Meaning
`-d` / `--data`, stdin, or inline fields	Request body; choose one source
`name=value`	String body field
`name:=json`	Typed JSON body field
`name==value`	Query parameter, regardless of method
`Header:Value`	Request header
`-X` / `--method`	`GET`, `POST`, `PATCH`, `PUT` or `DELETE`

A body selects POST unless a method is explicit. Blocks, comments and search use API paths; they are not separate command groups.

VFS and limits

The optional Notion VFS provides page and database files. Reuse its IDs, or obtain them through the API; no mount is required. Interactive login/logout, update, workers, deployment and file-management commands are absent. The config supplies the credential. Command-line parsing follows CLAP style. Exit codes distinguish these failures:

Failure	Exit code
Unknown options or missing required arguments, such as `ntn --bogus` or `ntn pages get`	2
Invalid JSON in a nonempty `ntn api --data` body or stdin	1
Empty `--data`, invalid inline request input, or conflicting body sources	5
Notion API authentication failure (HTTP 401)	4
Other Notion API failures	5

The shared conformance suite checks the implemented surface against ntn. The suite pins ntn 0.21.9, whose package metadata declares MIT. Mirage’s command implementation is Apache-2.0; see compatibility and licenses.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Setup

Supported commands

Read and edit pages

Query data sources

Call the API

VFS and limits

​Setup

​Supported commands

​Read and edit pages

​Query data sources

​Call the API

​VFS and limits

Setup

Supported commands

Read and edit pages

Query data sources

Call the API

VFS and limits