CLI Reference

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:

1. Connect + handshake
2. credentials:healthCheck
3. system:versions
4. system:homeDir
5. workspaces:get
6. sessions:get
7. LLM_Connection:list
8. sources:get
9. sessions:create (temporary __cli-validate-* session)
10. sessions:getMessages
11. Send message + stream (text response)
12. Send message + tool use (Bash tool)
13. sources:create (temporary Cat Facts API source)
14. Send + source mention (uses the created source)
15. Send + skill create (writes SKILL.md via Bash)
16. skills:get (verify skill appears)
17. Send + skill mention (invokes the created skill)
18. skills:delete (cleanup)
19. sources:delete (cleanup)
20. sessions:delete (cleanup)
21. 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