The craft command accepts various flags to customize its behavior. Use these when starting Craft Agents from the terminal.
Usage
If you provide a prompt, Craft Agents starts with that message. Otherwise, it opens the interactive interface.
Available Flags
—help
Show help information and exit.
—version
Show the current version number and exit.
The version is displayed in the header status bar while running, but this flag lets you check it quickly from the command line.
—model, -m
Select which Claude model to use.
craft --model opus
craft -m sonnet
craft -m haiku
| Value | Model |
|---|
opus | Claude Opus - most capable |
sonnet | Claude Sonnet - balanced (default) |
haiku | Claude Haiku - fastest |
—agent, -a
Activate a sub-agent immediately on startup.
craft --agent research
craft -a research "Find articles about AI"
craft -a work/code-review
—workspace, -w
Select which workspace to use.
craft --workspace "Work Projects"
craft -w Personal
—debug
Enable debug logging. Writes detailed logs to /tmp/craft-debug.log.
Useful for troubleshooting connection issues or unexpected behavior.
—print, -p
Print mode - outputs response and exits. Useful for scripting and automation.
craft -p "List my tasks due today"
craft --print "What's in my daily note?"
craft -p "Summarize my meeting notes" > summary.txt
text.
craft -p "List tasks" --output-format json
craft -p "Summarize document" --output-format stream-json
| Format | Description |
|---|
text | Plain text response (default) |
json | Structured JSON with response, tool calls, and usage |
stream-json | Newline-delimited JSON events for real-time processing |
—permission-policy
Control bash command permissions in headless mode. Default is deny-all.
craft -p "Check git status" --permission-policy allow-safe
craft -p "Run tests" --permission-policy allow-all
| Policy | Behavior |
|---|
deny-all | Block all bash commands (safest, default) |
allow-safe | Allow read-only commands (ls, cat, grep, find, etc.) |
allow-all | Allow all commands (use with caution) |
allow-all permits any shell command including destructive operations. Only use in trusted, controlled environments.
—session-resume
Resume the last session instead of starting fresh. Useful for multi-turn automation.
craft -p "Continue where we left off" --session-resume
—session
Use an explicit session ID for workflow management. Allows multiple related commands to share context.
craft -p "Step 1: Find the document" --session my-workflow-123
craft -p "Step 2: Summarize it" --session my-workflow-123
—url
Override the MCP server URL. For advanced users connecting to custom MCP endpoints.
craft --url "https://custom.mcp.server/endpoint"
—token
Provide a bearer token for MCP authentication. Used with --url for custom connections.
craft --url "https://..." --token "your-bearer-token"
Combining Flags
Flags can be combined:
# Use Opus model with Research agent
craft -m opus -a research
# Print mode with specific workspace
craft -w Work -p "Show my tasks"
# Debug mode with custom model
craft --debug -m haiku "Quick question"
Examples
Quick Query
Get information without entering interactive mode:
craft -p "What tasks do I have due this week?"
Scripted Automation
Use in shell scripts:
#!/bin/bash
TASKS=$(craft -p "List incomplete tasks as JSON")
echo "$TASKS" | jq '.tasks[]'
Workspace-Specific Command
Run a command in a specific workspace:
craft -w "Client Project" -p "Summarize recent updates"
Agent with Prompt
Activate an agent and send a prompt immediately:
craft -a research "Find recent news about renewable energy"
Debug Session
Start with debugging enabled:
craft --debug
# Then check /tmp/craft-debug.log for details
Environment Variables
Some behavior can also be controlled via environment variables:
| Variable | Purpose |
|---|
ANTHROPIC_API_KEY | Anthropic API key (alternative to stored credential) |
DISABLE_AUTOUPDATER | Set to 1 to disable auto-updates |
Exit Codes
| Code | Meaning |
|---|
0 | Success |
1 | Error (check output for details) |
-p), the exit code indicates whether the request completed successfully. 
