CLI Reference

The craft-cli is a terminal client that connects to a running Craft Agent headless server over WebSocket. It provides commands for listing resources, managing sessions, sending messages with real-time streaming, and validating server health.

Installation

# Clone the repository
git clone https://github.com/anthropics/craft-agents.git
cd craft-agents

# Install dependencies
bun install

# Option A: Run directly
bun run apps/cli/src/index.ts <command>

# Option B: Link globally (adds craft-cli to PATH)
cd apps/cli && bun link
craft-cli <command>

Quick Start

The fastest way to try it out — no server setup needed:

# Self-contained run (spawns a server automatically)
ANTHROPIC_API_KEY=sk-... bun run apps/cli/src/index.ts run "Hello, world!"

Connection Options

Flag	Env Variable	Default	Description
`--url <ws[s]://...>`	`CRAFT_SERVER_URL`	—	Server WebSocket URL
`--token <secret>`	`CRAFT_SERVER_TOKEN`	—	Authentication token
`--workspace <id>`	—	auto-detect	Workspace ID
`--timeout <ms>`	—	`10000`	Request timeout
`--tls-ca <path>`	`CRAFT_TLS_CA`	—	Custom CA cert (self-signed TLS)
`--json`	—	`false`	JSON output for scripting
`--send-timeout <ms>`	—	`300000`	Timeout for `send` command

Flags override environment variables. If --workspace is omitted, the first available workspace is used automatically.

Commands

Info & Health

Command	Channel	Description
`ping`	handshake only	Verify connectivity — prints clientId and latency
`health`	`credentials:healthCheck`	Check credential store health
`versions`	`system:versions`	Show server runtime versions

Resource Listing

Command	Channel	Description
`workspaces`	`workspaces:get`	List all workspaces (id, name, path)
`sessions`	`sessions:get`	List sessions (id, name, preview, status)
`connections`	`LLM_Connection:list`	List LLM connections
`sources`	`sources:get`	List configured sources

Session Operations

Command	Channel	Description
`session create [--name <n>] [--mode <m>]`	`sessions:create`	Create a new session
`session messages <id>`	`sessions:getMessages`	Print message history
`session delete <id>`	`sessions:delete`	Delete a session
`cancel <id>`	`sessions:cancel`	Cancel in-progress processing

Send Message (Streaming)

craft-cli send <session-id> <message>
echo "Summarize this" | craft-cli send <session-id>

The send command subscribes to session:event and streams the AI response to stdout in real time:

Event Type	Output
`text_delta`	Text appended inline
`tool_start`	`[tool: name — intent]` marker
`tool_result`	Tool output (truncated to 200 chars)
`error`	Error to stderr, exit code 1
`complete`	Newline, exit code 0
`interrupted`	`[interrupted]`, exit code 130

Raw RPC

craft-cli invoke <channel> [json-args...]   # Send any RPC channel
craft-cli listen <channel>                   # Subscribe to push events

invoke sends a request to any channel and prints the response. listen subscribes to a push channel and prints events as they arrive (Ctrl+C to stop).

Run (Self-Contained)

craft-cli run <prompt>
craft-cli run --workspace-dir ./project --source github "List open PRs"

The run command is fully self-contained — it spawns a headless server, creates a session, sends the prompt, streams the response, and exits. No separate server setup needed. An API key is resolved from --api-key, $LLM_API_KEY, or a provider-specific env var (e.g., $ANTHROPIC_API_KEY, $OPENAI_API_KEY).

Flag	Default	Description
`--workspace-dir <path>`	—	Register a workspace directory before running
`--source <slug>`	—	Enable a source (repeatable)
`--output-format <fmt>`	`text`	Output format: `text` or `stream-json`
`--mode <mode>`	`allow-all`	Permission mode for the session
`--no-cleanup`	`false`	Skip session deletion on exit
`--server-entry <path>`	—	Custom server entry point

LLM Configuration:

Flag	Env Fallback	Default	Description
`--provider <name>`	`LLM_PROVIDER`	`anthropic`	Provider: `anthropic`, `openai`, `google`, `openrouter`, `groq`, `mistral`, `xai`, etc.
`--model <id>`	`LLM_MODEL`	(provider default)	Model ID (e.g., `claude-sonnet-4-5-20250929`, `gpt-4o`, `gemini-2.0-flash`)
`--api-key <key>`	`LLM_API_KEY`	(provider env)	API key — also checks provider-specific vars like `$OPENAI_API_KEY`
`--base-url <url>`	`LLM_BASE_URL`	—	Custom endpoint for proxies, OpenRouter, or self-hosted models

# Multi-provider examples
craft-cli run --provider openai --model gpt-4o "Summarize this repo"
GOOGLE_API_KEY=... craft-cli run --provider google --model gemini-2.0-flash "Hello"
craft-cli run --provider anthropic --base-url https://openrouter.ai/api/v1 --api-key $OR_KEY "Hello"

Validate Server

# Against a running server
craft-cli --validate-server --url ws://127.0.0.1:9100 --token <token>

# Self-contained (auto-spawns a server)
craft-cli --validate-server

When no --url is provided, --validate-server automatically spawns a local headless server, runs the validation, and shuts it down. Runs a 21-step integration test covering the full server lifecycle including source and skill creation:

Connect + handshake
credentials:healthCheck
system:versions
system:homeDir
workspaces:get
sessions:get
LLM_Connection:list
sources:get
sessions:create (temporary __cli-validate-* session)
sessions:getMessages
Send message + stream (text response)
Send message + tool use (Bash tool)
sources:create (temporary Cat Facts API source)
Send + source mention (uses the created source)
Send + skill create (writes SKILL.md via Bash)
skills:get (verify skill appears)
Send + skill mention (invokes the created skill)
skills:delete (cleanup)
sources:delete (cleanup)
sessions:delete (cleanup)
Disconnect

Note: This test mutates workspace state — it creates and deletes a temporary session, source, and skill. All resources are cleaned up on completion. Continues on failure and reports a summary. Use --json for machine-readable output:

craft-cli --validate-server --json | jq '.results[] | select(.status == "FAIL")'

Troubleshooting

Symptom	Cause	Fix
Connection timeout	Server not running	Verify server URL and that it’s started
`AUTH_FAILED`	Wrong token	Check `CRAFT_SERVER_TOKEN` matches
`PROTOCOL_VERSION_UNSUPPORTED`	Version mismatch	Update CLI and server
WebSocket error	Network/TLS issue	Use `--tls-ca` for self-signed certs

​CLI Reference

​Installation

​Quick Start

​Connection Options

​Commands

​Info & Health

​Resource Listing

​Session Operations

​Send Message (Streaming)

​Raw RPC

​Run (Self-Contained)

​Validate Server

​Troubleshooting