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

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.
--no-cache		flag	false	Re-analyse every file instead of reusing SAST results for files unchanged since the last run. Also scan.cache: false or VYGL_NO_CACHE=1. See Large repositories.
--allow-incomplete		flag	false	Pass the scan even when an engine ran out of time (exit 0 with a warning instead of exit 2). Also scan.allow_incomplete: true.
--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

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

Command	Description
vygl project list	List all projects in your organization.

vygl results

Command	Description
vygl results <SCAN_ID>	Print findings from a previous scan.

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).
VYGL_ENGINE_TIMEOUT_S	Per-engine time budget in seconds, same as scan.engine_timeout_seconds. Defaults: 2700 for SAST, 3600 for cloud, 900 for the rest.
VYGL_CACHE_DIR	Where SAST keeps per-file results between runs (default ~/.cache/vygl). In CI, point it at a directory your pipeline caches.
VYGL_NO_CACHE	1 turns the SAST result cache off, like --no-cache.

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

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 (network error, invalid auth, malformed config).
2	INCOMPLETE — an engine ran out of time, so the results are missing everything it would have found. Not a pass: raise the budget, exclude generated or vendored code, or pass --allow-incomplete to accept it. A severity breach (1) takes precedence.

An engine that fails outright (binary missing, a crash) is reported in the output and the --json document but does not change the exit code.

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

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.