Browse documentation

`esos` command line.

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

Install from the console (signed in)Config ~/.esos/config.yamlExit codes 0 · 1 · 2Updated October 2026

Install

The CLI is distributed only to authenticated users; there is no public package index or anonymous download. It needs Python 3.11 or later.

From the console — open Developer → Quickstart, choose Download esos-cli, then install the wheel.
With an API key — download the installer from the authenticated release channel. It checks the wheel's SHA-256 against the published checksums before installing and stops on any mismatch.

# from a downloaded wheel
python -m pip install --upgrade ./esos_cli-0.1.1-py3-none-any.whl

# with an API key (Linux and macOS)
curl -fsSL -H "Authorization: Bearer $ESOS_API_KEY" -H "X-Organization-ID: $ESOS_ORG_ID" \
  https://app.securityvault.io/api/v2/developer/cli/install.sh -o install.sh
ESOS_API_KEY="$ESOS_API_KEY" ESOS_ORG_ID="$ESOS_ORG_ID" bash install.sh

# shell completion and updates
esos completion bash > ~/.esos-completion.bash
esos update                     # checks for a newer release and verifies its SHA-256

A PowerShell installer, install.ps1, is published on the same channel for Windows.

Authentication

esos auth login                         # OAuth 2.0 device flow
esos auth login --api-key "$ESOS_API_KEY"   # store a bearer token non-interactively, for CI
esos config set org_id <your-organisation-id>
esos auth status
esos auth logout

Settings — api_url, org_id, default_severity and fail_on — live in ~/.esos/config.yaml with owner-only permissions; change them with esos config set. The token is kept in the operating system's keychain (macOS Keychain, Windows Credential Manager, or Secret Service on Linux), never in the file. On a CI runner without a keychain, set ESOS_CLI_ALLOW_PLAINTEXT_TOKEN=1 to allow the token to be stored in the config file instead; without it the CLI refuses to store the token.

Commands

Command	What it does
`esos scan repo <git-url>`	Scan a Git repository. The tool plan is derived from the repository.
`esos scan run --target <git-url> --type <type>`	Queue a scan of one type (`sast`, `sca`, `iac` or `secrets`) and print the scan id.
`esos scan image <ref> [--tools a,b]`	Scan a container image.
`esos scan api <openapi.yaml>`	Scan an OpenAPI specification.
`esos ci scan`	Queue a scan of the target, then write the organisation's findings as SARIF, JUnit, JSON or a table; exits `1` if any is at or above `--fail-on` (default `high`).
`esos findings list [--severity] [--limit] [--output table\|json\|sarif\|junit]`	List findings for the organisation (up to 200 per call).
`esos findings show <id>`	Show one finding as JSON.
`esos sbom generate --target <target> [--format cyclonedx\|spdx]`	Generate an SBOM (CycloneDX by default).
`esos dashboard`	Open the console in your browser.
`esos config set\|get\|list`	Manage CLI settings.
`esos completion bash\|zsh\|fish\|powershell`	Print a shell completion script.
`esos update [--public-key key.pem]`	Download a newer release, verify its SHA-256 (and signature, when a key is given) and print the upgrade command.

In development: SBOM upload and diff, policy evaluation from the CLI, CLI triage and an organisation posture summary.

Gates and exit codes

esos ci scan --target https://github.com/your-org/app --format sarif --output results.sarif --fail-on high
esos --fail-on critical findings list --severity critical --output json

esos ci scan takes its own --fail-on. For other commands, put --fail-on before the subcommand, or set fail_on with esos config set.

Code	Meaning
`0`	Success
`1`	Policy failure — a finding at or above the `--fail-on` threshold
`2`	API, network or authentication error

Output formats

table for people, json for scripts, sarif (2.1.0) for GitHub code scanning and other SARIF consumers, and junit for Jenkins and GitLab test reports. esos findings list takes --output; esos ci scan takes --format and writes to the file named by --output.

Environment variables

Variable	Purpose
`ESOS_CLI_ALLOW_PLAINTEXT_TOKEN`	Set to `1` to allow storing the token in `~/.esos/config.yaml` where no OS keychain is available.
`ESOS_API_KEY`, `ESOS_ORG_ID`	Read by the installer script only. Pass the key to the CLI with `esos auth login --api-key` and the organisation with `esos config set org_id`.

Next steps

API reference — call the same endpoints the CLI uses.
Policy authoring — write the policy your pipeline gate enforces.
Deployment gates — how gates fit into CI/CD.

esos command line.