CLI reference
Sverka's CLI has 19 commands. Source of truth: `packages/cli/src/main.ts`.
Sverka's CLI has 19 commands. Source of truth: packages/cli/src/main.ts.
Commands
sverka init
Create a sverka.config.ts file with a default Construct-based workflow.
| Flag | Type | Default | Choices | Description |
|---|---|---|---|---|
--template | string | minimal | minimal, full | Config template to use |
--force | boolean | false | Overwrite existing config | |
--detect | boolean | false | Generate config from detected project checks (overrides --template) |
sverka validate
Synthesize the Definition Graph and run validators. Reports graph errors and validation diagnostics.
sverka plan
Synthesize the Definition Graph, bind a Run Plan for an entry, and print it without executing.
| Flag | Type | Default | Description |
|---|---|---|---|
--entry | string | — | Entry ID to plan for |
sverka graph
Print the synthesized Definition Graph showing pipelines, steps, entries, and dependencies.
sverka run
Execute a Run Plan through the native engine with the host runtime driver.
Emits step events: pending, started, succeeded/failed, run completion.
After each finished step, prints the tail of its captured stdout/stderr
(last 20 lines, --step-output-lines tunes or disables); on a TTY the
status lines are ANSI-colored (NO_COLOR or TERM=dumb opt out).
With no sverka.config.* on disk, sverka run still works: the same
detection sverka check uses becomes an implicit default pipeline —
one host step per detected check — and the run proceeds as usual. When
nothing is detectable the command exits 2 and points at sverka init.
Each run also writes .sverka/runs/<runId>/report.json (schema
sverka.run/v1, append-only) and report.html; human output ends with
a findings: count and the report path.
| Flag | Type | Default | Description |
|---|---|---|---|
--entry | string | — | Entry ID to run |
--executor | string | host | Runtime executor to use (host or docker) |
--evaluate | boolean | false | Collect SARIF findings and evaluate policy after the run |
--output | string | — | Output file path for HTML report (implies --format html) |
--report | string | — | Relocate the per-run HTML report (report.json stays put) |
--tui | boolean | false | Interactive terminal UI (opt-in; default output is plain text) |
--jobs, -j | number | 4 | Max steps running concurrently |
--step-output-lines | number | 20 | Captured stdout/stderr tail lines per step (0 disables) |
--watch, -w | boolean | false | Re-run on file changes (debounced; keeps watching after failures) |
--remote | boolean | false | Remote hub run: remote cache + snapshot store + report upload |
sverka discover
Discover and display project context (package manager, languages, checks).
| Flag | Type | Default | Description |
|---|---|---|---|
| (none) | — | — | Uses global flags only |
sverka check
Detect the project's checks (planner discovery + package.json scripts,
scoped to --root) and resolve them to step definitions — the same set
init --detect would generate.
| Flag | Type | Default | Description |
|---|---|---|---|
| (none) | — | — | Uses global flags only |
sverka policy
Evaluate policy against findings and baseline.
| Flag | Type | Default | Description |
|---|---|---|---|
--findings | string | — | Path to findings JSON file (required) |
--baseline | string | — | Path to baseline findings JSON file |
sverka compile --target github|gitlab
Compile the workflow to a CI target and print the YAML (or write it with
--output). With more than one pipeline, use --output-dir to write each
artifact to its own file under the given directory (mirrors the repo-relative
paths, e.g. <dir>/.github/workflows/<pipeline>.yml). --output and
--output-dir are mutually exclusive.
| Flag | Type | Default | Description |
|---|---|---|---|
--target | string | — | Target: github or gitlab (required) |
--output, -o | string | — | Write YAML to a file instead of stdout |
--output-dir | string | — | Write each artifact to <dir>/<artifact path> |
--pin | boolean | false | Pin GitHub action refs to commit SHAs (github target) |
sverka synth --target github|gitlab
Alias for compile — registers the same flags (--target, --output,
--output-dir, --pin).
sverka mcp-server
Expose Sverka operations (validate, plan, graph, run, synth) as
MCP tools over stdio. Runs until stdin closes or SIGTERM.
sverka view [file]
View SARIF findings in the terminal TUI or generate a standalone HTML
report. Reads from stdin when file is omitted; falls back to plain text
when no interactive terminal is available.
| Flag | Type | Default | Description |
|---|---|---|---|
--format, -f | string | tui | tui, web, or html (HTML report) |
--output, -o | string | sarif-report.html | Output path for --format web/html |
sverka ui
Start the local web dashboard server for SARIF findings.
| Flag | Type | Default | Description |
|---|---|---|---|
--port | number | 3000 | Port to listen on |
--host | string | localhost | Host to bind |
sverka doctor
Check installation health, dependencies, and configuration.
| Flag | Type | Default | Description |
|---|---|---|---|
| (none) | — | — | Uses global flags only |
sverka hub serve
Run a self-hosted remote run hub (shared cache + run history + dashboard).
The serve action is required — sverka hub alone is a usage error.
Options: --port (default 7357), --host, --data (default
.sverka-hub under --root). See Remote run hub.
sverka login
Store hub credentials in ~/.config/sverka/credentials. See
Remote run hub.
| Flag | Type | Default | Description |
|---|---|---|---|
--hub | string | — | Hub base URL (or SVERKA_HUB_URL) |
--token | string | — | Hub bearer token (or SVERKA_HUB_TOKEN) |
sverka runs
List run reports — local .sverka/runs/ by default, --remote for runs
stored on the hub. See Remote run hub.
| Flag | Type | Default | Description |
|---|---|---|---|
--remote | boolean | false | List runs stored on the configured hub |
--limit | number | — | Max runs to list |
sverka agent
Execute an agent job inside generated CI (Spec 54) — resolves the driver
from SVERKA_AGENT_* env vars and writes agent-result.json +
sverka-writes.json. See Agentic workflows.
| Flag | Type | Default | Description |
|---|---|---|---|
--output-dir | string | <root> | Directory for agent-result.json + sverka-writes.json |
sverka apply
Apply an agent job's declared writes (Spec 54 safe-outputs stage) —
sverka apply --provider <gitlab|github> inside the generated __apply
job. See Agentic workflows.
| Flag | Type | Default | Description |
|---|---|---|---|
--provider | string | auto-detected | CI provider: gitlab or github |
--file | string | <root>/sverka-writes.json | Path to sverka-writes.json |
Global flags
| Flag | Type | Default | Choices | Description |
|---|---|---|---|---|
--config | string | — | Path to config file (default: sverka.config.ts) | |
--root | string | process.cwd() | Project root directory | |
--format | string | text | text, json, html, sarif, web | Output format |
--verbose | boolean | false | Verbose output | |
--quiet | boolean | false | Suppress non-essential output |
Exit codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Policy failure |
| 2 | Usage error |
| 3 | Runtime error |