npm package: @innosage/draft-cli
Description: CLI for managing Draft content locally
Author: Innosage LLC
Latest version: 0.9.18

# @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](https://draft.innosage.co) 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

```bash
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.

```bash
# Start in local mode (default)
draft start-server

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

### 2. Check Connection

```bash
draft status --json
```

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

### 3. Manage Documents

| Command                | Description                                            |
| :--------------------- | :----------------------------------------------------- |
| `draft open <path>`    | Open a workspace markdown file in the editor.          |
| `draft comments list`  | List persisted comment artifacts for a workspace path. |
| `draft annotate <id>`  | Create a highlight annotation on a page/path.          |
| `draft ls`             | List all available pages in the paired tab.            |
| `draft cat <id>`       | Read a document (supports `--format markdown\|json`).  |
| `draft create "Title"` | Create a new document.                                 |
| `draft append <id>`    | Append content to a document (supports stdin).         |
| `draft replace <id>`   | Preserve matched heading; replace only section body.   |
| `draft patch <id>`     | Apply a unified diff (ideal for AI agents).            |

## 🤖 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](https://github.com/innosage-llc/draft-skills).

- **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](https://innosage.co) for the Performance-First web.