Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Command reference

Generated from boruna 3.5.0 --help when this site was built. For explanations and examples see the CLI guide.

boruna compile

  • boruna compile <FILE> [--output] — Compile a .ax source file to bytecode

boruna run

  • boruna run <FILE> [--policy] [--max-steps] [--record] [--live] [--record-net-to] [--replay-net-from] [--watch] [--providers] — Run a .ax source file or bytecode file

boruna trace

  • boruna trace <FILE> — Run with execution tracing enabled

boruna replay

  • boruna replay <FILE> <LOG> — Replay execution from a recorded event log

boruna inspect

  • boruna inspect <FILE> — Inspect a bytecode file

boruna ast

  • boruna ast <FILE> — Dump the AST of a .ax source file

boruna fmt

  • boruna fmt <FILE> [--check] — Format a .ax source file (canonical pretty-print)

boruna framework

  • boruna framework — Framework commands
  • boruna framework new <NAME> [--dir] — Create a new framework app from template
  • boruna framework validate <FILE> — Validate a .ax file conforms to the App protocol
  • boruna framework test <FILE> [--messages] — Run a framework app interactively with messages
  • boruna framework inspect-state <FILE> [--messages] — Inspect framework app state after running messages
  • boruna framework simulate <FILE> <MESSAGES> — Simulate a sequence of messages and display state transitions
  • boruna framework inspect <FILE> [--json] — Print App contract summary (State, Messages, Effects) — machine-readable
  • boruna framework diag <FILE> [--messages] — Structured diagnostics output (JSON)
  • boruna framework trace-hash <FILE> [--messages] — Run with tracing and print a stable hash of the trace
  • boruna framework replay <FILE> <LOG> — Replay a recorded cycle log and verify determinism

boruna lang

  • boruna lang — Language tooling commands (diagnostics, repair)
  • boruna lang check <FILE> [--json] [--output] — Check a source file and report diagnostics
  • boruna lang repair <FILE> [--from] [--apply] — Repair a source file using diagnostic suggestions
  • boruna lang codes [--json] — List the registry of stable diagnostic codes
  • boruna lang caps <FILE> [--json] — Report each function’s declared vs. inferred-needed capabilities and flag over-declarations (capabilities granted but never used)

boruna doctor

  • boruna doctor [--json] — Environment and toolchain health checks

boruna size

  • boruna size <FILE> [--json] — Report the bytecode artifact size of a .ax source file

boruna skills

  • boruna skills — Embedded, agent-curated documentation (list, get, emit, pack)
  • boruna skills list [--json] — List available agent skill documents
  • boruna skills get <NAME> [--json] — Print an agent skill document by name
  • boruna skills emit <DIR> — Write every skill as <DIR>/<name>/SKILL.md for an agent to load
  • boruna skills pack <QUERY> [--budget] [--json] — Return only the skill sections relevant to a query, within a token budget

boruna confidence

  • boruna confidence — Calibrated confidence for approval gates (threshold)
  • boruna confidence threshold <FILE> [--alpha-permille] [--score] [--json] — Show the auto-approve threshold a calibration file gives for a target false approval rate, and optionally the decision for one score

boruna trace2tests

  • boruna trace2tests — Trace-to-test tools (record, generate, run, minimize)
  • boruna trace2tests record <FILE> [--messages] [--out] — Record an execution trace from a framework app
  • boruna trace2tests generate [--trace] [--name] [--out] — Generate a test spec from a recorded trace
  • boruna trace2tests run [--spec] [--source] — Run a test spec against source code
  • boruna trace2tests minimize [--trace] [--source] [--predicate] [--out] — Minimize a failing trace using delta debugging

boruna template

  • boruna template — Template tools (list, apply, validate)
  • boruna template list [--dir] — List available templates
  • boruna template apply <NAME> [--dir] [--args] [--out] [--validate] — Apply a template with arguments

boruna literate

  • boruna literate — Literate workflow specs — extract embedded .ax/.qnt code fences from a markdown narrative into per-file outputs. See docs/architecture-literate-workflows.md
  • boruna literate extract <FILE> [--out-dir] [--json] [--verbose] — Extract <lang> <filename> += code fences from a markdown document into per-file outputs. Accepted languages: ax, boruna, quint. Other fences (rust, bash, …) are ignored. See docs/architecture-literate-workflows.md

