CLI Reference
The boruna binary is the primary interface for compiling, running, inspecting, and managing .ax programs and workflows.
Version
boruna --version (or -V) prints boruna <version>. The other binaries (boruna-mcp,
boruna-pkg, boruna-orch) do the same.
Installation
cargo build --workspace
# Binary at: target/debug/boruna
To use boruna without cargo run --bin boruna --, add target/debug/ to your PATH or install with:
cargo install --path crates/llmvm-cli
Top-level commands
boruna <command> [options]
Commands:
compile Compile a .ax file to bytecode
run Run a .ax file
trace Run and emit an execution trace
replay Replay from a recorded event log
inspect Inspect a compiled module
ast Print the AST for a .ax file
lang Language diagnostics, repair, and the code registry
doctor Environment and toolchain health checks
size Bytecode artifact size report for a .ax file
framework Framework app validation and testing
workflow Workflow validation, execution, and graph inspection
evidence Evidence bundle inspection and verification
template Template listing and application
skills Embedded, agent-curated documentation
trace2tests Generate regression tests from traces
boruna compile
Compile a .ax source file to bytecode.
boruna compile <file.ax>
Outputs the compiled module summary (functions, capabilities declared). Does not execute.
boruna run
Compile and run a .ax file.
boruna run <file.ax> [options]
Options:
--policy <name> Capability policy: allow-all, deny-all (default: deny-all)
--record Write an event log to .boruna/runs/<id>/
--live Enable real capability handlers (requires http feature)
--trace Emit a full execution trace to stdout
--step-limit <n> Abort if execution exceeds n steps
--watch Re-run on every change to the file (post-1.0)
Examples:
# Run in demo mode (no capabilities)
boruna run examples/hello.ax
# Run with all capabilities allowed
boruna run app.ax --policy allow-all
# Run with real HTTP (requires --features boruna-cli/http)
cargo run --features boruna-cli/http --bin boruna -- run app.ax --policy allow-all --live
# Watch mode — re-run on every save until Ctrl-C
boruna run app.ax --watch
Watch mode
--watch re-executes the file on every change. Filesystem events
are debounced to 200ms, so a single editor save triggers exactly
one rerun even on platforms that emit a flurry of events per save.
A separator line marks each rerun:
── reloading app.ax at 14:03:11 ──
3
steps: 4
A failed run (compile error or runtime panic) does not exit
watch mode — the error is printed and the watcher waits for the
next save. Press Ctrl-C to exit.
Watch combines with the standard run flags:
boruna run app.ax --watch --policy ./policy.json --record events.json.
boruna trace
Run a .ax file and emit a step-by-step execution trace.
boruna trace <file.ax> [--policy <name>]
boruna replay
Replay execution from a recorded event log.
boruna replay <file.ax> --from <event-log-path> [--verify]
Options:
--verify Compare replay output to recorded output; fail if they differ
boruna inspect
Inspect a compiled bytecode module.
boruna inspect <file.ax>
Prints: function table, constant pool, declared capabilities, bytecode disassembly.
boruna ast
Print the parsed AST for a .ax file as JSON.
boruna ast <file.ax> [--json]
boruna lang
Language diagnostics and auto-repair.
boruna lang check <file.ax> [--json]
boruna lang repair <file.ax>
boruna lang codes [--json]
Subcommands:
check Run diagnostics: type errors, undeclared capabilities, unreachable code
repair Apply auto-repair suggestions from diagnostics
codes List the registry of stable diagnostic codes (E001–E010)
Examples:
# Check for errors with machine-readable output
boruna lang check app.ax --json
# Automatically repair issues
boruna lang repair app.ax
# Resolve a diagnostic code seen in `lang check --json` output
boruna lang codes --json
lang codes emits the registry from docs/reference/diagnostic-codes.md. Codes
are stable forever — tools and agents may switch on them.
boruna doctor
Environment and toolchain health checks.
boruna doctor [--json]
Reports the binary version, which optional features were compiled in, whether a
Rust toolchain is reachable, the persistent data directory’s writability, and
whether the current directory looks like a Boruna project root. Read-only.
Exits 1 if any check has error status.
boruna size
Bytecode artifact size report for a .ax source file.
boruna size <file.ax> [--json]
Compiles the file and reports per-function opcode counts, module-wide totals
(functions, ops, constants, types, globals), and the serialized .axbc
artifact byte size. Nothing is written to disk.
boruna confidence
Calibrated confidence for approval gates. See docs/design-conformal-gating.md.
boruna confidence threshold <calibration.json> --alpha-permille <1..999> [--score <0..1000>] [--json]
Reads a labelled calibration set and prints the score at or above which a gate may skip a
human, so that a wrong answer is auto-approved with probability at most alpha. Also
prints how the calibration set itself would have behaved at that threshold, and the
decision for --score when given. When the set has too few wrong examples to certify
alpha (at least ceil(1000 / alpha_permille) - 1 are needed), the threshold is never and
every case goes to a human. Exits 1 on an invalid file or alpha.
boruna skills
Embedded, agent-curated documentation — compiled into the binary so an agent can learn Boruna from the installed binary alone.
boruna skills list [--json]
boruna skills get <name> [--json]
boruna skills emit <dir>
boruna skills pack "<query>" [--budget <tokens>] [--json]
Subcommands:
list List available skill documents
get Print one skill document (ax-language, cli, workflows, diagnostics)
emit Write every skill as <dir>/<name>/SKILL.md (name + description frontmatter)
pack Return only the sections relevant to a query, within a token budget
skills get exits 1 on an unknown skill name and lists the available names.
The cli skill ends with a command reference generated from the installed binary, so it
lists exactly the commands and flags that exist. A unit test fails when a hand-written
skill names a boruna <command> that does not exist.
skills emit is idempotent and overwrites existing files. skills pack ranks sections
by keyword overlap with the query (ties broken by skill name and position), so the same
query always returns the same bytes. --budget is an estimate (characters / 4, default
2000); the best section is truncated rather than dropped if it alone exceeds it. Exits 1
when nothing matches.
boruna framework
Validate and test framework apps (Elm-architecture .ax apps with init/update/view).
boruna framework validate <file.ax>
boruna framework test <file.ax> [options]
Options for test:
-m <messages> Comma-separated message sequence, e.g. "increment:1,reset:0"
Examples:
boruna framework validate examples/framework/counter_app.ax
boruna framework test examples/framework/counter_app.ax -m "increment:1,increment:1,reset:0"
boruna workflow
Validate and run workflow DAGs.
boruna workflow validate <workflow-dir/>
boruna workflow run <workflow-dir/> [options]
Options for run:
--policy <name> Capability policy (default: deny-all)
--record Write evidence bundle to .boruna/runs/<id>/
--live Enable real capability handlers
--replay <dir> Replay from an existing evidence bundle
--verify (with --replay) Verify outputs match recorded values
Examples:
# Validate DAG structure
boruna workflow validate examples/workflows/llm_code_review
# Run in demo mode
boruna workflow run examples/workflows/llm_code_review --policy allow-all
# Run and record evidence
boruna workflow run examples/workflows/llm_code_review --policy allow-all --record
# Run with real HTTP and LLM calls
cargo run --features boruna-cli/http --bin boruna -- \
workflow run examples/workflows/llm_code_review \
--policy allow-all --live --record
boruna workflow schedule
Run a workflow on a cron schedule. Loops until SIGINT (Ctrl-C).
boruna workflow schedule <workflow-dir/> [options]
Options:
--cron <expr> 5-field cron expression (required), e.g. "*/5 * * * *"
--policy <name> Capability policy (default: deny-all)
--data-dir <dir> Directory for runs.db and per-run output (default: .boruna/data)
--max-concurrency <n> Maximum concurrent runs; skips tick if a run is already active (default: 1)
--live Enable real capability handlers (requires http feature)
When a scheduled tick fires while a previous run is still active, that tick is skipped.
boruna workflow eval
Run a workflow against two LLM provider configurations and compare evidence bundles.
boruna workflow eval <workflow-dir/> --providers-a <file.json> --providers-b <file.json> [options]
Options:
--providers-a <file> First provider config JSON file (required)
--providers-b <file> Second provider config JSON file (required)
--runs <n> Runs per provider (default: 1)
--data-dir <dir> Directory for evidence bundles
--json Machine-readable output
Reports per-step output agreement and timing differences between the two provider sets.
boruna workflow find
Recursively discover workflow.json files under a directory tree.
boruna workflow find [dir] [--json]
Validates each discovered workflow and prints path, name, step count, and validity. dir defaults to the current directory. Use --json for a JSON array.
boruna workflow graph
Emit the workflow DAG as structured graph facts.
boruna workflow graph <dir> [--json]
Reports nodes (each step’s kind, capabilities, and dependencies), edges,
topological execution order, roots (steps with no dependencies), and leaves
(steps nothing depends on). Read-only — only workflow.json is read, step
source files are not. Exits 1 if the graph contains a cycle (is_dag: false).
boruna evidence
Inspect, verify, and manage evidence bundles.
boruna evidence create <run-id> --output-dir <dir> [--data-dir <dir>]
boruna evidence verify <bundle-dir/> [--bundle-encryption-key <hex>]
boruna evidence inspect <bundle-dir/> [--json] [--decrypt] [--bundle-encryption-key <hex>]
boruna evidence diff <bundle-a> <bundle-b> [--json]
boruna evidence gc-blobs [--data-dir <dir>] [--dry-run] [--json]
boruna evidence rotate-kek <target> --old-kek <hex> --new-kek <hex> [options]
Examples:
# Build a bundle from a completed run
boruna evidence create abc123def456 --output-dir ./bundles
# Inspect a bundle
boruna evidence inspect .boruna/runs/20260315-143022-abc4d/
boruna evidence inspect .boruna/runs/20260315-143022-abc4d/ --json
# Verify a bundle
boruna evidence verify .boruna/runs/20260315-143022-abc4d/
evidence inspect
For plaintext (non-encrypted) bundles, evidence inspect automatically shows step output content from outputs/<step_id>/result.json. Each step output is truncated at 500 characters in text mode. With --json, the full parsed content appears under the "step_outputs" key. Encrypted bundles print a hint to stderr if --decrypt / --bundle-encryption-key is not supplied.
evidence create
Build an evidence bundle from a persisted run. Reads the run’s metadata, step checkpoints, and hash-chained audit log; writes a bundle directory with workflow.json, policy.json, per-step outputs, audit_log.json, env_fingerprint.json, and manifest.json. Bundles are created on demand — the runner does not auto-create them.
boruna evidence create <run-id> --output-dir <dir> [--data-dir <dir>]
The bundle is written to <output-dir>/<run-id>/.
evidence diff
Compare two evidence bundles side-by-side.
boruna evidence diff <bundle-a> <bundle-b> [--json]
Reports differences in workflow metadata, step outputs, audit event counts, and verification status. Use --json for machine-readable output.
Examples:
boruna evidence diff .boruna/runs/run-baseline/ .boruna/runs/run-rerun/
boruna evidence diff baseline/ rerun/ --json
evidence gc-blobs
Sweep orphaned content-addressed blobs from the data directory.
boruna evidence gc-blobs [--data-dir <dir>] [--dry-run] [--json]
An orphan is a blob file no longer referenced by any run checkpoint. Reports {deleted, skipped, bytes_freed}. Use --dry-run to report without deleting.
evidence rotate-kek
Rotate the key-encryption key (KEK) on one or more encrypted bundles without re-encrypting file content.
boruna evidence rotate-kek <target> --old-kek <hex> --new-kek <hex> [options]
Options:
--kek-id-from <id> Only rotate bundles whose current kek_id matches (safety check)
--kek-id-to <id> kek_id written to the rotated manifest (default: "default")
--dry-run Print planned actions without modifying any bundle
--parallelism <n> Parallel bundle limit in batch mode (default: min(8, num_cpus))
<target> may be a single bundle directory or a parent directory whose immediate subdirectories are bundles (batch mode).
boruna template
List and apply app templates.
boruna template list
boruna template apply <name> [options]
Options for apply:
--args <key=value,...> Template variable substitutions
--validate Validate the generated output after applying
Examples:
boruna template list
boruna template apply crud-admin --args "entity_name=products,fields=name|price" --validate
Available templates: crud-admin, form-basic, auth-app, realtime-feed, offline-sync
boruna trace2tests
Generate regression tests from execution traces.
boruna trace2tests <trace-file> --output <test-dir/>
See TRACE_TO_TESTS.md for details.
Global options
--help Print help for any command
--version Print the Boruna version