Skip to content

cli.md

Latest commit

 

History

History
493 lines (334 loc) · 13.1 KB

cli.md

File metadata and controls

493 lines (334 loc) · 13.1 KB

CLI Reference

The boruna binary is the primary interface for compiling, running, inspecting, and managing .ax programs and workflows.

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–E009)

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 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]

Subcommands:
  list   List available skill documents
  get    Print one skill document (ax-language, cli, workflows, diagnostics)

skills get exits 1 on an unknown skill name and lists the available names.

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 serve <bundle-dir/> [--port <port>]
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 serve

Start a local web UI to browse an evidence bundle.

boruna evidence serve <bundle-dir/> [--port <port>]

Serves a read-only inspector at http://localhost:<port> (default: 4444). Requires the serve feature:

cargo run --features boruna-cli/serve --bin boruna -- evidence serve ./bundles/my-run/

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