draft-cli

---
name: "draft-cli"
description: "Use draft for JSON Workspace page-domain Draft operations and hosted Secret Share helpers."
license: "MIT"
---

# Draft CLI Skill

Use `draft` for JSON Workspace page-domain Draft operations and hosted Secret Share helpers.

## Current Runtime Contract

- Prefer the saved JSON Workspace as the default page target.
- Use workspace metadata commands before page commands so you know which folder and source the CLI is using.
- Until headless storage is removed, pass the resolved workspace path with `--workspace-json <folder>`
  for page commands that must operate on JSON Workspace data.

## Workspace-First Pattern For Page Commands

For page commands such as `draft page ls`, `draft page cat`, `draft page create`,
`draft page append`, `draft page replace`, `draft page patch`, `draft page annotate`, and
`draft page publish`:

```bash
draft workspace status --json
draft workspace path --json
```

Use the returned `active_workspace_path` to anchor page commands explicitly:

```bash
draft --workspace-json <active_workspace_path> page ls --json
draft --workspace-json <active_workspace_path> page cat <page_id> --json
```

For an explicit folder override, anchor the command with `--workspace-json`:

```bash
draft --workspace-json <folder> page ls --json
draft --workspace-json <folder> page cat <page_id> --json
```

If the user wants that folder to become the default workspace, set it first:

```bash
draft workspace set-path <folder> --json
draft workspace status --json
```

Use the workspace metadata to confirm whether the CLI is operating on the saved default path or an
explicit override before you describe results back to the user.

## Version Detection And Older CLI Fallback

Newer CLIs can expose workspace metadata commands such as:

```bash
draft workspace status --json
draft workspace path --json
draft workspace set-path <folder> --json
```

If those commands are unavailable, detect that once and fall back safely:

```bash
draft workspace --help
draft --workspace-json <folder> page ls --json
```

- If `draft workspace --help` or `draft workspace status --json` fails with an unknown-command
  style error, assume the CLI is older.
- On older CLIs, require an explicit folder and run page commands with
  `draft --workspace-json <folder> ...`.
- If the user did not provide a folder and the CLI lacks workspace commands, ask for the JSON Workspace folder path or ask them to upgrade the CLI.

## Page Commands

Prefer explicit `draft page ...` commands under a JSON Workspace target. In the transition period,
include `--workspace-json <folder>` so the command cannot accidentally hit legacy headless storage:

```bash
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 comment <comment_id> <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 publish <page_id> --json
```

### Agent-Native Read Guidance

- Prefer `draft --workspace-json <folder> page cat <page_id>` for rendered page reads meant for
  human review. The markdown surface preserves links, marks, tables, images, ordered lists, line
  breaks, and custom blocks better than manual rendering from `pages/*.json`.
- Use `draft --workspace-json <folder> page cat <page_id> --json` only when you need structured
  block data for parsing or automation. It is larger than the markdown read surface.
- Treat raw workspace JSON files as a last resort for recovery or low-level inspection, not the
  default read path.
- For discovery, prefer `draft --workspace-json <folder> page search "phrase" --json` when the CLI
  supports it. On older CLIs without page search, use `rg` over workspace page files only to
  discover candidate page IDs or titles, then switch back to `draft --workspace-json <folder> page
  cat <page_id>` for authoritative rendered output.

## Patch Contract

`draft page patch` applies unified diffs to the page body markdown only. Do not generate patches
from decorated human `page cat` output that includes `Title:`, `ID:`, or `---` separator lines, and
do not generate patches from `page cat --json` block output.

Patch workflow:

```bash
draft --workspace-json <folder> page cat <page_id>
# Extract only the body markdown, build a unified diff against that body, then:
draft --workspace-json <folder> page patch <page_id> --json < change.diff
draft --workspace-json <folder> page cat <page_id> --json
```

Verify the patch output or follow-up `page cat` before running downstream commands that depend on
the edited text, such as `page annotate --anchor "new text"`. If patch returns `PATCH_MISMATCH`,
reread the current page body markdown, regenerate a fresh diff against that exact body surface, and
retry.

## Image Mutation Contract

