Skip to content
docs

CLI Reference

The Vygl CLI is distributed as a Docker image (vygl/vygl-cli:latest). For walkthroughs and patterns, see Running Scans (CLI); this page is the terse reference.

vygl scan

Section titled “vygl scan”
vygl scan [OPTIONS] [PATH]

Scan a directory or, with --image, a container image.

Flag Short Type Default Description
--scan-types -t comma list sast,sca,secrets,iac,malware Engines to run. Valid: sast, sca, secrets, iac, malware, container. malware and container may be turned off by org/project settings — the CLI fetches the policy on each run and skips disabled engines automatically.
--image string — Scan a container image; forces --scan-types container.
--fail-on severity unset Severity that exits non-zero. One of critical, high, medium, low.
--no-upload flag false Skip pushing findings to the cloud.
--rules path — Directory or file of SAST rules to scan with. For self-hosted and air-gapped installs; the org policy still takes precedence when signed in. Also settable as scan.sast.rules_path in .vygl.yml. Without any rule source, SAST reports no_rules_configured rather than zero findings.
--json path — Write the full scan result to this path as a JSON document — every finding (the console truncates at 15), per-engine status, and the dependency inventory. Written for every outcome, including a --fail-on breach; a write failure warns on stderr and never changes the exit code. See Running Scans → JSON output.
--name -n string (auto) Project name (used when no git remote).
--project-id -p UUID (auto) Bind to a specific project. Overrides VYGL_PROJECT_ID and the YAML project_id.
--branch -b string (auto) Override branch detection.
--commit sha (auto) Override commit detection.
--repo-url URL (auto) Override git-remote detection.
--git-provider string (auto) Force SCM type (github, gitlab, bitbucket, gitea); also VYGL_GIT_PROVIDER.
--pr int (auto) PR/MR number — enables comment posting. Auto-detected on GitHub Actions, GitLab CI, Bitbucket Pipelines.
--config -c path (auto) Path to a .vygl.yml; overrides auto-discovery.
--show-all flag false Print every finding to stdout, not just gate-triggering ones.
--trigger string ci Mark the trigger source on the dashboard (e.g. manual, scheduled).
--api-url URL from env Override API base URL. Effective default: VYGL_API_URL, falling back to https://api.vygl.io.

vygl auth

Section titled “vygl auth”
Command Description
vygl auth set-key <KEY> Store API key in ~/.vygl/credentials (chmod 600).
vygl auth test Verify the stored key and print the org it belongs to.

vygl project

Section titled “vygl project”
Command Description
vygl project list List all projects in your organization.

vygl results

Section titled “vygl results”
Command Description
vygl results <SCAN_ID> Print findings from a previous scan.

Environment variables

Section titled “Environment variables”
Variable Purpose
VYGL_API_KEY API key (required for cloud upload).
VYGL_API_URL API base URL (default https://api.vygl.io).
VYGL_PROJECT_ID Override auto-detected project ID.
VYGL_GIT_PROVIDER Force SCM type (github, gitlab, bitbucket, gitea).

CI-native vars (GITHUB_*, CI_*, BITBUCKET_*, GITEA_*) are read for branch / commit / repo / PR / committer auto-detection.

Exit codes

Section titled “Exit codes”
Code Meaning
0 Scan completed; no findings ≥ --fail-on threshold and no Block-mode rule fired.
1 Scan completed; either findings at/above --fail-on are present, OR a cloud-policy rule in Block mode produced a finding (independent of --fail-on), OR the run errored (engine failure, network error, invalid auth, malformed config).

The CLI today returns 0 or 1 — there’s no separate “run errored” exit code.

CI auto-detection

Section titled “CI auto-detection”

The CLI reads CI-native environment variables to fill scan metadata automatically. Supported providers:

  • GitHub Actions (GITHUB_*).
  • GitLab CI (CI_*).
  • Bitbucket Pipelines (BITBUCKET_*).
  • Gitea Actions.
  • Generic git fallback (uses git rev-parse and git remote get-url origin).

Override any auto-detected value with the corresponding flag, or with VYGL_GIT_PROVIDER to force the SCM family.

Config file

Section titled “Config file”

The loader accepts any of .vygl.yml, .vygl.yaml, vygl.yml, .vigil.yml, .vigil.yaml, vigil.yml at the repo root. See Configuration for the schema.

fail_on precedence (highest to lowest): --fail-on flag → scan.fail_on in the YAML → project setting in the dashboard.