Reference

CLI reference

Every atmos subcommand and flag. PATH is a file or a directory, and the files a scan picks up are listed in language support.

Commands#

Command	What it does
atmos scan <PATH>	Code and dependencies in one run, closing with one summary. The default.
atmos sast <PATH>	Code analysis only.
atmos sca <PATH>	Dependency analysis only.
atmos agent setup [<PATH>]	Set up a repository so Atmos checks the files an agent edits at the end of each turn and sends the findings in them back to the agent. Only you get the hook. See coding agents.
atmos agent hook	What your agent runs after each file edit and at the end of each turn. Setup configures it for you.
atmos login	Sign this machine in: a link opens in your browser, you approve, and the sign-in is stored for every later command. Once per machine. `--no-browser` only prints the link.
atmos logout	Revoke this machine's sign-in and forget it.
atmos whoami	Show who is signed in, to which workspace, and where the sign-in comes from. See atmos whoami.
atmos db update	Download or refresh the local advisory database. Runs without any credential.
atmos self-update	Update the binary in place.
atmos licenses	Print the license you run Atmos under. `--third-party` prints the third-party notices instead.

atmos whoami#

Before a scan in a new terminal or CI job, atmos whoami asks Atmos who the sign-in belongs to and prints the account, the workspace and the source of the sign-in: atmos login, ATMOS_TOKEN or --token, in the order a scan uses them. Pass --token <TOKEN> to check that Workspace Token instead.

Situation	What it prints	Exit code
Signed in	The account, the workspace and the source of the sign-in.	0
Not signed in	An error that says how to sign in.	3
Sign-in rejected	An error that says to run `atmos login` again or to check the token. A revoked or expired sign-in gets this.	3
Cannot scan	The account and the workspace, then why Atmos refuses scans with this sign-in: you are a viewer in the workspace, or its workspace was deleted or you are not a member of it. Run `atmos login` to choose a workspace.	3
Atmos unreachable	What `atmos login` recorded on this machine, with a note that the sign-in was not checked.	0

With --format json, atmos whoami prints one object:

signed_in, and source: login, ATMOS_TOKEN or --token.
email (null for a Workspace Token) and workspace.
verified, false when Atmos could not be reached, and can_scan, null when not verified.
reason, viewer or no_active_workspace when Atmos refuses scans, with an error object whose code is scan_refused.

Without a sign-in, or with a rejected one, the output is the error object a scan prints.

Platform flags#

Shared by every scan subcommand.

Flag	What it does
--token <TOKEN>	Workspace Token (`atmos_ws_...`) for CI and other headless environments. Falls back to `ATMOS_TOKEN`, then to the sign-in stored by `atmos login`. A scan with none of the three does not run.
--repo <ID>	Name the repository (`host/owner/name`) when it has no git `origin` remote. Every scan needs the name, and a scan adds the repository to your workspace.
--no-upload	Keep the findings on this machine and upload nothing. The scan still needs network access and still adds the repository to your workspace. Only `.atmos-ignore.yaml` then decides which findings fail the build. See triage on the platform.
--snippets	Include the matched source line in the upload and in SARIF output. Off by default. See what leaves your machine.

Shared flags#

Also on scan, sast and sca.

Flag	What it does
--baseline-commit <REF>	Report and fail only on the findings the baseline commit does not have: the commit where your branch left `<REF>`. A GitHub Actions pull request and a GitLab merge request pipeline use their target branch without the flag. A `<REF>` the checkout does not have stops the scan with exit code 2. See fail only on new findings.
--fail-on <SEVERITY>	The lowest severity that fails the build, from `critical` down to `info`. Findings below it stay in the report. Without the flag, every finding fails the build. See choose what fails the build.
--format	`human` (default report), `json`, or `sarif` (SARIF v2.1.0). See output.
-o, --output <FILE>	Write the report to a file instead of stdout.
--color	`auto`, `always`, or `never`.
--progress / --no-progress	`--progress` shows the progress lines even when stderr is not a terminal, and `--no-progress` turns them off except the results link. Progress goes to stderr, reports to stdout.
--incremental	Warm scans. An unchanged tree replays the prior result and after an edit only what changed is rechecked, with the same result as a cold scan. For `scan` and `sast` the flag turns on by itself once this repository has a cache, and `--no-incremental` forces a cold scan. `sca` takes the flag explicitly each run.
--cache-dir <DIR>	Keep the warm scan cache in `<DIR>`, a folder outside the repository (default `repos/` in your user cache folder). For `scan` and `sast`, passing it also turns warm scans on.

SAST flags#

On scan and sast.

Flag	What it does
--rules <RULES>	A YAML rule file, or a directory of them. Optional: rules also load from `.atmos/rules/` (suppress with `--no-local-rules`).
--no-managed-rules	Scan with your own rules only, from `--rules` and `.atmos/rules/`. `atmos sca` does not take this flag and stops with exit code 2, JSON error code `usage`. See keep the Findings page complete.
-j N	Cap scan parallelism. 0 uses the default.
--max-file-mib <MIB>	Size budget for each file, 4 MiB by default. A file over a budget is skipped with a visible reason, so anything it contains goes unreported. Raise it to scan generated or bundled files, and 0 turns the budget off.
--max-file-lines <LINES>	Line budget for each file, 50,000 lines by default. Works like the size budget.

SCA flags#

On scan and sca.