boruna repl

  • boruna repl <FILE> [--policy] — Interactive REPL for .ax modules — load a file, evaluate expressions interactively, inspect the environment. See docs/architecture-boruna-repl.md

boruna simulate

  • boruna simulate <DIR> [--max-samples] [--seed] [--policy] [--invariant] [--witnesses] [--json] — Random property-based simulation of a workflow. Runs the workflow N times under a user-supplied invariant (and optional witnesses) and reports violation count + witness frequencies. See docs/architecture-boruna-simulate.md

boruna new

  • boruna new <TEMPLATE> [--dir] [--target] [--var] [--no-input] [--force] — Scaffold a new project from a template (interactive)

boruna workflow

  • boruna workflow — Workflow execution and validation
  • boruna workflow validate <DIR> [--print-hash] — Validate a workflow definition directory
  • boruna workflow run <DIR> [--policy] [--record] [--evidence-dir] [--encrypt-bundle] [--bundle-encryption-key] [--bundle-kek-id] [--live] [--data-dir] [--ephemeral] [--concurrency] [--skip-if-running] [--submit-only] [--expect-workflow-hash] [--bundle-storage] [--providers] — Run a workflow
  • boruna workflow approve <RUN_ID> <STEP_ID> [--data-dir] — Approve a paused approval-gate step. Records an approval sentinel in the run’s metadata; the operator must run boruna workflow resume <run-id> afterward to advance the run past the gate
  • boruna workflow reject <RUN_ID> <STEP_ID> [--reason] [--data-dir] — Reject a paused approval-gate step. Records a rejection sentinel; boruna workflow resume <run-id> will then halt the run as Failed with the optional reason as the error message
  • boruna workflow trigger <RUN_ID> <STEP_ID> [--token] [--payload] [--payload-file] [--data-dir] — Trigger a paused external_trigger step (sprint 0.3-S15). Records the supplied payload as the step’s output and primes resume to advance past the gate. Operator must run boruna workflow resume <run-id> afterward to actually execute downstream steps
  • boruna workflow show <RUN_ID> [--json] [--data-dir] — Show the full state of a single run: row, step checkpoints, and approval-gate decisions. Use --json for machine-readable output (jq-friendly). Reads from the same --data-dir as run/resume
  • boruna workflow list [--status] [--json] [--data-dir] — List runs in the persistent store. Optional –status filter
  • boruna workflow resume <RUN_ID> [--data-dir] [--workflow-dir] [--policy] [--live] [--concurrency] [--expect-workflow-hash] — Resume a previously-paused or crashed workflow run by id
  • boruna workflow schedule <DIR> [--cron] [--policy] [--data-dir] [--max-concurrency] [--live] — Run a workflow on a cron schedule in a long-running daemon process. Validates the cron expression on startup (fail fast), then loops: sleep until next fire time → invoke the runner API → log outcome. Ctrl-C / SIGTERM finish any in-progress run then exit cleanly
  • boruna workflow eval <WORKFLOW_DIR> [--providers-a] [--providers-b] [--runs] [--data-dir] [--json] — Run the same workflow against two LLM provider configs and compare outputs
  • boruna workflow find <DIR> [--json] — Find and inspect workflow definitions under a directory tree
  • boruna workflow graph <DIR> [--json] — Emit the workflow DAG as structured graph facts

