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.
--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).

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 (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

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.