Skip to main content

Usage and Audit Commands

Client-side commands for a company's consumption/cost/budget data and its governed-act audit trail. Every command here accepts the shared client options (--api-base, --api-key, --context, --profile, --json; see CLI Overview). Full flag lists are on the CLI Reference.

Usage is tokens, not money​

usage summary/by-* render cost_events — token counts and a costCents column priced from provider rate cards. This is not a bill: there is no invoicing or rating engine in this deployment (see the Grounded Caveat below). usage finance * is a separate, self-reported debit/credit ledger — still not an invoice, but a real currency figure someone entered, with its own estimated flag.

vagaris usage summary --company-id <id> [--from <iso8601>] [--to <iso8601>]
vagaris usage by-agent --company-id <id> [--from <iso8601>] [--to <iso8601>]
vagaris usage by-agent-model --company-id <id> [--from <iso8601>] [--to <iso8601>]
vagaris usage by-provider --company-id <id> [--from <iso8601>] [--to <iso8601>]
vagaris usage by-biller --company-id <id> [--from <iso8601>] [--to <iso8601>]
vagaris usage by-project --company-id <id> [--from <iso8601>] [--to <iso8601>]
vagaris usage window-spend --company-id <id>
vagaris usage quota-windows --company-id <id>

quota-windows is board-scoped and calls out to each configured provider adapter live; a slow or unreachable provider shows up as ok: false for that provider only, not as a command failure.

Budget​

vagaris usage budget overview --company-id <id>
vagaris usage budget set-company --company-id <id> --budget-monthly-cents <n>
vagaris usage budget set-agent --agent-id <id> --budget-monthly-cents <n>

set-company/set-agent are board-only writes to the existing monthly-cap field; they do not create or adjust a budget policy (thresholds, warn percent, hard-stop) — that is a separate server surface this namespace does not expose yet (see Grounded Caveat).

Finance ledger​

vagaris usage finance summary --company-id <id> [--from <iso8601>] [--to <iso8601>]
vagaris usage finance by-biller --company-id <id> [--from <iso8601>] [--to <iso8601>]
vagaris usage finance by-kind --company-id <id> [--from <iso8601>] [--to <iso8601>]
vagaris usage finance events --company-id <id> [--from <iso8601>] [--to <iso8601>] [--limit <n>]

Audit trail​

Vagaris is the authority for this trail — every row lives in the immutable, DB-enforced-append-only governed_act_audit table. list/verify return a live hash-chain integrity verdict alongside the rows; verify prints only that verdict and exits non-zero when the chain is tampered.

vagaris audit list --company-id <id> [--limit <n>]
vagaris audit verify --company-id <id>
vagaris audit decisions --company-id <id> [--limit <n>]
vagaris audit explain <act-id> --company-id <id>
vagaris audit explain --company-id <id> --run <run-id>
vagaris audit explain --company-id <id> --issue <issue-id>
vagaris audit explain --company-id <id> --approval <approval-id>
vagaris audit explain --company-id <id> --entity <type>:<id>

audit explain takes exactly one selector — the act id, or one of --run/--issue/--approval/--entity — and composes the full causal trace: world-change (the triggering issue/ingress event) → impact (affected entity, best-effort blast radius) → ownership (the acting seat / resolved DRI) → action (the gate decision, its approval leg, its closure leg) → the raw correlated audit rows.

Evidence​

vagaris audit evidence --company-id <id> [--limit <n>] [--stream <name>]

An index — which evidence stream, which source event, when — across every tenant-scoped append-only plane. Deliberately carries no payload body (secret-shaped values never cross this route); read the owning plane for a row's full content. Answers 501 evidence_fabric_not_applied on a database that predates migrations 0164/0166 — that is a real "not installed yet" state, not a client bug.

Export​

vagaris audit export --company-id <id> [--limit <n>]
vagaris audit evidence-export --company-id <id> [--limit <n>] [--stream <name>]

Both write newline-delimited JSON (one row per line) to stdout. This is a genuine server gap, not a CLI limitation worked around silently: GET /companies/:id/audit has no cursor and clamps to 500 rows; GET /companies/:id/evidence clamps to 200. export/evidence-export request the maximum single page and print a warning to stderr when the page is full, because older rows may exist beyond it. A complete historical export needs a cursor-based GET /companies/:id/audit/export (and the evidence-fabric equivalent) that does not exist yet.

Grounded caveat​

There is no invoicing or rating surface in this deployment — services/billing/billing-policy.ts is a closed taxonomy of billing failure reasons, not a rating engine — so this namespace has no billing command; usage finance * above is the closest real surface, and it is a manual ledger, not a generated invoice.