Written by npx @wirecat/cli-template new, then filled in during design. Steps 1, 2 and 5 below are built: sign-in
with a token, doctor, documents get, databases list|show, read live, the sync into the shared store with search,
the local reads and the knowledge commands, and the page writes.
- Category: files and documents
- Content languages: en, ru, es
- Sign-in: an API token or key; a browser sign-in (OAuth) comes last, see Sign-in
- The API: an official API with an official client library
- How people filter: by time, by person, by container (chat, folder, calendar), by words in the text, by status or label
- Never in the store, a log or the output: tokens and passwords, links that carry a secret
- Untrusted input: page and row text written by other members, files and attachments, links, names and titles set by others
Learn from drive-cli. Where drive-cli keeps code of its own for something cli-core now shares (profiles, the profile lock, the permission policy, the MCP server, session commands), follow gcal-cli, mail-cli and bitrix24-cli instead.
Languages: en, ru, es.
notion keeps a copy of the Notion pages and databases a person chooses on their computer, makes them searchable
offline with the rest of WireCat (memo search, search all), and gives an agent the same through MCP. Later it keeps
a folder of Markdown files and a Notion page tree in step, both ways.
The work goes in this order, each step one pull request:
Sign-in with a token,Done.doctor, and reading one page live, as Markdown. No store.Sync into the shared store, search and MCP.Done: cli-core's shared documents commands over Notion.- Databases: their rows, with their properties.
- Search by a property (
status:Done). Writes: create, update and delete a page.Done: see Writes.- A local folder kept in step with a Notion page tree.
The raw API, comments and files.Done:api, and see Comments and files.- Sign-in in the browser (OAuth), through the person's own Notion connection.
Every request runs inside cli-core's command run (WC-LIFE-15, WC-LIFE-17).
Every secret lives in the system keyring (a private file only when the keyring fails or --credential-storage file
is given). Nothing is kept on a WireCat server.
- A token.
notion <profile> session startasks for the token hidden, or reads it from stdin, checks it against Notion (retrieve your token's bot user), and keeps it under the keyring accounttoken:<profile>. Two kinds of token work:- a personal access token, which acts with the person's own rights and expires after at most one year;
- an internal connection's token, which sees only the pages shared with that connection.
- OAuth, last. Through a public Notion connection in the browser, under
oauth:notion:<profile>. A profile uses one kind of sign-in; starting the other replaces it.- Notion's token endpoint takes the client id and secret as HTTP Basic and a JSON body, and each refresh returns a new refresh token (authorization guide). cli-core's token keeper refreshes under one lock for every process, so a rotated token is never sent twice.
- The secret is needed for every exchange, and Notion does not call its clients public. So no WireCat app can ship
inside the tool (WC-SECR-25): the person registers their own public connection, its secret is asked hidden and
kept in the keyring, and
doctorreports that WireCat has no app, with the reason. - cli-core's sign-in listens on a random local port, and a connection matches its redirect address exactly. Either cli-core gets a fixed local port, which the person registers with their own connection, or the browser returns to a fixed relay page that forwards the code to the local port and stores nothing, as bitrix24-cli does.
One connection, one profile. The account is the workspace id and the token's bot id. Two profiles on one token
would be one account in the shared store, and each sync would remove the pages of the other. So session start and
sync refuse a connection another profile signed in to uses (profile.account-taken), and name that profile: use
it, or run session end there first. A profile whose copy was synced from one connection refuses a token of another
(profile.other-account), at sign-in and at sync; the token it had stays. The other connection goes to a new profile.
Removing a profile's copy (account remove) is not built yet.
session status, session list and session end work as in the template sample. session end removes only this
tool's own entries. Notion's own CLI keeps its tokens under the same keyring service name, notion-cli, with a
workspace id as the account; this tool never lists, reads or removes an account it did not write.
The environment variables start with WCNOTION_ (WCNOTION_TOKEN, WCNOTION_PROFILE), not NOTION_: Notion's own
MCP server reads NOTION_TOKEN, and a token set for it would silently sign every profile in.
The command names are drive-cli's and the shared vocabulary's wherever the thing is the same. A difference has its reason here.
| Command | What it does | drive-cli |
|---|---|---|
session start|status|end|list, account remove |
sign-in, as above | same; status is required (WC-ACCT-12) |
folders add|list|browse|remove |
narrow the sync to chosen pages and databases; with none chosen, everything the token sees is synced | same name; a Notion "folder" is a page or a database |
sync, status |
copy the chosen pages into the store; report coverage | same |
documents list|show|export|context|add |
read the local copy; add one page by its link |
same |
documents get |
read one page live, as Markdown | same |
documents create|update|delete|restore |
write a page; delete moves it to Notion's trash |
create|update; Notion has a trash to restore from |
databases list|show |
a database, its data sources (their ids) and its properties, live | Notion only, as sheets is Drive only |
search |
the local copy, Lucene syntax; database rows are searched here, not by a separate query | same |
catalog, tags, relationships, notes, memories, facts, identities |
the knowledge layer over documents | same |
mirrors add|list|remove|status|sync|watch |
a local Markdown folder in step with a page tree | same |
comments list|create|reply |
page comments, live; list shows unresolved ones only |
same group name |
files upload |
a local file added to the end of a page | Notion only |
api list|show, one command per operation |
the raw API, from Notion's OpenAPI document | same |
doctor, config, mcp, skill, runs, upgrade, commands |
from cli-core | same |
drive-cli commands with no Notion counterpart: documents check and documents history, revisions (page history is
out of scope), files (Notion stores files inside pages), permissions (no command changes who sees a page),
store (an import for old drive installs).
Notion's own CLI and MCP server show what users trip on. This tool takes three of their ideas:
documents updaterefuses to delete child pages and databases unless--allow-deleting-contentis given;databases showgives a database's data source ids, which every query after Notion's 2025-09-03 version needs;apilists the operations and prints each one's spec.
- What is kept. Each page and each database row is a
documentsrecord through cli-core's document ingestion, under the providernotion(kinddocuments, registered on every run that writes the store; a read opens it read-only).- The account is one sign-in's view of a workspace: the workspace id plus the token's bot id. Two profiles in one workspace with tokens of their own see different pages, so they are different accounts.
- The record's external id is the page id. In the catalog a page is a
fileand a database afolder, with Notion's type kept beside it. Every page is a folder to the sync and a document too (cli-core'sisDocument), so pages under pages are copied and a page can be a chosen folder. A row is a plain file. - The page text is Notion's own Markdown export
(retrieve a page as Markdown, version 2). A
row's properties go into its front matter, so they are searchable as words from step 3, and as fields from
step 4. A page's creator and last editor become Notion identities in the shared store, with the roles
ownerandlast-editor, and the page is linked to their people. Their names and email addresses come from retrieve a user, asked once per user and run. An email address joins the identity to the person who has it, as drive-cli does. That needs the connection's capability to read user information including email addresses; without it the sync keeps the id, and says so in its issues and indoctor. A page read before this keeps no identities until it changes, or untilidentities linknames one. - File links that Notion signs carry a secret and expire after an hour. They are removed from the text before it is stored.
- How it syncs. On demand (
sync), on a schedule (jobs), and kept running bymirrors watch. Notion has no change feed, so the position is a time mark:- The first sync walks everything the token sees, or only the chosen folders: the top of the workspace, and the rows of each database. WireCat Desktop offers the same choice.
Pages under pages are not synced yet: done in step 2. SYNC.md has the details.- Later syncs read the pages edited since the mark, with a two-minute overlap, because Notion's timestamps
appear to be rounded to the minute (to be confirmed against the live API in step 2). They come from search
sorted by
last_edited_time, and from each chosen database filtered bylast_edited_time. - Notion says its search is not complete and lags behind edits
(search limitations). So a full
walk runs again on a schedule and with
sync --rescan, and that walk finds deleted pages. - A database query stops at 10,000 rows and says so
(query a data source); the store's catalog takes
at most 10,000 entries per scope. Every page of results is checked, and a folder that would pass a limit fails
with an error that names it, never a silent cut. The store has no ceiling any more, and neither has the sync: one
sync walks at most 10,000 entries (
maxEntries) and its run's budget, saves where it stopped, and the next sync goes on. - Requests are paced below Notion's limit of 180 a minute per connection, through cli-core's pacer. Data source
queries have a limit of their own, "about 3 requests per second per connection"
(request limits), so they take a second pace at the
same rate with a smaller burst.
cli-base's retry waits for
Retry-After; search and database queries are POST, so they are marked as reads. sync --limitbounds the pages saved in one run, and the source stops at 2,000 requests while it looks for changes.statusanswers withprogressin the shared shape (WC-LIFE-14). Not yet: a budget sized to the deadline with anextstep (WC-LIFE-16), which cli-core's sharedsynccommand does not offer.
- When Notion deletes a page. It leaves the next full walk, is confirmed gone by asking Notion for it directly (a page missing from search is not proof), and is marked deleted in the store, never wiped.
- Local deletion. One account with
account remove, as in drive-cli; the store's own commands cover the rest.
- Titles, the full text, a row's properties, and the names of authors.
- Yes: records of kind
documentsappear insearch alland in memo, with no change to memo. - Everything in the local copy: search, show, export, notes and memories.
- The system keyring, as above.
- Every write is a permission key of its own and goes through cli-core's guard and write journal, with
--dry-run. As in gcal-cli and drive-cli, creating and updating a page is allowed, and deleting one asks first. Deleting child pages through an update needs its own flag on top. No command shares a page or changes who can see it.
documents create|update|delete|restore change pages live, as gcal-cli changes events. Each runs through cli-core's
guard and send journal, with the command's own permission key, and answers with an operation_id.
- create sends create a page with
markdown(version 2) under a parent page. With no--title, Notion takes the text's first# heading. A row of a database is not created here: its title property has a name of its own, and its other properties are step 3's. - update replaces the whole text with
replace_contentof update page Markdown. Notion refuses a text that leaves out a child page's or database's tag unlessallow_deleting_contentis set, which--allow-deleting-contentsends. Notion's refusal is a plainvalidation_error, also given to a text over 5,000 blocks, so it is mapped tonotion.text-refusedwith both causes named; Notion's own message is not repeated, as it quotes titles. Notion'swarningsfor a part it changed or left out are reported by their code only. A partial edit (update_content) waits for mirrors, step 6. - delete and restore set
in_trashwith update a page. The API has no permanent delete, sodeleteis always undone byrestore. - Permissions, as gcal-cli and drive-cli: create, update and restore are
allow;documents.deleteisask. An update with--allow-deleting-contentalso checksdocuments.delete, so it asks too, in one question. Over MCPaskgoes ahead (cli-core's rule), sodenyis what keeps an agent from deleting. Each write also checks the key of theapioperation it sends (api.post-page,api.update-page-markdown,api.patch-page), so denying the operation cannot be got round throughdocuments. The other way round, a rawapicall that deletes also checksdocuments.delete, as gcal-cli'sapichecksevents.deletefor a body that cancels an event: every operation whose method deletes (delete-a-block, which may be a page,delete-a-comment,delete-viewand the rest), and a body that setsin_trash,erase_contentoris_archivedtotrue, allows deleting content, or sets a data source's property tonull, which removes it with its values. The list comes from a scan of Notion's OpenAPI document for such fields.--dry-runandWCNOTION_READ_ONLYare cli-core's. - Files.
--filetakes only a regular file, after following links, and refuses/proc,/sysand/dev(/proc/self/environholdsWCNOTION_TOKEN), credential files, browser profiles and the WireCat folders, with cli-core'srefusedPlace, as a messenger's file send does: an agent steered by a page's text must not publish a key. The/procand regular-file check here goes once cli-core'srefusedPlacehas it (cli-core #3014). - Never sent twice. A 5xx, which Notion also gives a request it ended after 60 s, no answer, or an answer that
cannot be read is
outcome_unknown: the page may have changed, so it is read before the write is repeated. - The local copy is not changed by a write; the next
syncbrings it in step.
comments list|create|reply and files upload are friendly commands over the same calls api makes, with the
writes' guard, send journal, operation_id, --dry-run and WCNOTION_READ_ONLY.
- comments list sends list comments, which gives only
unresolved comments; its help says so.
--limitand--cursorpage it. - comments create comments on a page and comments reply answers in a discussion by its
discussion_id, both withmarkdownin create a comment, which keeps inline Markdown only. The text is asecretInput: no run record keeps it, whateverrecord_inputsays. Both checkcomments.createandapi.create-a-comment, so a deny on either stops a reply too. - files upload sends up to 20 MB in one part and a larger file in parts of 10 MB, then completes it, as
sending larger files says (parts of 5 to
20 MB). It then appends the file to the end of the page as an image, video, audio, PDF or file block, by the type
Notion read from the name. It checks
files.upload,api.create-file,api.complete-file-uploadandapi.patch-block-children. The file is opened once and checked as--fileis: no link, no system or credential file.
mirrors uses cli-core's mirror engine, as drive-cli does: a three-way merge of Markdown blocks, conflicts settled
with --keep, nothing deleted on the other side. The Notion side reads a page as Markdown and writes only the
changed parts with update page Markdown. Notion applies
the parts that match and only warns about the rest, so a warning counts as a failed write. Child pages are never
deleted.
The strict fake in src/testing/fake-notion.ts is built from Notion's reference only; no answer was captured from a
live workspace. bin/notion-live <page> checks the real API through scripts/live.sh, with a temporary profile that
stores nothing, and records the pass in docs/dev/live-checks.txt for bin/release. It fails on the first two points
below and on the write round trip after them; the rest a person reads in its output:
GET /v1/users/megivesbot.workspace_idfor both kinds of token. The account is that id and the bot's id; the reference lists the field but its example leaves it out, and sign-in refuses an answer without it.documents geton a page with an uploaded file whose name has parentheses, such asScreenshot (2).png, cuts at least one signed link and prints noX-Amz-orsignature=query. Use such a page for the check: it fails on a page with no file. The form of a signed link in Markdown v2 is not documented;src/notion/links.tscuts every query that carries a signature, plain or percent-encoded, wherever the link around it ends.- A
child_pageblock'slast_edited_timeis its page's, and itshas_childrenmatches what the page holds. The sync files a child page from its block (the sync); the check warns on a difference and needs a test page with at least one page under it. - A renewed personal access token, or a new token of the same connection, keeps the bot id. If it does not, a
profile refuses its own renewed token as another connection (
profile.other-account), and the account must become the workspace id alone, or the bot's owner. GET /v1/users/{id}with the bot's own id answers with its name (not yet checked live). The reference says a connection without user information capabilities is refused with 403; the sync then keeps authors by id only.bot.owner.typeisuserfor a personal access token andworkspacefor an internal connection's token.- On a page past about 20,000 blocks, the
<unknown url="…"/>tag names its block id, so the fetched part lands in place; otherwise it is added after the page. databases listrows carry a data source's title, andparent.database_id, in search results.
The check writes, but only under the page it is given, the owner's test page "WireCat Test". It creates one page
wirecat-live-<time> there and a page under it, reads the text back, replaces it, checks that an update dropping the
child page is refused with notion.text-refused, trashes and restores the page, checking in_trash each time, and
leaves it in Notion's trash. Its temporary profile allows documents.delete, so no question stops the run; a check
that fails half way trashes its page on the way out.
- Mirrors, to settle before step 6:
- Where a page created from a local file keeps its origin key, so a create cut short is not repeated. Drive keeps it in a hidden file property. A Notion page has properties only inside a database.
- Notion has no revision lock on a write. A check of
last_edited_timebefore the write leaves a short race. - A Markdown edit must match its old text exactly once. A line that repeats (the same checklist item twice) needs a whole-page replace instead.
- Notion blocks the shared Markdown blocks cannot hold (toggles, callouts, mentions, child pages, and possibly bookmarks and embeds) must pass through unchanged.