Flag	What it does
--osv-db-dir <DIR>	Keep the local advisory database in `<DIR>`, a folder outside the repository (default `osv-db/` in your user cache folder, downloaded on first use).
--online / --offline	Query the live OSV API instead of the local database, or keep advisory resolution on the local database. Mutually exclusive. `--offline` governs advisory lookups only, and every scan still connects to the platform.
--skip-db-update	Keep a cached database even if the freshness check says it is stale.
--sca-rules <PATH>	Your own SCA YAML rules, loaded alongside the advisory database.
--reachable-only	Drop findings whose package your code never reaches. See keep the Findings page complete.
--no-reachability	Skip the reachability analysis entirely (faster).
--min-severity / --min-confidence	Filter the report by severity or reachability confidence. See keep the Findings page complete.
--no-ignore	Also scan lockfiles that .gitignore would exclude.
--error-on-no-lockfiles	(`scan` only) Exit with code 2 when no lockfile is found. Off by default.

Keep the Findings page complete#

Atmos marks a finding Fixed when an uploaded scan that could have seen the finding no longer reports it, as when findings close describes. A scan you narrow reports less, even when the code has not changed:

A dependency scan with --min-severity, --reachable-only or --min-confidence drops the findings the option excludes, and Atmos marks them Fixed.
A scan with --no-managed-rules, --no-local-rules or fewer rules in --rules than the last scan runs fewer rules, and Atmos marks Fixed the findings of the rules that did not run.
A path newly listed in .atmosignore or .gitignore is no longer scanned, and Atmos marks its findings Fixed.

To keep the Findings page complete, upload scans that run your full rule set without these options, and pass --no-upload to a narrowed scan. To keep a finding from failing the build while the Findings page still lists it, add it to .atmos-ignore.yaml instead of ignoring its path.

db update and self-update#

atmos db update#

Flag	What it does
--ecosystem <NAME>	Restrict to one ecosystem, repeatable. Defaults to npm, Maven and NuGet.
--osv-db-dir <DIR>	Database location (default `osv-db/` in your user cache folder).

atmos self-update#

Flag	What it does
--check	Report whether an update exists without installing it.
--version <X.Y.Z>	Install this version instead of the latest, when it is the installed version or a newer one. To go back to an older release, run the install script with that version, as the quickstart shows.
--token	Same as the platform flag. Downloads are authenticated with your sign-in, or with a Workspace Token in CI.

Output#

The report goes to stdout, or to the file -o names. Progress, warnings and errors go to stderr, each line starting with atmos:.

The human report prints once the upload is done. Each finding opens with its severity in the words the platform uses, from critical down to info. A secret in a flagged line is masked. A finding someone marked False positive, Accepted or Ignored on the Findings page carries the note triaged on the Findings page. After the summary, the report closes with one note for each kind of finding that does not fail the build:

Findings .atmos-ignore.yaml covers.
Findings already in the baseline commit.
Findings triaged on the platform.
Findings below --fail-on.

--format json is the native report, and --format sarif is SARIF v2.1.0 with each data flow trace as codeFlows. Both keep every finding and mark the ones that do not fail the build:

A finding .atmos-ignore.yaml covers carries suppressed in JSON and a suppressions entry in SARIF. See what an ignored finding looks like.
With a baseline commit, every finding carries baseline_state in JSON and baselineState in SARIF, new or unchanged.
How many findings triage and the baseline commit left out goes to stderr.

Lines and columns in JSON and SARIF start at 1, and columns count characters (Unicode code points), as in the human report.

Exit codes#

Code	Meaning
0	No finding fails the build, or the folder has nothing to scan.
1	Findings fail the build: open findings at or above `--fail-on` that `.atmos-ignore.yaml`, triage on the platform and the baseline commit do not cover. See what fails the build.
2	A scan error, a mistyped command, or `--error-on-no-lockfiles` without a lockfile. A path, an `--output` folder or a `--baseline-commit` that does not exist, and an `.atmos-ignore.yaml` that is not valid, stop the scan before anything runs or is sent.
3	Atmos could not start the scan, and nothing was scanned. The error says why and what to do.
4	Upload failure. The report still prints or is written to the `--output` file, and the code wins over 1 so CI notices the platform did not receive the report.

A file that fails to parse becomes an atmos: skip line on stderr, and so does a text file a regex rule cannot read because it is not UTF-8 or is larger than 1 MiB. A rule that fails to load becomes an atmos: warning: line. The scan continues with the rest.

JSON error codes#

When a scan cannot run or start, --format json prints one error object on stdout, also when -o names a file:

json

{"error": {"code": "path_not_found", "message": "src/api does not exist. Nothing was scanned."}}

These codes come with exit code 3, and nothing was scanned:

Code	When
not_signed_in	No sign-in. Run `atmos login`, or set `ATMOS_TOKEN` or pass `--token`.
sign_in_rejected	Atmos rejected the sign-in, for example a revoked or expired one.
network	Atmos could not be reached.

These codes come with exit code 2, before anything runs or is sent:

Code	When
path_not_found	The scan path does not exist.
output_dir_not_found	The folder `--output` names does not exist.
baseline_not_found	The checkout does not have the `--baseline-commit`.
invalid_ignore_file	`.atmos-ignore.yaml` is not valid, is a symbolic link or is larger than 1 MiB.
usage	A mistyped command line, such as a flag the subcommand does not take.

other covers any other failure, with exit code 2 or 3, such as a scan of a repository without a name (no origin remote and no --repo). A scan refused because of the workspace's plan also exits 3, with its own code and a message that says what to do. Treat a code you do not know as other.