CLI reference

The native executable is agl. During development, invoke it with cargo run --; after installation, use agl directly. Mock mode is deterministic and does not require credentials.

Run, check, and inspect a source file

agl <source.agent> [pipeline-or-workflow] [options]

The source file is parsed, imported modules are loaded, diagnostics are emitted, and the program is statically checked before execution. A pipeline/workflow name is required for execution, --lower, and --effects; it is not required for --check, --test, --format, --docs, --api, or --summary.

Flag	Description
--input JSON	Object containing pipeline inputs; default {}.
--check	Parse, load imports, analyze, and type-check without executing.
--test	Run every test block in the source file.
--format	Print canonical AGL source and exit.
--lower	Print the selected pipeline/workflow after workflow lowering.
--effects	Print inferred transitive effects as JSON.
--summary	Print effects, external writes, and approval boundaries as JSON.
--docs PATH	Write generated Markdown API documentation.
--api PATH	Write a machine-readable public API snapshot.
--deployment PATH	Load provider-neutral agent bindings from JSON.
--policy PATH	Enforce effect, tool, network, and filesystem policy.
--adapter mock\|openai\|live\|anthropic	Select the task/model adapter. live is an OpenAI compatibility alias.
--trace-live	Emit model/tool trace lines to stderr.
--output-trace PATH	Write the structured execution trace to a JSON file.
--event-store PATH	Persist durable events and checkpoints in the local SQLite-backed store.
--execution-id ID	Choose a stable durable execution identity; requires --event-store.
--resume	Replay checkpoints for the selected durable execution; requires --event-store.
--approval NAME=BOOL	Supply an approval or rejection; may be repeated.
--eval NAME	Run a declared dataset evaluation.
--update-baseline	Replace the selected evaluation baseline; requires --eval.
--plugin MODULE	Load a Python compatibility plugin by path or dotted name; may be repeated.

Examples:

cargo run -- examples/blog.agent blog_post \
  --input '{"topic":"agent memory patterns"}'
cargo run -- examples/showcase_all_features.agent --check
cargo run -- examples/showcase_all_features.agent --test
cargo run -- examples/multiagent_blog.agent publish_topic_blog --lower
cargo run -- examples/blog.agent blog_post --effects
cargo run -- examples/blog.agent blog_post --summary
cargo run -- examples/blog.agent blog_post --output-trace trace.json

Input keys and values are checked against the declared pipeline signature before execution. Errors use stable diagnostic codes and include source locations where available.

REPL

cargo run -- repl --adapter mock

The REPL is stateful. Load a source file, then run a named pipeline:

AGL REPL (adapter=mock). Type 'help' for commands, 'exit' to quit.
> load examples/blog.agent
Loaded 'examples/blog.agent': 2 agents, 2 tasks, 1 pipelines.
> run blog_post {"topic":"agent memory"}
{
  "result": "[writer] Draft article:\n[planner] key points for 'agent memory'"
}

Commands are load <path>, run <name> [json], lower <name>, list, clear, help, and exit. REPL options also accept --deployment, --plugin, and --trace-live.

Tooling subcommands

These commands are intercepted by the native binary and do not use the source-file CLI:

agl protocol                 # JSON-lines compiler protocol over stdin/stdout
agl lsp                      # LSP server over stdio
agl completions bash         # bash completion script (also zsh and fish)
agl package lock agl.json    # write agl.lock
agl api-compare old.json new.json

The protocol accepts structured parse/check/format/lower/effects requests. The LSP server supports diagnostics, completion, hover, definition, references, rename, and formatting.

Live adapters and environment

export OPENAI_API_KEY="sk-..."
cargo run -- examples/incident_runbook.agent respond_to_incident \
  --adapter openai --trace-live \
  --input '{"incident":"database failover drill"}'

export ANTHROPIC_API_KEY="sk-ant-..."
cargo run -- examples/incident_runbook.agent respond_to_incident \
  --adapter anthropic --trace-live \
  --input '{"incident":"database failover drill"}'

Variable	Meaning
OPENAI_API_KEY	Credential for the OpenAI adapter.
ANTHROPIC_API_KEY	Credential for the Anthropic adapter.
AGL_OPENAI_MODEL	Optional OpenAI model override.
AGL_ANTHROPIC_MODEL	Optional Anthropic model override.

Never put credentials in .agent files or deployment/policy JSON.

Exit status

0 means the requested operation succeeded. 1 means a source, type, runtime, provider, plugin, policy, or evaluation failure. 2 means invalid CLI arguments or an unsupported completion shell.