Rulvar API reference / @rulvar/cli
@rulvar/cli
The Rulvar ops shell: the rulvar binary (run, resume, runs, inspect, plan, kb), TUI progress, the embeddable HTTP server with SSE events and external-input resolution (createServer), the queue worker over any leasable store (createWorker), and the OpenTelemetry exporter (toOtel).
Part of Rulvar, an embeddable TypeScript engine for durable, budget-bounded multi-agent LLM workflows, where a completed LLM call is never paid for twice. Full documentation: docs.rulvar.com.
Install
bash
pnpm add @rulvar/cli
pnpm exec rulvar --helpDocumentation
License
Interfaces
| Interface | Description |
|---|---|
| AssembledCli | - |
| CliConfig | The shape both the config module and a workflow module may export. |
| CliIo | - |
| CommandContext | - |
| CreateServerOptions | - |
| CreateWorkerOptions | - |
| KbSweepCliConfig | The kb sweep config: a FIXED pool (sweep volume is never authorized by proposal volume) plus the cases per taskClass. Structural sweep shapes only: the CLI's static dependency stays @rulvar/core and @rulvar/evals loads dynamically at command time (the plan-command precedent), so graders and cases are typed by the config module. |
| LoadedWorkflowModule | - |
| OtelContextApi | Minimal OTel context surface (setSpan/with) for parentage. |
| RulvarServer | - |
| SpanLike | The tiny subset of the OTel Tracer/Span API the exporter uses. |
| ToOtelOptions | - |
| TracerLike | - |
| Worker | - |
Type Aliases
| Type Alias | Description |
|---|---|
| PreflightDeclaration | The preflight declaration a config or workflow module may export (the experiment-review P2.2): the declared spawn wave, the orchestrator spec, and the quota rule set behind the configured limiter, exactly the PreflightInput slices the estimator cannot derive from engineOptions alone. rulvar preflight merges the workflow module's declaration over the config file's, and --spawns overrides the spawn wave from the command line. |
Variables
| Variable | Description |
|---|---|
| DEFAULT_MAX_BUFFERED_EVENTS_PER_RUN | The default per-run replay-buffer bound (RV409): generous enough that any ordinary run keeps its full replay (lifecycle events number in the hundreds; only long agent:stream delta torrents approach tens of thousands), small enough that one delta-heavy run cannot grow process memory past a few tens of megabytes. Past the bound the oldest events are dropped and the replay marks the gap; the journal remains the durable record. Before v1.94.0 an absent maxBufferedEventsPerRun meant unbounded; set an explicit huge bound (Number.MAX_SAFE_INTEGER) to restore that in effect. |
| DEFAULT_MAX_PENDING_EVENTS_PER_CLIENT | The default per-connection pending-frame bound: generous enough that a reading consumer never notices (a normal reader keeps the queue near empty), small enough that a consumer that stopped reading cannot grow process memory past a few megabytes per connection. |
| DEFAULT_STORE_DIR | - |
| DEFAULT_WORKER_TTL_MS | Appendix A: the committed reference lease ttl. |
| HELP | @rulvar/cli: the Rulvar shell (https://docs.rulvar.com/guide/cli). M5 surface: run/resume/runs ls/inspect over the canonical grammar, TUI progress on the event stream, interactive resolution of suspended approvals and externals. plan/kb commands land M6+/M10; createServer/createWorker land M8; the OTel exporter lands M5-T08. |
Functions
| Function | Description |
|---|---|
| assembleEngine | - |
| attachProgress | Attaches the renderer to a handle's event stream; returns a detach. |
| costAuditCommand | cost-audit (RV1910): the denominator diagnostic over one stored run. The four-role benchmark's recovery run produced four mutually inconsistent cost views; the lifecycle now admits one, and this command VERIFIES it on a concrete journal instead of trusting the doctrine: the roster is closed (every agent entry terminal), the settle is recorded and is the billing boundary, and the settled fold, the invoice totals and the wire cardinality agree. Exit 1 with the failing checks named when any diverge, which is exactly what a pre-RV1904 journal (the benchmark's own) reports. --all (RV2209) runs the same six checks over EVERY run the store lists, one summary row each, exit 1 when any run diverges: the parity sessions audited seven journals one invocation at a time, and a catalog posture check should cost one command. |
| createServer | - |
| createWorker | - |
| driveRun | Drives a handle to a terminal outcome, resolving suspensions interactively and resuming until the run settles or input runs dry. |
| inspectCommand | - |
| invoiceCommand | rulvar invoice (P1.3): the per-dispatch reconciliation export from the journal's providerCalls ledger, one row per billable provider call with the provider's response id when the adapter surfaced one, plus the gross/net ledger totals (totalUsd here is the GROSS figure: abandoned subtrees included, exactly what a provider invoice bills). --json prints the machine-readable InvoiceExport; the text form prints one line per row and mirrors the export's declared pricing basis honestly (RV511): fully attributed runs price per request and the rows sum to gross; an aggregate-priced remainder or legacy entry makes the export say row usd is non-additive, and allocatedUsd is the additive column that sums to gross in every case. Pricing folds at read time from the run's settle pins composed with the assembled price table (RV611), the same numbers rulvar inspect reports and the engine's own settle mirrors. |
| loadCliConfig | Loads rulvar.config.mjs/.js from cwd; absent config is fine. |
| loadWorkflowModule | Imports a workflow module given on the command line. |
| looksLikeFile | True when the run target names a file rather than a registry entry. |
| preflightCommand | rulvar preflight (the experiment-review P2.2; grammar in grammar.ts): the effective-config linter and dry-run estimator. Loads the SAME config, module, and run-profile merge rulvar run would assemble, but constructs no engine, opens no store, and dispatches nothing: the report is computed by preflightEstimate over options alone, so the command cannot pay for a single provider token by construction. The declared spawn wave comes from the preflight export of the config or workflow module (module wins), and --spawns JSON overrides it from the command line. --json prints the machine-readable report. Exit 1 when any finding has severity 'error' (the linter contract: green preflight means the run can at least start), 0 otherwise. |
| processIo | The process-backed io the bin entry uses. |
| renderEventLine | Renders one event to a line, or undefined for silent event types. The composed line is sanitized so an untrusted provider/tool/log string cannot inject a control sequence or a second physical line (v1.21.0 review P2-1). |
| reportOutcome | Renders the settled outcome; returns the process exit code. Error messages, suspension keys, model refs, and phase names originate from providers, tools, and workflow authors, so each is sanitized before it reaches a terminal line, matching the TUI renderer (v1.24.1 review P2-1). Values print as JSON, which escapes control bytes on its own. |
| resumeCommand | - |
| runCli | @rulvar/cli: the Rulvar shell (https://docs.rulvar.com/guide/cli). M5 surface: run/resume/runs ls/inspect over the canonical grammar, TUI progress on the event stream, interactive resolution of suspended approvals and externals. plan/kb commands land M6+/M10; createServer/createWorker land M8; the OTel exporter lands M5-T08. |
| runCommand | - |
| runsLsCommand | - |
| strictExitCode | --strict (the v1.40.0 improvement plan's completion contract): a settled ok run whose orchestration acceptance envelope reports a completion other than 'complete' exits nonzero, with the degraded reasons printed. Outcomes without an acceptance envelope (a workflow that never opted into orchestrate acceptance) and nonzero exit codes pass through unchanged, so the flag never masks the ordinary status exit and never bites a plain workflow. |
| toOtel | Exports one run's event stream onto a tracer. The run's events are consumed in seq order; span openers start spans, the matching closers end them, and payload-only events attach as span events on the innermost open span. Returns the number of spans created. Every terminal path exports, the unsettled ones included (RV1106): a rejecting result never fails an export the stream already completed, it only marks any leftover span with the refusal. |