CLI reference

Common behaviour

• agentloom --version prints the version, and -h is --help, on agentloom and on every command.
• Warnings go to stderr, such as a retry or a parse warning. agentloom --log-level LEVEL COMMAND, or AGENTLOOM_LOG_LEVEL, shows more or less: see Logs.
• Paths are checked: a workflow, agent or recording that doesn’t exist is a usage error, exit 2.
• --json prints only JSON on stdout. Lines such as Running workflow: … go to stderr, and runs and history print [] when they find nothing. A command that stops before it has a result, such as on a workflow that doesn’t load, prints nothing on stdout and the error on stderr.

Every run, replay and resume writes a record to agentloom_runs/<run_id>.json, or under AGENTLOOM_RUNS_DIR: see history.

run

agentloom run [OPTIONS] WORKFLOW_PATH

The summary shows the status, duration, tokens and cost of the run and of each step and, with --checkpoint, the commands to resume a paused run. With --json, the result has status, step_results, final_state, total_tokens, total_cost_usd, error and run_id.

• --record needs a live provider: it refuses a workflow with provider: mock, and --mock-responses. These conflicts exit with 2.
• --mock-responses with a file that doesn’t exist is a usage error, exit 2.
• A missing API key isn’t caught before the run: the first step fails with No provider registered for model …, after its retries.

validate

agentloom validate WORKFLOW_PATH

For examples/03_router_workflow.yaml:

Workflow 'customer-support-router' is valid.
  Version:  1.0
  Steps:    5
  Layers:   3
  Provider: openai
  Model:    gpt-4o-mini
  Budget:   $0.05

  Execution plan:
    Layer 0: classify
    Layer 1: route
    Layer 2: handle_billing, handle_general, handle_technical (parallel)

It loads the file as run does, agent files included, and checks every field, dependency, router target and subworkflow path, and that there is no cycle. Steps that can run in parallel and write the same output key get a warning. An error prints Validation FAILED: and exits with 1.

It doesn’t check what only a run finds: an inline subworkflow’s steps, a Pydantic schema’s import, tool names, prompt templates, keys or recordings. See What validate checks.

visualize

agentloom visualize [--format ascii|mermaid] WORKFLOW_PATH

ascii, the default, prints one row per layer, with a box per step, such as [IF/ELSE: route]. mermaid prints a Mermaid flowchart inside a ```mermaid fence, ready for a Markdown file. Both go to stdout.

Router edges in the Mermaid output carry the whole condition. For Graphviz DOT or PNML, use the Graph API.

replay

agentloom replay [OPTIONS] WORKFLOW_PATH --recording FILE

Runs a workflow against a recording made with run --record, without calling any provider. See Testing & replay.

• Replay is strict. A step the recording lacks fails the run. A changed prompt fails too, for entries that carry a request_hash, as run --record writes them; older recordings without one replay a changed prompt with its recorded answer.
• With --allow-default-fallback, a step in the recording gets its recorded answer, even if its prompt changed, with a warning.
• A cut needs a provider and its key only for the steps that run live. Steps before the cut replay until a call misses, and go live from there; one that goes live on a model with no provider fails, naming the model.
• Conflicting options, such as --record without a cut, and a --live-from or --force-live step the workflow doesn’t have, exit with 2.

verify-determinism

agentloom verify-determinism [OPTIONS] WORKFLOW_PATH --recording FILE

Replays the recording --runs times and compares the runs: the status, each step’s status, output and error, the final state and the event log. When the recording carries an event log, the replayed one must match it too.

It prints Deterministic: 2 replays of … give the same result and exits with 0, or prints the first difference as a diff and exits with 1. A replay that doesn’t end in success also exits with 1, unless you pass --allow-failed.

resume

agentloom resume [OPTIONS] RUN_ID

Continues a run from its checkpoint. Checkpoints and resume covers what runs again.

• A run whose workflow says provider: mock resumes against its recording.
• A value in --state is visible in the shell history and the process list, as any argument is.
• --state reaches the run’s own state. A subworkflow paused at a gate resumes from its own checkpoint, and its redacted keys stay redacted.
• An unknown run, or a decision for a run that isn’t paused, exits with 1. --approve with --reject exits with 2, and so does a subworkflow’s own checkpoint, <run id>.<step id>: the error names the run to resume.
• A decision for a gate that expired is ignored, and resume says so: the gate takes its on_timeout.

runs

agentloom runs [--checkpoint-dir DIR] [--json]

Lists the checkpoints, with each run’s id, workflow, status and last update, in UTC, and when a paused run’s gate expires. Subworkflows have rows of their own, as <run_id>.<step_id>. --json prints the checkpoints whole, state and definition included.

history

agentloom history [OPTIONS]

Lists the record of every run that ended, checkpointed or not, newest first.

A record holds the run’s id, time, workflow, a hash of its definition, status, the providers and models it used, cost, tokens, steps run, duration and error. Records are never deleted, and a resumed run replaces the record of its first part. A replay records the provider of the recording, not mock. Observability covers the record.

callback-server

agentloom callback-server [OPTIONS]

An HTTP server that resumes paused runs from their checkpoints, for approvals that come from another system.

• /approve and /reject answer 202 and then resume the run. The outcome reaches the checkpoint and the run’s record, not the caller. An unknown run answers 404, a run that isn’t paused 409, and a config file that stopped loading after the server started 500.
• A decision for a run the server is already resuming answers 409.
• A gate inside a subworkflow is decided on the run at the top. The child’s own run id, the one with a dot, answers 400 and names that run; a link whose ?gate=<path> isn’t where the run is paused answers 409.
• A decision for a gate that expired answers 202 with expired_at: the gate takes its on_timeout.
• The server resumes each run whose gate expired, without a request: it looks every 30 seconds, and at the next expiry it knows of.
• With --token, every endpoint but /webhook answers 401 without the right header. A server on an address other than loopback, without a token, prints a warning: anyone who reaches it can decide. The token is a command-line argument, visible to other users of the machine in its process list.
• Runs with provider: mock can’t resume here: the server sets up only live providers. Use agentloom resume.
• A gate’s webhook can’t reach a server on localhost or a private address unless the workflow sets sandbox.allow_internal_webhook_targets: true. See The webhook.

agent inspect

agentloom agent inspect [--json] AGENT_PATH

Prints an agent’s definition as it loads, without running it: its model and prices, system prompt, tools with their parameters, the agents it calls, its loop policy, output schema and constraints. A file that isn’t a valid agent prints the errors and exits with 1.

info

agentloom info

Prints the AgentLoom version, the Python version and platform, the core dependencies and the observability extra, and the providers: OpenAI, Anthropic and Google as configured when their key is set, and Ollama’s address. It never prints a key.

What’s next

• Testing & replay

  Recordings, replay, cuts and fault injection.

• Reliability

  Exit statuses, checkpoints and resuming runs.

• Providers

  The keys and endpoints run reads.