Closes#37. Wraps the two 2025 Notion endpoints that do server-side
markdown I/O on a full page:
GET /v1/pages/:id/markdown → notion page markdown <id>
PATCH /v1/pages/:id/markdown → notion page set-markdown <id>
### page markdown
Prints a page's content as markdown. Strictly better than `block list
--md` for page-level dumps: the server handles toggles, columns, synced
blocks, and databases-as-pages uniformly and always matches what the
Notion UI shows.
notion page markdown <id>
notion page markdown <id> > page.md
notion page markdown <id> --out page.md
notion page markdown <id> --format json # full response incl. truncated flag
Surfaces Notion's 'truncated' flag and 'unknown_block_ids' as stderr
notes in default output so silent partial renders don't go unnoticed.
### page set-markdown
Updates a page from markdown in one API call. Supports all four
mutation modes Notion's PATCH endpoint accepts:
--replace (default) replace_content: overwrite whole page
--append insert_content at end
--after <anchor> insert_content after ellipsis anchor ("start...end")
--range <anchor> replace_content_range bounded by ellipsis anchor
--file <path> (use '-' for stdin)
--text <str> inline markdown
--allow-deleting-content pass allow flag for destructive modes
Because Notion handles the full markdown → blocks conversion server-side,
this is the cleanest way to write long documents — the 100-children
batching (#21) doesn't apply to set-markdown.
### Implementation
Two pure helpers isolate the fiddly bits for unit testing without network:
- buildSetMarkdownBody: produces the correct envelope for each mode;
rejects ambiguous flag combinations up front.
- readMarkdownSource: picks the source (--file / --text / stdin); same
mutual-exclusion rules as the rest of the CLI.
### Tests
- Exhaustive buildSetMarkdownBody coverage across all four modes +
allow_deleting_content + multi-mode rejection.
- readMarkdownSource: required / conflict / file / stdin / file-missing.
### Smoke
Verified end-to-end against a real workspace: replace via --file,
append --text, markdown read with --out, stdin replace, and multi-mode
rejection all behave as documented.
Closes#38. Fixes silent truncation of property values with >25 items.
Problem:
'notion page view' and 'notion page props' both call GET /v1/pages/:id,
which returns every property in a single response but truncates values
at 25 items. A relation pointing to 40 pages silently loses 15.
Fix:
New 'page property' subcommand wraps GET /v1/pages/:id/properties/:id
and walks next_cursor until has_more is false, merging results[] into
a single response.
Interface:
notion page property <page-id> <property-id>
notion page property <page-id> --name "References" # resolve id by name
notion page property <page-id> <property-id> --page-size 50
Implementation:
- fetchPagePropertyAllPages handles both paginated ('list' object) and
non-paginated ('property_item' object) response shapes.
- findPropertyIDByName scans page.properties map for --name lookups;
error message includes the list of available names.
- renderPageProperty prints a human-friendly summary; summarizePropertyItem
covers relation / rich_text / title / people / number types with a
JSON fallback for anything else.
Tests:
- TestFetchPagePropertyAllPages_FollowsCursors spins up a 3-page
httptest server and asserts all 4 items are merged with has_more=false.
- Passthrough test for 'property_item' (non-paginated) shape.
- findPropertyIDByName: found / missing / malformed page.
Smoke-tested against a real database: --name resolves correctly, positional
property-id works, 'title' non-paginated path returns the expected single
item, and both conflict / not-found errors fire cleanly.
Closes#36. Brings 'block update' in line with 'block append' / 'block
insert', which have supported markdown input since earlier releases.
New flags:
--file <path> read markdown from a file; must parse to exactly one
block. Fails fast on type mismatch because Notion's
PATCH /v1/blocks/:id cannot change a block's type.
Code-fence language aliases from #22 apply here, so
--file with a 'ts' / 'sh' / 'yml' fence still works.
--markdown when combined with --text, runs the inline parser
(bold / italic / code / strikethrough / links).
Mutual-exclusion and validation:
- --text and --file are mutually exclusive.
- --markdown is implied for --file; supplying both is rejected.
- At least one of --text / --file is required.
- --file preserves type-specific inner fields (code.language, to_do.
checked, etc.) from the parsed block.
Logic extracted to buildUpdateBlockBody() so it's unit-testable without
network. Tests cover plain text, --markdown annotations, --file parsing
with language normalization, type mismatch, multi-block rejection, and
missing-file errors.
Smoke-tested end-to-end: paragraph → plain update, paragraph → markdown
update with links/bold, code block → sh-alias update normalized to
'shell', and the type-mismatch guard fires correctly.
Wraps two endpoints added in Notion's 2025 API that the CLI didn't yet
expose:
- PATCH /v1/comments/:id → 'notion comment update <id> --text ...'
- DELETE /v1/comments/:id → 'notion comment delete <id> [<id> ...]'
'update' reuses the existing buildCommentRichText helper so the
--mention-user flag works the same way as 'comment add'.
'delete' follows the 'block delete' pattern: variadic args, per-id
error isolation, and a summary line (N comment(s) deleted). When the
target id is the anchor of a discussion, Notion removes the whole
thread; deleting a reply removes just that one comment — this is
documented in the Long help.
Two new client methods (UpdateComment, DeleteComment) keep the API
plumbing in internal/client alongside AddComment.
Smoke-tested against a real workspace: create comment → update text →
verify new text via 'comment get' → delete → raw DELETE on the same id
returns object_not_found as expected (the synchronous GET path is
eventually consistent server-side, which is a Notion behavior, not a
CLI issue).
Closes#33
Three changes to de-scare the soft-delete command:
- 'page archive <id>' is the canonical form. This is the term used in
Notion's UI and in the 2025 API (where the field is renamed in_trash,
kept backwards-compatible with 'archived').
- 'page delete' and 'page trash' are now cobra aliases that resolve to
the same RunE. Existing scripts pinned on 'page delete' keep working
unchanged; the legacy variable pageDeleteCmd also still exists as an
assignment to pageArchiveCmd for any external code path.
- Help text now makes the soft-delete nature explicit and the success
line tells the user how to undo ('run notion page restore').
The page restore Long was updated to say 'reverse of archive / delete /
trash' for symmetry.
Aliases are hidden from 'notion page --help' by cobra, so new users see
one canonical command; they surface on 'notion page <alias> --help'.
Closes#35
Wraps GET /v1/file_uploads/:id — the dedicated endpoint for checking the
status of a file upload (pending / uploaded / expired), recovering its
content_type/size, or grabbing an existing file_upload id for re-use
inside a block.
Previously this endpoint was only reachable via:
notion api GET /v1/file_uploads/<id>
The new command prints a human-friendly summary by default and passes
through the raw JSON with --format json.
Tests cover the full-field render and the minimal 'pending' render,
asserting only on output that goes through fmt.Println — keys rendered
via fatih/color bypass our stdout pipe capture (same pattern as the
existing search table tests).
Closes#34
The Notion API returns a technically-accurate but hard-to-action
validation error when an internal integration tries to create a page at
the workspace root:
validation_error: Provide a parent.page_id or parent.database_id
parameter to create a page, or use a public integration with
insert_content capability. Internal integrations aren't owned by a
single user, so creating workspace-level private pages is not
supported.
Two small improvements so users don't have to parse that paragraph:
1. `notion auth status` and `notion auth doctor` now derive the
integration type from bot.owner.type ("workspace" → internal,
"user" → public) and print it. For internal integrations a follow-up
line reminds the user they must share a parent page first.
2. client.errorHint matches the internal-integration validation_error
signature and prints a concrete workaround with the exact next command:
→ Internal integrations can't create pages at the workspace root.
Workaround: create (or pick) a parent page in the Notion UI,
share it with this integration, then pass its ID as the parent:
notion page create <shared-page-id> --title "..."
To list pages shared with your integration: notion page list
Detection code is small (detectIntegrationType in cmd/auth.go) and
defensive: unknown or missing owner shape returns "" so pre-existing
response fixtures that don't include bot.owner still render fine.
Closes#25
Previously `notion file upload` only worked with a local filesystem
path. To upload something that lived behind a URL (chat attachment, CI
artifact, object-storage direct link) you had to curl to a tmp file
first. To pipe bytes into Notion you couldn't at all.
This change introduces a fileSource abstraction and three loaders:
<path> local file (existing behavior, unchanged)
- read from stdin (requires --name)
http(s)://... HTTP GET, follows redirects, reads Content-Type
and Content-Disposition filename if present
A new --name flag overrides the filename in all three modes. It is
required for stdin (we can't guess) and recommended for URLs whose
path segment is opaque (e.g. /download?id=123).
Deliberately scoped out of this PR (use a curl-pipe for these):
- custom auth headers for the URL loader
- chunked / streaming upload (single-part, same as before)
Tests use httptest for URL loading, os.Pipe to redirect stdin, and
integration tests wire uploadFromAny through the existing fileUploadAPI
mock to prove every source funnels into the same two-step upload flow.
Closes#26
Before this change there was no first-class CLI path to turn an uploaded
file into a block. Users had to run `notion file upload`, capture the
id, then hand-craft a PATCH /v1/blocks/<id>/children JSON body and send
it via `notion api`. The existing --image-url only accepted external
http(s) links.
This PR adds a symmetric triple for every media type Notion supports:
--image-url / --image-file / --image-upload
--file-url / --file-file / --file-upload
--video-url / --video-file / --video-upload
--audio-url / --audio-file / --audio-upload
--pdf-url / --pdf-file / --pdf-upload
Semantics:
--<kind>-url http(s) external URL → block.<kind>.type = external
--<kind>-file local path → upload then embed
--<kind>-upload existing file_upload id → embed directly
Flags are mutually exclusive with each other and with --file/positional
text. --caption works with any of them.
Implementation lives in cmd/media_source.go:
- registerMediaFlags: adds the 15 flags + --caption to a cobra command.
- resolveMediaSource: validates, returns the single active source.
- mediaSource.Build: performs the upload (for --*-file) and assembles
the final block map.
The legacy --image-url flag and its validator/builder are now thin
back-compat wrappers around the new helpers, so existing tests and
usage keep working byte-for-byte.
Closes#23
Notion rejects PATCH /v1/blocks/<id>/children with either:
- body.children.length > 100, or
- body.children[N].<type>.rich_text[0].text.content.length > 2000
Both limits are fixed and known at parse time, so the CLI can absorb
them. Previously even a moderately long markdown file (a postmortem, a
design doc with one ~2KB stack trace, …) required manual splitting.
New helpers in cmd/block_limits.go:
- chunkChildren: slice the children list into groups of ≤100.
- appendChildrenBatched: PATCH each chunk sequentially, preserving
order. The `after` anchor is attached to the FIRST batch only,
because Notion won't let subsequent inserts reference a block from
the same transaction. Progress is printed to stderr (not stdout, so
--format json still pipes cleanly).
- handleOversizedBlocks + parseOversizeMode: split oversize code
blocks on newline boundaries by default, with `--on-oversize=
truncate|fail` escape hatches. Code language and to_do checked
state are preserved across split chunks.
Partial-failure message now tells the user exactly which batch failed
and how many blocks were already written:
batch 2/3 failed after writing 100 block(s): <api error>
Wired into both `block append` and `block insert`.
Tests cover: chunk sizes, oversize split/truncate/fail modes, newline
boundary preference, order preservation across batches, `after` anchor
placement, partial-failure error text, and an end-to-end pipeline with a
150-bullet + 3000-char-code-block document.
Closes#21
Markdown / LLM output routinely uses short language labels (`ts`, `sh`,
`yml`, `py`, …) that the Notion API rejects because code.language is a
fixed enum. Previously every such fence hard-failed the whole PATCH with:
body.children[N].code.language should be "abap", ..., "typescript",
"yaml", or "java/c/c++/c#", instead was "ts".
Introduce `normalizeCodeLanguage`:
- passes through any value that's already in the Notion enum,
- maps ~50 common aliases (ts→typescript, sh→shell, yml→yaml, py→python,
cpp→c++, cs→c#, dockerfile→docker, md→markdown, proto→protobuf, …),
- for unknown values, falls back to 'plain text' and emits a one-line
stderr warning so a single unrecognized fence can't break a long doc.
Applied to both markdown parsing (`notion block append --file`) and the
`--lang` flag on inline append/insert, so CLI-typed aliases like
`--lang ts` also work.
Closes#22
- Auto-prefix /v1 when a path starts with / but not /v1/, with a stderr
note so power users see the rewrite. Previously `notion api GET /users/me`
returned an opaque 'invalid_request_url' error.
- Support `--body @file.json` (curl-style) and `--body -` for explicit
stdin reads. The existing implicit stdin fallback for POST/PATCH/PUT
still works.
- Reject GET requests with a body up-front instead of silently dropping it.
- Route PATCH through c.Patch() unconditionally (previously it hit c.Post
first and was overwritten, which made error paths confusing).
- Drop the misleading positional-arg example from --help; the flag was
the only supported form.
Closes#24
Notion API validation requires table_row blocks inside table.children
(not at block top-level). Fixes 'table.children should be defined' error.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
After profile-based login, cfg.Token is empty because MigrateToProfiles
clears it. doctor was only checking the legacy top-level token field,
causing it to always report 'no token found' even after a successful login.
Fixes#5
- Add profiles support to config structure
- Add auth switch command for interactive/direct profile switching
- Update auth login to support --profile flag
- Update auth status to show current profile
- Update getToken() to use profile system
- Backward compatible: auto-migrates legacy single-token config
- Add comprehensive tests for profile functionality
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- GET parent comment to find discussion_id
- POST new comment with discussion_id to same thread
- Shows discussion ID in output for reference
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Query all rows with pagination support
- Support --format csv (default), json, md
- Support --output to write to file (default: stdout)
- CSV: headers from property names, rows from property values
- JSON: array of objects with property values
- MD: markdown table format
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Supports --after to position after a specific block
- Supports --before to position before a specific block
- Supports --parent to move to a different parent block/page
- Uses PATCH /v1/blocks/{id} with parent and after fields
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Downloads page blocks as Markdown
- Opens in $EDITOR (or $VISUAL, fallback to vi)
- Parses edited Markdown back to Notion blocks
- Updates page by deleting old blocks and appending new ones
- Supports --editor flag to override default editor
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- config_test: use t.Setenv for reliable env isolation on CI
- config_test: skip permission test on Windows
- test.yml: align Go matrix with go.mod (1.24)
- goreleaser: fix deprecated formats/homebrew_casks fields
- block: improve --format md rendering with proper indentation
- block: add more markdown parse test cases
- page: minor improvements
- Add --filter-json for raw Notion API filter JSON (OR/nested queries)
- Add --all pagination to db query (all list commands now support --all/--cursor)
- Add semantic error hints with actionable suggestions for 10 API error codes
- Add page create --db for database parent (schema-aware property detection)
- Add block list --depth N for recursive nested block fetching
- Add block list --md for Markdown output rendering
- Add Markdown-to-blocks parser for --file (h1-h3/bullet/numbered/todo/quote/code/divider)
- Add comment get command
- Move todo parsing before bullet to prevent --[ ] matching as bullet
- Add 24 new tests (block markdown parsing + error hints)
Total: 4,310 lines Go, 1,056 lines tests, 124 test cases, 9.6MB binary
New commands:
- block insert: positional insertion with --after <block-id>
- block append --file: read content from markdown files
- block delete: now supports multiple IDs in one call
- page restore: unarchive pages (reverse of delete)
- page link/unlink: manage relation properties between pages
- db add-bulk: bulk create rows from JSON file with progress
- auth doctor: health check (config, token, workspace, API)
All following our design: human-friendly syntax, dual output,
schema-aware operations. No raw JSON required from users.
3,878 lines of Go. 38 subcommands. Single binary.
Qi Qi