@innosage/draft-cli

@innosage/draft-cli

Draft CLI is a headless command-line interface for local Draft page operations and hosted Secret Share helpers.

Installation

npm install -g @innosage/draft-cli

Lifecycle

Start the headless v2 daemon:

draft start-server
draft status --json

Stop it when finished:

draft stop-server

The CLI no longer supports browser-backed relay, draft daemon, runtime v1, or CLI workspace mode. draft status --json reports READY when the headless daemon is running.

Page Commands

Use explicit page-domain commands:

draft page ls --json
draft page create "Title" --json
draft page search "phrase" --json
draft page cat <page_id>
draft page append <page_id> "More content" --json
draft page replace <page_id> --heading "Status" "Updated body" --json
draft page patch <page_id> --json < change.diff
draft page annotate <page_id> --anchor "exact text" --note "Reviewer note" --json
draft page comments <page_id> --json
draft page comment <comment_id> <page_id> --json
draft page publish <page_id> --json

Temporary top-level page aliases such as draft ls, draft cat, and draft patch still emit legacy-alias metadata in JSON responses. Prefer the draft page ... namespace.

JSON Workspace Folder Target

For page commands that should operate on a JSON Workspace folder instead of the default local page store, pass:

draft --workspace-json <folder> page ls --json
draft --workspace-json <folder> page search "phrase" --json
draft --workspace-json <folder> page cat <page_id> --json
draft --workspace-json <folder> page create "Title" --json
draft --workspace-json <folder> page append <page_id> "More content" --json
draft --workspace-json <folder> page replace <page_id> --heading "Status" "Updated body" --json
draft --workspace-json <folder> page patch <page_id> --json < change.diff
draft --workspace-json <folder> page annotate <page_id> --anchor "exact text" --note "Reviewer note" --json
draft --workspace-json <folder> page comments <page_id> --json
draft --workspace-json <folder> page insert-image <page_id> ./image.png --json
draft --workspace-json <folder> page update-image <page_id> <local_id> --width 320 --json
draft --workspace-json <folder> page delete-image <page_id> <local_id> --json
draft --workspace-json <folder> page reparent <page_id> root --json
draft --workspace-json <folder> page delete <page_id> --json
draft --workspace-json <folder> page check --json
draft --workspace-json <folder> page publish <page_id> --json

This is a headless file-backed page target, not legacy CLI workspace mode. JSON page command output includes meta.source with the active storage model, workspace path, path source, and capability flags so agents can verify the target before writing.

Patch Contract

draft page patch applies a unified diff to the page body markdown only.

• Valid patch surface: the current body markdown content, for example # Status, blank lines, and body text.
• Not a valid patch surface: the decorated human draft page cat <page_id> wrapper lines such as Title:, ID:, and the surrounding --- separators.
• Not a valid patch surface: draft page cat <page_id> --json, because that returns block JSON, not patchable markdown lines.
• JSON Workspace and headless-local use the same body-markdown patch contract.

Minimal valid example:

--- a
+++ b
@@ -1,3 +1,3 @@
 # Status

-Original
+Updated Patched

If a patch fails with PATCH_MISMATCH, reread the page, regenerate the diff from the current body markdown surface only, and retry.

Workspace Path Anchoring

The CLI can persist and inspect the active JSON Workspace path for agent workflows:

draft workspace status --json
draft workspace path --json
draft workspace set ~/.draft/workspace --json
draft workspace set-path ~/.draft/workspace --json
draft workspace reset --json

In this release, page commands that must operate on JSON Workspace data should still pass the resolved path with --workspace-json <folder>. A later migration can route default page commands to JSON Workspace once headless storage is retired.

Secret Share

Secret Share creation is a hosted Worker operation, but encryption happens locally in the CLI before anything is sent to the Worker. The API key authorizes creation only; it does not decrypt the share.

Configure the API key once:

draft auth set-key "<secret-share-api-key>"
draft auth status

For CI or one-off automation, use an environment variable:

DRAFT_SECRET_SHARE_API_KEY="<secret-share-api-key>" \
  draft secret create --file ./brief.md --json

Create a password-protected share:

draft secret create --file ./brief.md --password "<reader-password>" --expires 1h --json

Read a Secret Share:

draft secret open "<secret-url-or-id>" --password "<reader-password>" --json

Image IDs

For image mutations, draft page insert-image ... --json returns local_id. That identifier is the same value exposed as the image block id in draft page cat <page_id> --json.

Use that returned local_id for later mutations:

draft --workspace-json <folder> page insert-image <page_id> ./image.png --json
draft --workspace-json <folder> page cat <page_id> --json
draft --workspace-json <folder> page update-image <page_id> <local_id> --width 320 --json
draft --workspace-json <folder> page delete-image <page_id> <local_id> --json

Troubleshooting

• DAEMON_OFFLINE: run draft start-server, then draft status --json.
• PAGE_NOT_FOUND: run draft page ls --json and retry with a valid page ID.
• PATCH_MISMATCH: reread the page body markdown, regenerate the diff from that surface only, and retry.

Built by Innosage LLC for the Performance-First web.