Docs/Build/CLI reference

`esos` command line.

One binary for developers and pipelines. Device-flow login for humans, API keys for CI, structured output for everything else.

Install pip install esos-cliConfig ~/.esos/config.yamlExit codes 0 · 1 · 2Updated September 2026

Install

pip install esos-cli            # Python 3.11+
pipx install esos-cli           # isolated
esos completion bash > /etc/bash_completion.d/esos
esos update                     # checks for a newer release and verifies its signature

A statically built Go edition ships for minimal CI images with the same command surface.

Authentication

esos auth login                 # OAuth 2.0 device flow against /api/v2/auth/device
esos auth login --api-key $ESOS_API_KEY
esos auth status
esos auth logout

Credentials persist in ~/.esos/config.yaml with owner-only permissions. Set api_url, org_id and default_severity there or with esos config set.

Commands

Command	What it does
`esos scan run --target <path\|url> --type <sast\|…>`	Queue a scan for a repository path or URL; prints the job id.
`esos scan repo [PATH] [--tools a,b]`	Scan a git repository (default: current directory). Tools default to the auto plan.
`esos scan image <ref>`	Scan a container image (trivy, grype, syft).
`esos scan url <url> --profile passive\|active`	DAST scan. Destructive mode is refused without attestation.
`esos scan api <openapi.yaml>`	Scan an OpenAPI specification.
`esos ci scan`	CI scan with policy enforcement and structured output; honours `--fail-on`.
`esos findings list [--severity] [--limit] [--output table\|json\|sarif\|junit]`	List findings for the organisation.
`esos findings show <id>`	Show one finding with evidence.
`esos findings triage <id> --status … --reason …`	Record a triage verdict (human principal, reason required).
`esos sbom generate --target … --format cyclonedx`	Generate an SBOM.
`esos sbom upload <file> --project … --version …`	Upload an SBOM to `/api/v2/sca/sboms/upload`.
`esos sbom diff <old> <new>`	Added and removed packages between two SBOMs.
`esos policy evaluate --finding-id <id>`	Evaluate the policy decision for a finding.
`esos policy check`	Run policy check against the current project.
`esos policy list`	List active policies.
`esos status`	Overall organisation posture.
`esos dashboard`	Open the console in the browser.
`esos config set\|get\|list`	Manage CLI configuration.

Gates and exit codes

esos --fail-on critical findings list --output sarif > results.sarif
esos --fail-on high ci scan

Code	Meaning
`0`	Success
`1`	Policy failure — threshold breached or policy deny
`2`	API, network or authentication error

Output formats

--output table for humans, json for scripts, sarif (2.1.0) for GitHub code scanning and other SARIF consumers, junit for Jenkins and GitLab test reports.

Environment variables

Variable	Purpose
`ESOS_API_URL`	Override `api_url` (self-hosted installs).
`ESOS_API_KEY`	Bearer token for non-interactive use.
`ESOS_ORG_ID`	Organisation id sent as `X-Organization-ID`.

esos command line.