CLI reference¶

vsutra is a command-line client for the VirtualSutra REST API. Everything the console does over HTTP is reachable from it, which makes it the practical tool for CI pipelines, scripted triage and bulk export.

The client is generated from the API's own OpenAPI schema, so a command and the route it calls come from one source: CI regenerates the client from the committed schema and fails the build on any difference.

Installing¶

The CLI is not published to a package index. It is provided by VirtualSutra on request - contact support@virtualsutra.com. You receive a Python wheel; install it into a virtual environment:

pip install ./vsutra_cli-<version>-py3-none-any.whl
vsutra --help

Authenticating¶

vsutra login          # GitHub device flow (default); needs VSUTRA_GITHUB_CLIENT_ID set
vsutra login --key    # prompt for an API key instead

Either way the result is written to ~/.vsutra/config.toml, holding api_url and token.

For CI, set the environment instead - it takes precedence over the config file, so nothing needs to be written to disk:

Variable	Meaning
`VSUTRA_API_URL`	API base URL. Falls back to `api_url` in the config file.
`VSUTRA_API_KEY`	The API key to present. Falls back to `token` in the config file.

Which key to use in CI

Use an API key minted for the purpose - Settings > Admin > API Keys, or your own under Settings, scoped to what the pipeline actually needs. Do not reuse the console's own credential: on a deployment that names it in CONSOLE_API_KEYS, an unattended caller presenting it gets 401 "Actor assertion required", because that key is reserved for requests carrying a signed actor assertion. A Kubernetes install that generates its own keys provides a separate machine key for exactly this.

Without either source, commands exit with Not authenticated. Run 'vsutra login' or set VSUTRA_API_KEY.

Output format¶

Every listing and detail command takes --output / -o:

Value	Use for
`table` (default)	reading on a terminal
`json`	one indented JSON document - `jq`, a file, a step output
`ndjson`	one compact JSON object per line - streaming into a pipeline, `jq -c`, a log shipper

vsutra findings list --run-id <run-id> --output ndjson | jq -c 'select(.severity=="critical")'

Command groups¶

vsutra --help lists the groups; vsutra <group> --help and vsutra <group> <verb> --help are the authoritative argument lists, generated from the same schema as the client itself. This page deliberately does not restate them: a hand-written copy drifts, and several of these commands take required options that are easy to get wrong from prose.

Group	For
`scan`	Submit an inspection from a config file
`run`	Trigger, list, inspect, tail and diff runs
`findings`	List, inspect, bulk-export and mute findings
`issues`	Finding patterns tracked across runs: triage, assign, resolve, reopen
`schedule`	Recurring inspections
`report`	Download generated reports and SBOM artifacts
`remediation`	List remediations and stage proposals for approval
`connections`	Cloud accounts, repositories, registries, clusters, web apps, pentest targets
`pentest`	Ingest an external pentest report, or dispatch a pentest
`compliance`	Per-run framework scores and detail

Three things worth knowing before you reach for --help:

Findings are addressed per run. findings list and findings get take --run-id; there is no cross-run findings list, because the API does not expose one. findings export takes the run id as a positional argument instead.
run diff needs an explicit --baseline. There is no "previous run" default. It prints summary counts; --findings switches to the finding-level rows, whose statuses are new, resolved, persisted, escalated and deescalated.
pentest dispatch will not run without an attestation. --url, --typed-hostname and --standing-authorization-note are all required, --typed-hostname is never derived from --url for you, and without --confirm-authorized no HTTP request is issued at all.

Operators: internal-docs' CLI Reference lists every verb alongside the route it calls.

Scopes¶

The CLI can only do what the credential you gave it is allowed to do - it holds no privileges of its own. A 403 means the key's scopes are too narrow, not that the command is wrong.

Area	Scope needed
Most reads	`read`
`schedule list`	`schedule:read`
`scan submit`, `run trigger`, `connections` writes, `remediation propose`	`write`
`schedule create` / `update` / `delete`	`schedule:write`
`findings mute`, issue writes	`findings:write`
`report download` / `report sbom`	`reports:read`

remediation:approve gates approving a remediation, which the CLI does not do - approve from the console. A key holding read alone cannot list schedules or download reports; those are separate scopes on purpose.

See the Tier & Scope Matrix for the full breakdown, and Actor assertions for why a direct API key is judged differently from the same person working in the console.