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

You are reading the development version (master). For the latest release (v3.6.0) see the stable docs.

Command reference

Generated from boruna 3.6.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