`draft page insert-image` returns `local_id`. Use that returned `local_id` for subsequent
`update-image` and `delete-image` commands. In `page cat --json` compatibility output, the same
identifier is exposed as the image block `id`.

Top-level page aliases can still exist during compatibility windows, but agents should use the
`draft page ...` namespace.

## Public Preview Feedback

Public Draft preview and published URLs expose review feedback through the public page surface, not
through JSON Workspace page commands. Treat the public preview or published URL as the primary
machine-readable entrypoint for public review workflows. When the task starts from a public preview
or published URL, fetch that public URL first, parse its metadata/frontmatter, then use the
returned endpoints in priority order.

This direct public-page feedback read path does not require `draft`, `draft workspace status`,
`draft status`, a JSON Workspace folder, a daemon, or browser pairing. Do not run
`draft --workspace-json <folder> page comments <page_id> --json` just because the user supplied a
public URL.

Example for "read feedback from this public Draft preview URL":

1. Fetch the provided public preview or published URL.
2. Parse metadata/frontmatter and read `comments_api_url` and `task_toggles_api_url` as the P0
   endpoints.
3. Fetch `comments_api_url` directly to read human feedback and comments.
4. Fetch `task_toggles_api_url` directly to read review toggle state and task decisions.
5. If `source_snapshot_url` is present, treat it as a P1 optional structured published-content
   snapshot that helps match comments and toggles to the exact published body.
6. Summarize feedback and decision state, using `source_snapshot_url` only when it helps disambiguate
   the published content under review.

Retrieval order for public review reads:

1. Fetch public URL.
2. Parse metadata/frontmatter.
3. Fetch `comments_api_url`.
4. Fetch `task_toggles_api_url`.
5. Optionally fetch `source_snapshot_url`.
6. Summarize feedback and decision state.

If JSON Workspace comment commands return empty for a page that also has a public preview/published
URL, do not conclude there is no feedback or no decisions until you have checked that public URL for
`comments_api_url` and `task_toggles_api_url`.

CLI comment commands such as `draft --workspace-json <folder> page comments <page_id> --json` are
primarily for private or local Draft page workflows, live workspace pages, or local page
annotations. They are not the default public review path for preview or published URLs.

## Write And Share Guardrail

Read-only behavior is the safe fallback. Do not run write/share commands unless the user explicitly
asks for the exact action and target.

- write commands: `draft --workspace-json <folder> page create`, `draft --workspace-json <folder> page append`, `draft --workspace-json <folder> page replace`, `draft --workspace-json <folder> page patch`, `draft --workspace-json <folder> page annotate`
- share commands: `draft --workspace-json <folder> page publish`, `draft secret create`

Before returning a public or shareable URL, review the command output and confirm it is the requested
artifact.

## Secret Share

Secret Share commands are hosted/local-crypto helpers and do not require workspace checks,
`draft status`, or `draft start-server`.

Configure the API key:

```bash
draft auth set-key <secret-share-api-key>
draft auth status --json
```

Create a Secret Share:

```bash
draft secret create --file docs/brief.md --expires 1h --json
```

Read a Secret Share:

```bash
draft secret open '<secret_url_or_id>' --password "$DRAFT_SECRET_PASSWORD" --json
```

Use `--password` for password-protected shares. Use `DRAFT_SECRET_PASSWORD` only when the runtime
already provides it.

## Error Handling

- Unknown `draft workspace ...` command: fall back to `draft --workspace-json <folder> ...` and
  ask for the folder path when it is missing.
- Missing configured workspace path: use `draft workspace set-path <folder> --json` when the user
  wants a default, or use `draft --workspace-json <folder> ...` for a one-off command.
- `PAGE_NOT_FOUND`: run `draft --workspace-json <folder> page ls --json` and retry with a valid page ID.
- `PATCH_MISMATCH`: reread with `draft --workspace-json <folder> page cat <page_id>`, extract the page body markdown only, regenerate the patch against that exact body surface, and retry.
- `ANCHOR_NOT_FOUND`: reread the current page before annotating; do not annotate text that a failed patch did not create.
- Missing Secret Share API key: use `draft auth set-key`, `--api-key`, or `DRAFT_SECRET_SHARE_API_KEY`.