docs.cli()

the virgil cli

the cli is a thin shell over the hosted service: it bundles your working directory, submits a scan, streams progress, and prints the ranked triage with exit codes ci can act on. scans run on virgil's servers and bill against your account's credits — every new account starts with 3 free audits.

## install

pipx install virgilhq     # binary on $PATH is `virgil`
virgil login              # device-code flow, one time

the pypi package is virgilhq (the bare name was taken); the command is virgil. pipx keeps the install isolated from your system python — on pep-668 distributions a bare pip install would refuse anyway. virgil login opens a browser approval page and stores a token in ~/.config/virgil/credentials.json.

## scan

virgil scan .                                 # local directory
virgil scan github.com/OWASP/NodeGoat         # remote, bare host
virgil scan OWASP/NodeGoat                    # github shorthand
virgil scan . --show report                   # land on the narrative report
virgil scan . --show ask_virgil               # land in the chat repl
virgil scan . --base-sha abc1234 --head-sha def5678   # pr mode
virgil scan . --no-wait                       # print the audit id, return

local scans zip your working directory (build artifacts, node_modules, and similar noise are skipped) and upload it. pr mode only flags findings on lines changed between the two SHAs — the right shape for review gates.

## drill in

virgil clusters <audit-id>               # every cluster, sorted by severity
virgil clusters <audit-id> --sev high    # filter
virgil cluster  <audit-id> <key>         # one cluster in detail
virgil findings <audit-id>               # raw findings table
virgil chat     <audit-id>               # q&a grounded in this audit
virgil chat     <audit-id> -m "what's the worst finding?"
virgil open     <audit-id>               # jump to the web console
virgil status   <audit-id>

## reports

virgil report <audit-id> --format md
virgil report <audit-id> --format sarif -o findings.sarif
virgil report <audit-id> --format json
virgil report <audit-id> --format pdf

## ci integration + exit codes

virgil scan . --fail-on critical     # exits 1 on any critical
virgil scan . --fail-on high         # exits 1 on critical or high
virgil scan . --fail-on never        # always exits 0

exit codes: 0 — scan finished under the threshold. 1 — findings at or above --fail-on. 2 — the audit itself failed (clone error, scanner crash); failed audits refund their credit. 3 — could not reach the api.

## config + environment

virgil config show
virgil config set default_fail_on=high
virgil config set default_post_scan_view=ask_virgil
virgil config unset default_fail_on

settings resolve env var → config file → default. env vars: VIRGIL_TOKEN (overrides the saved login — use this in ci), VIRGIL_FAIL_ON, VIRGIL_SHOW, VIRGIL_CONFIG_DIR.

wondering what happens to the code you upload? read the security model.