vega-cli

name	vega-cli
description	Query Vega security-scan results and run security scans from the command line. Use when asked to scan code with Vega, check scan progress or cost, or list/inspect security findings for a project, repository, or scan. Provides projects/repos/scans/findings subcommands with agent-friendly text output and raw-JSON mode.

Vega CLI

vega audits code for security vulnerabilities on the Vega backend. Every subcommand is non-interactive and designed for programmatic use:

• stdout carries data only — aligned columns for lists, markdown-style sections for details. Progress, warnings, and errors go to stderr.
• Add the global --json flag to any command to get the raw backend JSON response instead (compact, one object/array per line).
• IDs are self-describing: projects pg_…, repositories proj_…, scans scan_…; public findings use VEGA-HIGH-00001-style display IDs. Finding display IDs are unique only within a repository. Wherever a <project> or <repo> argument is accepted, a unique name works too.
• vega <noun> --help lists each subcommand; singular aliases work (vega scan run = vega scans run).

Install

The vega binary must be on PATH. If command -v vega fails, install the latest release (Linux/macOS, x64/arm64):

curl -fsSL https://raw.githubusercontent.com/NebuSec/vega-skill/main/install.sh | sh

Installs to ~/.local/bin (override with VEGA_INSTALL_DIR; pin a version with VEGA_VERSION=vX.Y.Z). With Node.js available, npm install -g @nebusec/vega works too. Binaries are also downloadable directly from https://github.com/NebuSec/vega-skill/releases.

Setup

Authentication, in precedence order: VEGA_API_KEY env var, else the credential stored by vega auth login (--api-key vega_… for headless, --headless for browser login over SSH). Backend URL: VEGA_API_URL env or --api-url (defaults to production).

Verify before doing anything else:

vega auth status --json
# {"signed_in":true,"source":"stored OAuth token","user_id":"…","email":"…",…}
# exit 3 when not signed in → run `vega auth login` or set VEGA_API_KEY

Reading results (drill-down)

The hierarchy is project → repository → scan → finding.

vega projects list
# PROJECT_ID           NAME         REPOS  OPEN  ACTIVE  LAST_SCAN
# pg_HfPTMSdF1RTuWtk9  vega-collab  1      8     0       2026-06-29T23:36:00…

vega projects get <project>          # detail incl. finding_counts by severity
vega projects repos <project>        # repositories in the project
vega projects scans <project>        # scans across the project

vega repos list [--project <p>] [--git-remote github.com/org/repo]
vega repos get <repo>                # state, snapshot_id, latest_scan_id, …
vega repos scans <repo>

vega scans list [--limit N]          # workspace-wide
vega scans get <scan_id> [--live]    # detail; --live adds live cost/progress
vega scans get <scan_id> -s          # ONE line — cheapest way to poll:
# scan_NtWy… running 49% "Auditing auth module" findings=8 cost=$260.73

Findings

vega findings list --scan <scan_id>            # or --project <p> / --repo <r>
# FINDING_ID     SEV     CONF  STATUS     FILE                TITLE
# VEGA-MEDI-00001 medium  high  candidate  app/…/inline.py     Inline publish does…
# (stderr) total: 8  next_cursor: eyJz…

Filters keep output (and your token use) small — prefer them over fetching everything: --severity critical,high, --status confirmed, --file-prefix src/api/, --cwe CWE-89, -q "sql injection", --limit N. Page with --cursor <next_cursor> (cursor is on stderr in text mode, next_cursor in the JSON body), or pass --all to fetch every page.

Visibility: findings still waiting in the dedup queue are hidden by default (add --include-dedup-pending to see them, e.g. while a scan is running); findings confirmed as duplicates are never listed.

vega findings get --scan <scan_id> <finding_id>      # summary/root cause/evidence/fix
vega findings get --scan <scan_id> <id1> <id2>       # several from one scan;
                                                      # --json emits NDJSON
vega findings get --scan <scan_id> <finding_id> --full  # adds buggy code,
                                                         # attack path and long sections
vega findings export --scan <scan_id> [--finding <id>]   # markdown report

Finding display IDs are repository-local, so get requires the scan that contains them. Fetch get only for findings you will act on; use export for a full human-readable report.

Triage is repository-level and requires an explicit repository scope:

vega findings mark --repo <repo> pending|valid|invalid|fixed <finding...>
vega findings triage --repo <repo> <status> <finding...>  # mark alias
vega findings fix --repo <repo> <finding...>
vega findings invalid --repo <repo> <finding...>
vega findings ack --repo <repo> <finding...>              # valid, still open

fix, invalid, and ack are shortcuts for fixed, invalid, and valid. Multiple IDs run in argument order and are not transactional: on failure, earlier successful changes remain. With --json, multiple results are NDJSON. These commands change server state; confirm the exact repository, finding IDs, and desired status with the user before invoking them.

Running a scan

vega scans run --path . --yes --max-cost 20 --cost-cap 30 --wait

Steps performed: index + zip the directory (respects .vegaignore) → upload as a new repository (--project <p> attaches it; --repo <r> reuses an existing repository instead of uploading) → wait for snapshot → cost estimate → consent gate → create scan.

Cost consent (scans cost real money):

• The estimate always prints first: estimated cost: $1.86 (p10 $0.70 – p90 $4.91), …
• --max-cost <usd>: abort with exit 6 if the estimate exceeds it; otherwise counts as consent. This is the safest flag for agents.
• --yes: unconditional consent. Without either, a non-TTY run exits 6.
• --cost-cap <usd>: independent server-side spend cap (also settable later via vega scans cost-cap <scan_id> <usd>).
• --estimate-only (or vega scans estimate): print the estimate and stop — free, no scan created.

Watching progress:

• default: prints scan created: scan_… and returns immediately; poll with vega scans get <scan_id> -s.
• --wait: poll until done; state changes on stderr, final scan detail on stdout.
• --follow: stream backend events; with --json each event is one NDJSON line on stdout and the final scan detail is the last line.
• vega scans follow <scan_id> attaches to an already-running scan.

Scan control

vega scans pause|resume|cancel|retry <scan_id>    # prints "scan_… <new state>"
vega scans cost-cap <scan_id> <usd>

Exit codes

code	meaning	typical reaction
0	success	—
1	API/transport error (incl. 403 permission/billing denials — message says why)	read stderr
2	usage error / ambiguous name	fix arguments, or use the id
3	not authenticated (HTTP 401 / no credential)	vega auth login or set VEGA_API_KEY
4	not found (bad id or unknown name)	check the id
5	scan ended failed/cancelled under --wait/--follow	inspect failure_reason in the printed detail
6	cost consent refused or --max-cost exceeded	raise --max-cost or pass --yes

Errors print as error[<code>]: <message> (request_id=…) on stderr — include the request_id when reporting backend issues.