boruna evidence

  • boruna evidence — Evidence bundle inspection and verification
  • boruna evidence create <RUN_ID> [--output-dir] [--data-dir] — Build an evidence bundle from a persisted run (sprint 0.4-S10). Reads the run’s metadata, step checkpoints, and hash-chained audit log; writes a bundle directory containing workflow.json, policy.json, per-step outputs, audit_log.json, env_fingerprint.json, and a manifest.json with bundle hash + per-file checksums
  • boruna evidence verify <DIR> [--bundle-encryption-key] [--expected-bundle-hash] [--require-encryption] [--verify-key] [--require-signature] — Verify an evidence bundle for integrity
  • boruna evidence inspect <DIR> [--json] [--itf] [--decrypt] [--bundle-encryption-key] — Inspect an evidence bundle’s manifest
  • boruna evidence gc-blobs [--data-dir] [--dry-run] [--json] — Sweep orphan blobs from the data-dir’s blobs/ tree (sprint W3-B). An orphan is a content-addressed blob file no longer referenced by any step_checkpoints.output_blob_ref row. Reports {deleted, skipped, bytes_freed}. Holds an exclusive write lock on runs.db for the duration of the sweep — see docs/design-blob-gc.md for the TOCTOU rationale
  • boruna evidence rotate-kek <TARGET> [--old-kek] [--new-kek] [--kek-id-from] [--kek-id-to] [--dry-run] [--parallelism] — Rotate the KEK on one or more encrypted evidence bundles (post1-T-2.4). Unwraps the DEK with the old KEK, re-wraps it under the new KEK, and atomically rewrites each bundle’s manifest.json. Per-file ciphertext is unchanged because the DEK itself does not change
  • boruna evidence redact <DIR> [--event] [--field] [--reason] — Verifiably redact one audit-log entry in an evidence bundle so PII can be removed from a SEALED bundle without breaking verification
  • boruna evidence diff <BUNDLE_A> <BUNDLE_B> [--json] — Compare two evidence bundles side-by-side (post1-evidence-diff). Reports differences in workflow metadata, step outputs, audit event counts, and verification status
  • boruna evidence attest <DIR> [--verify] [--signing-key] [--verify-key] [--output] — Emit (or verify) an in-toto Statement + DSSE envelope for the bundle’s runtime provenance, for interop with the supply-chain ecosystem (cosign verify-blob, in-toto-verify). Additive — does NOT touch the native bundle format. Writes attestation.intoto.dsse.json into the bundle directory
  • boruna evidence anchor <DIR> [--rekor-url] [--offline] [--verify] [--output] — Anchor a signed bundle in a Sigstore Rekor transparency log, adding an external witness + trusted timestamp on top of the bundle’s own hash chain (closes the “trust the recorder / silent backdating” hole). Builds a hashedrekord entry from the manifest’s bundle_hash + ed25519 signature. Three modes:
  • boruna evidence report <DIR> [--framework] [--format] — Generate a human-readable COMPLIANCE evidence-mapping report that maps a bundle’s actual contents to the specific regulatory obligation each one helps satisfy. Verifies the bundle first and stamps the verdict at the top; a tampered/unverifiable bundle produces a report that says so loudly. This is a technical mapping, NOT a certificate of compliance
  • boruna evidence otel <DIR> [--out] — Export the bundle’s execution as OpenTelemetry spans in OTLP/JSON — the file format any OTel collector ingests. No SDK dependency, no network: emit the document and POST it to a collector (or pipe it through the otlpjson file receiver) to surface the run in Jaeger, Tempo, Honeycomb, Datadog, etc

boruna capability

  • boruna capability — Capability surface inspection (versioned identity for caching)
  • boruna capability list [--json] — List all capabilities this binary exposes, with stable identity hash. Use capability_set_hash as part of a cache key to safely memoize deterministic results across binary upgrades. See docs/reference/capability-identity.md

boruna metrics

  • boruna metrics — Prometheus metrics export from the persistent run store (sprint 0.4-S12). See docs/design-prometheus-metrics.md for the architectural decision and operator integration pattern (cron + node_exporter’s textfile collector)
  • boruna metrics export [--data-dir] — Export current metrics in Prometheus text format to stdout. Pipe to a .prom file under node_exporter’s textfile collector directory:

boruna policy

  • boruna policy — Policy file validation and inspection (sprint 0.4-S15). See docs/design-policy-as-code.md and docs/reference/policy-schema.md for the schema and the stable error_kind taxonomy
  • boruna policy validate <FILE> [--json] — Strict-validate a policy file. Exits 0 on ok, 2 on validation error, 1 on file IO error. Designed as a CI gate
  • boruna policy show <FILE> — Validate then print the effective policy in human-readable form: default behavior, denormalized rule list, net policy bounds

boruna migrate

  • boruna migrate <KIND> <PATH> [--from] [--to] [--dry-run] [--in-place] — Migration tooling beta (sprint W5-C). Upgrades pre-1.0 Boruna artifacts to the current on-disk format. See docs/guides/migration.md for the coverage matrix and recommended workflow