CLI Reference

CLI Reference

Sandcastle provides 27 top-level CLI commands. All commands support the global --json flag for machine-readable output.

Setup & Server

sandcastle init

Interactive setup wizard. Creates .env file with:

• Sandbox backend selection (E2B, Docker, Local, Cloudflare)
• API keys for AI providers (Anthropic, OpenAI, etc.)
• License key prompt
• Optional Redis, PostgreSQL, S3 configuration

sandcastle init

sandcastle serve

Start the API server and dashboard.

sandcastle serve                # Default: http://0.0.0.0:8080
sandcastle serve --port 9090    # Custom port
sandcastle serve --host 127.0.0.1  # Localhost only

sandcastle doctor

Run local diagnostics. 7 sections:

1. Python version and dependencies
2. Environment variables and .env
3. Database connectivity
4. Sandbox backend health
5. AI provider API key validation
6. Tool/connector status
7. License verification

sandcastle doctor
sandcastle doctor --json    # Machine-readable output

sandcastle health

Quick API health check.

sandcastle health

---

Workflow execution

sandcastle run

Run a workflow from a YAML file or workflow name.

sandcastle run workflow.yaml                          # Run from file
sandcastle run lead-enrichment --input '{"company":"Acme"}'  # By name with input
sandcastle run my-workflow --callback https://...      # With callback URL

sandcastle generate

Generate a workflow from natural language description.

sandcastle generate "Monitor competitor pricing daily and alert on Slack"
sandcastle generate "Summarize all PDFs in a folder" --model sonnet

sandcastle status

Show run status and step details.

sandcastle status <run_id>
sandcastle status <run_id> --json

sandcastle cancel

Cancel a running workflow.

sandcastle cancel <run_id>

sandcastle logs

Stream real-time run events (SSE).

sandcastle logs <run_id>     # Stream until complete

sandcastle replay

Replay a run from a specific step.

sandcastle replay <run_id> --from-step analyze

sandcastle fork

Fork a run with modifications.

sandcastle fork <run_id> --input '{"company":"NewCo"}'

---

Resource listing

sandcastle ls

List resources.

sandcastle ls runs                 # List recent runs
sandcastle ls runs --status failed # Filter by status
sandcastle ls workflows            # List workflow files
sandcastle ls schedules            # List schedules

sandcastle runs

Run management subcommands.

sandcastle runs list               # List all runs
sandcastle runs compare <id1> <id2>  # Compare two runs

sandcastle templates

List available templates.

sandcastle templates               # List all 118 templates
sandcastle templates --json        # Machine-readable

---

Scheduling

sandcastle schedule

Manage cron schedules.

sandcastle schedule create lead-enrichment --cron "0 9 * * MON-FRI"
sandcastle schedule create seo-audit --cron "0 0 * * 0"  # Weekly
sandcastle schedule delete <schedule_id>

---

Approvals

sandcastle approve

Approve a paused approval step.

sandcastle approve <approval_id>
sandcastle approve <approval_id> --note "Looks good, ship it"

sandcastle reject

Reject a paused approval step.

sandcastle reject <approval_id>
sandcastle reject <approval_id> --note "Needs revision"

---

API key management

sandcastle keys

Manage API keys.

sandcastle keys list
sandcastle keys create --name "CI Pipeline"
sandcastle keys create --name "Temp" --expires 7d
sandcastle keys delete <key_id>
sandcastle keys rotate <key_id>

---

Dead letter queue

sandcastle dlq

Manage failed runs.

sandcastle dlq list
sandcastle dlq retry <dlq_id>
sandcastle dlq resolve <dlq_id>

---

Tools & Integrations

sandcastle tools

Manage connectors.

sandcastle tools list                  # List all 56 tools
sandcastle tools configure slack       # Set up Slack credentials
sandcastle tools configure github      # Set up GitHub token

---

Community Hub

sandcastle hub

Browse and manage community templates.

sandcastle hub search "lead enrichment"
sandcastle hub search --category marketing
sandcastle hub install revenue-forecast-ensemble
sandcastle hub list                    # List installed community templates
sandcastle hub publish my-workflow.yaml
sandcastle hub collections             # List curated collections
sandcastle hub install-collection complete-sales-stack

---

Advanced

sandcastle eval

Run evaluation suite against a workflow.

sandcastle eval my-workflow --suite quality-checks

sandcastle mcp

Start MCP (Model Context Protocol) server.

sandcastle mcp --url http://localhost:8080

sandcastle violations

View policy violations.

sandcastle violations list
sandcastle violations list --severity critical

sandcastle autopilot

Manage A/B testing experiments.

sandcastle autopilot list
sandcastle autopilot deploy <experiment_id>

sandcastle db migrate

Run database migrations.

sandcastle db migrate

sandcastle worker

Start background worker (for Redis/arq queue).

sandcastle worker

---

Global flags

Flag	Description
--json	Output in JSON format (all commands)
--help	Show help for any command
--version	Show Sandcastle version