ccwf-cli

# ccwf CLI

`ccwf` is the command-line entry into cc-wf-studio — a visual AI-agent workflow tool. It treats `.vscode/workflows/*.json` workflow files as inputs and lets you render them as Markdown, validate the schema, open them in a browser-based viewer, convert them into Agent Skills, or execute them. The same workflow JSON also drives the VSCode extension and an MCP server, so you can pick whichever interface fits the situation.

This Skill teaches Claude how to recognise when `ccwf` is the right answer and which subcommand to reach for. The subcommands and flags listed here are the source of truth — if behaviour seems off, check `ccwf <subcommand> --help` first.

## Prerequisites

Confirm `ccwf` is available before running any other subcommand:

```bash
ccwf --version
```

If `ccwf` is not on PATH:

- **Preferred**: install globally — `npm install -g @cc-wf-studio/cli`
- **Without install**: prefix every command with `npx @cc-wf-studio/cli` (e.g. `npx @cc-wf-studio/cli render <file>`)
- **In a project**: `pnpm add -D @cc-wf-studio/cli` and run via `pnpm exec ccwf`

If the user has a VSCode workspace and you can't find a workflow file, search `.vscode/workflows/*.json` first; that's the canonical location.

## Core workflow

The natural flow when the user has a workflow file in hand:

1. **`ccwf validate <file>`** — schema-check it. Exit 0 = clean, exit 1 = errors. Run this first whenever you receive a workflow from elsewhere.
2. **`ccwf preview <file>`** — opens a read-only viewer (Mermaid + per-node Markdown) in the browser. Use this when the user says "show me" / "what's in this workflow?" / "見せて".
3. **`ccwf export <file>` or `ccwf run <file>`** — materialises the workflow as Claude Code (or another agent's) Skill files. Use `run` when the user wants the next step to be actually executing the workflow with `claude`.

If a step fails, stop and surface the exact error to the user before moving on.

## Subcommand reference

### `ccwf render <file>`

Print a Markdown bundle (Mermaid flowchart + per-node execution instructions) to stdout. Use when piping to another tool or pasting into a PR / chat message.

```bash
ccwf render ./.vscode/workflows/my-workflow.json             # Markdown (default)
ccwf render ./.vscode/workflows/my-workflow.json -f mermaid  # ```mermaid block only
```

Output is the same content `ccwf preview` shows in the right pane.

### `ccwf validate <file>`

Schema-check the workflow JSON.

```bash
ccwf validate ./.vscode/workflows/my-workflow.json           # exit 0/1, human-readable errors on stderr
ccwf validate ./.vscode/workflows/my-workflow.json --json    # prints { valid, errors[] }
```

Use this:
- Before `ccwf run` / `ccwf export` if the file is hand-edited or AI-generated
- In CI / pre-commit hooks
- When the user asks "is this workflow OK?" / "壊れてない?"

### `ccwf preview <file>`

Open a **read-only viewer** in the browser. Mermaid flowchart on the left, per-node Markdown on the right. Auto-reloads when the file changes on disk. Auto-shuts down 30s after the last viewer tab closes.

```bash
ccwf preview ./my-workflow.json                  # boot, open browser
ccwf preview ./my-workflow.json --port 51234     # pin to a port
ccwf preview ./my-workflow.json --keep-alive     # don't auto-shutdown when the tab closes
```

Use when the user says any of: "show me", "preview", "what does this workflow do?", "open it in a browser", "見せて", "可視化して".

The printed URL has the shape `http://localhost:<port>/<uuid>/`. The UUID just keeps two concurrent preview sessions from clobbering each other — it isn't a security boundary, since the server only listens on the loopback interface by default.

### `ccwf canvas <file>` (experimental)

Open the **full editable canvas** in the browser (same UI as the VSCode extension). Saves write back to the workflow file. Heavier than `preview`; reach for it only when the user explicitly wants to edit without VSCode.

```bash
ccwf canvas ./my-workflow.json
```

Other VSCode-only features (Slack share, Claude API upload, MCP server management, agent-specific export buttons) return a `CANVAS_UNSUPPORTED` error in this mode — they require the extension proper.

### `ccwf export <file> [--agent <name>]`

Materialise the workflow as **Agent Skill files** for a target agent. Pure file write, no execution.

```bash
ccwf export ./my-workflow.json                                 # --agent claude-code (default)
ccwf export ./my-workflow.json --agent cursor                  # cursor
ccwf export ./my-workflow.json --agent codex --cwd /tmp/proj   # codex, custom output root
ccwf export ./my-workflow.json --overwrite                     # replace existing files
```

Output by `--agent`:

| `--agent`              | Files emitted (relative to `--cwd` or `process.cwd()`)                                       |
|------------------------|----------------------------------------------------------------------------------------------|
| `claude-code` (default)| `.claude/agents/<sub-agent>.md` (inline SubAgent nodes) + `.claude/skills/<workflow>/SKILL.md` |
| `antigravity`          | `.agent/skills/<workflow>/SKILL.md`                                                          |
| `codex`                | `.codex/skills/<workflow>/SKILL.md`                                                          |
| `copilot`              | `.github/skills/<workflow>/SKILL.md`                                                         |
| `cursor`               | `.cursor/skills/<workflow>/SKILL.md` + `.cursor/agents/<sub-agent>.md`                       |
| `gemini`               | `.gemini/skills/<workflow>/SKILL.md`                                                         |
| `roo-code` (Zoo Code)  | `.roo/skills/<workflow>/SKILL.md`                                                            |

Use `export` (rather than `run`) when the user wants the *files only* — e.g. checking generated content into git, inspecting before execution, or generating Skills for multiple agents in