@innosage/draft-cli

Agent-native, local-first bridge for the Draft editor.

The Draft CLI is a high-performance command-line interface designed to bridge the gap between your local terminal, AI agents, and the Draft block-based editor. It enables deterministic, programmatic access to your documents with sub-100ms latency.

🚀 Why Draft CLI?

• Agent-First Design: Built for "Flow State" automation. AI agents can launch a daemon and immediately interact with documents without manual browser confirmation.
• Zero-Friction Handshake: Uses a secure, token-based pairing model that bypasses traditional API friction while maintaining strict local security.
• Local-First Performance: Communicates directly with the PWA's local IndexedDB via a secure WebSocket relay.
• Deterministic Operations: Specifically designed for programmatic editing with support for unified diffs, semantic section replacement, and atomic appends.

📦 Installation

npm install -g @innosage/draft-cli

🛠 Core Workflow

1. Establish the "Wire" (Server)

To connect your terminal to the Draft editor, start the server in the background. This returns your shell immediately and prepares the local daemon lifecycle.

# Start in headless v2 mode (default)
draft start-server

# Keep the deprecated browser-backed flow runnable for compatibility
draft start-server --runtime v1_DEPRECATED

# Start in workspace mode (for repository-backed markdown editing)
draft start-server --mode workspace --workspace <root>

2. Check Connection

draft status --json

If status reports BROWSER_NOT_CONNECTED, run draft daemon to pair or retarget a browser tab.

3. Manage Documents By Domain

Use explicit command domains:

• draft page ... for page-domain commands
• draft workspace ... for workspace-domain navigation, binding resolution, and workspace-native mutations

| Command | Description | | :------------------------------------------- | :------------------------------------------------------------- | ----------- | --------------------------------------- | | draft open <path> | Open a workspace markdown file in the editor. | | draft workspace ls | List workspace files/folders under the active root. | | draft workspace resolve <target> | Resolve path | document_id | page_id to canonical binding identity. | | draft workspace cat <target> | Read workspace file content by path | document_id | page_id. | | draft workspace append <target> | Append markdown directly to a workspace-bound file. | | draft workspace replace <target> --heading | Replace a section body in a workspace-bound file. | | draft workspace patch <target> | Apply unified diff directly to workspace file content. | | draft workspace comments <target> | List durable workspace comment artifacts. | | draft workspace annotate <target> | Create live annotation and persist durable workspace artifact. | | draft page annotate <id> | Create a highlight annotation on a page ID. | | draft page ls | List all available Draft pages in the paired tab. | | draft page cat <id> | Read a page (supports --format markdown\|json). | | draft page create "Title" | Create a new page. | | draft page append <id> | Append content to a page (supports stdin). | | draft page replace <id> | Preserve matched heading; replace only section body. | | draft page patch <id> | Apply a unified diff to a page. |

Legacy top-level content commands are in staged Phase 5 deprecation. Top-level draft annotate and draft comments list now hard-error with replacement guidance. Remaining top-level page content aliases (draft ls, draft cat, draft patch, etc.) remain temporary compatibility aliases and include meta.legacy_alias metadata in --json responses. Top-level lifecycle commands (start-server, stop, status, daemon) remain first-class.

4. Migration Examples (Phase 5)

| Legacy command | Namespaced replacement | Why this boundary exists | Status (as of 2026-04-12) | | :--------------------------- | :------------------------------ | :--------------------------------------------- | :------------------------------------------------ | ---------------------------------------------------------- | -------------------- | | draft ls --json | draft page ls --json | ls enumerates page IDs, not workspace files. | Legacy alias with warning metadata | | draft patch <page_id> | draft page patch <page_id> | Page patch mutates page-domain content only. | Legacy alias with warning metadata | | draft comments list <path> | draft workspace comments <path | document_id | page_id> | Durable review artifacts are workspace-domain data. | Hard-error (retired) | | draft annotate <path> | draft workspace annotate <path | document_id | page_id> | Workspace annotation must resolve workspace binding first. | Hard-error (retired) | | draft annotate <page_id> | draft page annotate <page_id> | Page annotation is page-domain and ID-scoped. | Hard-error at top-level; namespaced path required |

Staged retirement targets for remaining top-level page aliases:

• 2026-05-15: draft ls, draft cat
• 2026-06-15: draft create, draft append, draft replace
• 2026-07-15: draft patch, draft publish, draft comments, draft comment

🤖 For AI Agents

The Draft CLI is the preferred interface for AI agents interacting with human-authored documents.

💡 Tip: To quickly equip your agent with these capabilities, install the official Draft Skill.

• Atomic Mutations: Use patch to apply precise changes without rewriting the entire document.
• Semantic Targeting: Use replace --heading "Context" to replace only the section body while keeping the matched heading (for sections like "Summary" or "Action Items").
• Lifecycle Control: Prefer draft start-server / draft stop-server for daemon lifecycle, and use draft daemon for pairing or retargeting the browser tab.

🧯 Troubleshooting

• DAEMON_OFFLINE: run draft start-server, then draft status --json.
• BROWSER_NOT_CONNECTED: run draft daemon, then draft status --json.
• EDITOR_NOT_READY: mount a real page route (https://draft.innosage.co/#/page/<id>), then re-run draft status --json before retrying writes.

Built by Innosage LLC for the Performance-First web.