CLI

halo is one binary: install it with curl -fsSL https://halolang.com/install.sh | sh (see Quickstart), update it with halo upgrade. This is halo --help from the current release:

txt

$ halo --help
Halo CLI - AI Workflow Language

USAGE:
  halo run <file.halo> [options]        Run a pipeline
  halo debug <file.halo> [options]      Run with stage-by-stage tracing
  halo test <file.halo> [options]       Run offline: --mock plus --auto-approve
  halo resume <file.halo> <runId>       Continue a paused run (--payload '<json or word>')
  halo replay <file.halo> <runId>       Rerun a recorded run with the answers it got: no model
                                        or tool calls (--live-models or --live-tools to redo one side)
  halo validate <file.halo|dir ...>     Check syntax and semantics
  halo parse <file.halo>                Print the AST as JSON
  halo init [name]                      Create a new Halo project
  halo upgrade                          Update an installed halo to the latest release
  halo serve [files|dirs ...]           Serve pipelines: HTTP API, webhooks, schedules,
                                        approval links, MCP at /mcp, and Halo Studio at /
  halo plan <file.halo>                 Show what a run could do: model calls and worst-case
                                        cost, tool calls and their effects, approvals
  halo mcp [files|dirs ...]             Serve pipelines as MCP tools over stdio

TOOL PACKAGES:
  halo search [query]                   Find tool packages in the registry
  halo add <name[@version]|file|url|dir> Install a tool package (--trust if it runs code)
  halo remove <name>                    Uninstall a tool package
  halo install [--trust]                Install everything halo.lock pins (--trust: also the
                                        packages that run code; trust is never read from the lock)
  halo tools [--json]                   List every tool provider and its methods
  halo pack <dir>                       Bundle a package folder into a .halotool file
  halo publish <file.halotool> --registry <index.json>   Add it to a registry index

RUN OPTIONS:
  --pipeline, -p <name>  Pipeline to run (default: the file's entry pipeline)
  --arg <key=value>      Input argument (repeatable; values parse as JSON when possible)
  --args '<json>'        Input arguments as a JSON object
  --mock                 Mock every agent and tool call (no network, no API keys)
  --auto-approve         Approve every |! yield and ~> listen automatically
  --checkpoint <file>    Resume from a @checkpoint snapshot
  --api-key <key>        API key for any provider without its own env var
  --router '<json>'      Router configuration, e.g. '{"strategy":"cost-optimized"}'
  --json                 Print the full run result (output, meta, trace) as JSON
  --no-telemetry         Don't record this run for Halo Studio (.halo/telemetry.db)
  --no-record            Don't keep a recording for halo replay (.halo/recordings)

  Without a terminal (and without --auto-approve), a run that reaches |! yield
  or ~> listen pauses and prints the command that continues it.

RESUME OPTIONS:
  --payload <value>      The response: JSON, or a word like approve/reject (default: approve)
  --event <name>         What the run is waiting for (default: whatever it is waiting for)

SERVE OPTIONS:
  --port <n>             Port (default 8080)
  --host <addr>          Interface (default 127.0.0.1; others need HALO_SERVE_TOKEN)
  --config <file>        Config file (default ./halo.json if present): schedules,
                         webhooks, notify.slack, publicUrl, files
  --no-studio            Don't serve Halo Studio

VALIDATE OPTIONS:
  --strict               Treat warnings as errors

ENVIRONMENT:
  OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY,
  TOGETHER_API_KEY, REPLICATE_API_TOKEN, HALO_API_KEY (fallback), OLLAMA_HOST

EXAMPLES:
  halo run examples/01-hello.halo --arg name=World --mock
  halo debug examples/06-gates.halo --arg name=Ana --arg lang=es --mock
  halo validate examples/

Every halo run keeps a recording in .halo/recordings for halo replay (--no-record turns that off) and records telemetry for Halo Studio in .halo/telemetry.db (--no-telemetry). Exit status is 0 on success, 1 on a failed run or validation errors.

CLI ​

CLI