CLI reference

Generated from the command tree in cmd/halo; do not edit. Regenerate with make docs-gen.

Global flag: --output text|json. Commands that read a policy repo take --policy-dir D (default .). halo validate exits 0 when valid and 2 on validation errors; other failures exit 1 with error: ... on stderr.

The other binaries (halod, halo-proxy, halo-server, halo-shadow) are covered in Binaries and runtime configuration.

Usage

halo

Flags

Flag	Shorthand	Type	Default	Description
--output		string	text	output format: text|json

Commands

Command	Description
halo admin	Sync vendor admin consoles (Claude, ChatGPT/Codex, Gemini, Copilot, Cursor) with policy (ADR-0025)
halo agents	Delegated and remote (A2A) agents (ADR-0024)
halo artifact	Digest, scan and sign agent extension artifacts (skills, plugins, hooks, commands, agents; ADR-0028)
halo audit	Inspect halo-server’s hash-chained audit log
halo budget	Gateway cost budgets: spend per user, group, ring and org
halo ci	Governed gateway credentials and config for headless CI / cloud agents
halo cloud-agents	Govern cloud and background coding agents: render workflows, list tasks, kill (ADR-0034)
halo controller	Automated experiment loop (evaluate, kill on rollback, PRs, notify)
halo copilot	AI-assisted policy operations: the model drafts, Halos verifies, a human approves (ADR-0035)
halo dlp	Gateway data-loss prevention and prompt-injection defense (ADR-0033)
halo doctor	Check this machine and the policy repo; print the exact fix for each problem
halo egress	Explain the sandbox egress policy (ADR-0032)
halo eject	Write simple mode’s generated Gateway, Profile and Rings out as files and drop the simple keys from halos.yaml
halo enable	Enable an MCP server or hook for everyone (profile) or a cohort (toggle)
halo eval	Offline replay evals
halo exp	Manage experiments
halo explain	Print the full low-level policy halos.yaml expands to, or with –user one user’s effective config and which layer set each field
halo export	Export a signed release for a delivery channel
halo freeze	Change freezes: policy windows and the incident freeze (ADR-0030); rollbacks are never frozen
halo gateway	Compile gateway artifacts from the policy repo
halo harnesses	Show the harness capability matrix
halo init	Create a policy repo: one simple halos.yaml (–full for the multi-file scaffold)
halo keys	Signing key management
halo kill	Kill an experiment, toggle or rollout fleet-wide via halo-server (effective at the next poll)
halo mcp	Model Context Protocol server for agents
halo migrate	Rewrite policy documents from apiVersion halos.dev/v1alpha1 to halos.dev/v1
halo model	Change which model an alias routes to
halo onboard	Agent-friendly onboarding steps: detect, local, install, proxy, verify, company (dry run unless –apply)
halo plan	Diff the release each ring (or –ring) would get against a previous release, and with –diff who is affected
halo quickstart	Try it: bring up the whole stack on Docker (make demo), open the console and print a guided tour
halo release	Build, publish and promote releases
halo render	Render a ring’s harness config files under –out, mirroring absolute paths
halo roi	Delivery ROI of a policy change: PR outcomes per experiment arm (ADR-0027)
halo rollback	Point a ring (and its experiment channels) back at an earlier signed release (version or manifest digest)
halo rollout	Phased rollouts: plan, status, simulate; advance opens a PR, never merges
halo sessions	Agent session ledger: one identity-linked record per agent session (ADR-0031)
halo status	One screen: rings, rollouts, live experiments, toggles and policy health
halo telemetry	Telemetry pipeline artifacts
halo toggle	Feature toggles: list, evaluate, kill, find stale
halo units	Org hierarchy: business units and teams with delegated owners (ADR-0018)
halo upgrade	Watch upstream CLIs and models; open eval-gated upgrade PRs (never merges)
halo validate	Load and validate a policy repo (exit 2 on errors)
halo version	Print the halo version
halo whoami	Show the ring and experiment variants a user is assigned