Command line

atlas-cli is a command-line client for the Atlas API. It is the same API the web app uses, reached with a personal API key instead of a browser session — so anything you can do in the app, subject to your role, you can script.

It is worth reaching for when a browser is the wrong tool:

• piping results into other tools — --json on every read command
• checking something quickly without loading a page
• scripts and scheduled jobs, which need exit codes rather than a session

Install

uv tool install atlas-cli      # from the atlas-cli repository
atlas --version

--help works before anything is configured, so atlas --help and atlas probes list --help are safe first steps.

Configure

You need two things: the API's base URL and a key.

export ATLAS_URL=https://api.atlas.bluesapphiresoftware.net
export ATLAS_API_KEY=atlas_pk_…

Or, to avoid putting a credential in your shell profile, ~/.config/atlas/config.toml:

url     = "https://api.atlas.bluesapphiresoftware.net"
api_key = "atlas_pk_…"

Command-line flags beat environment variables, which beat the file — so one invocation can point at a different instance without changing anything on disk.

TIP

ATLAS_URL is the Atlas API, not RIPE Atlas. Same distinction as the one on the API keys page: your RIPE credential is a separate thing that Atlas uses on the server side. The CLI never talks to RIPE directly.

Create a key at /account/api-keys — issuance needs a staff account. See Authentication for how the key is sent, and API keys for scoping and rotation.

Scopes and roles are separate gates

read is granted to every key; write is opt-in and is required for anything that changes data. On top of that, your account's role still applies — atlas jobs, atlas enrichment and atlas maintenance are admin-only whatever the key's scopes say.

Commands

group	commands
probes	list · count · show
anchors	list · show
countries	list · show
jobs	list · history · show · watch — admin
enrichment	status · targets — admin
maintenance	purge-ignored-history — admin

atlas probes list --country NL
atlas probes count --country NL --status 1
atlas probes show 1001

atlas anchors list --country NL
atlas countries list

atlas jobs history --status failed      # did anything break overnight?
atlas jobs watch                        # follow a running job

Every read command takes --json, so nothing has to parse a table:

atlas probes list --country NL --json | jq '.[].data.id'

Exit codes

code	meaning
0	success, with results
1	a failure — not configured, unreachable, or an API error
2	it worked, and there was nothing to return

2 is deliberately separate from 1 so a script can tell "no results" from "something broke":

if atlas probes list --country XX >/dev/null; then
  echo "found some"
else
  echo "none"
fi

atlas probes count prints a bare number for the same reason:

n=$(atlas probes count --country NL)

Destructive commands

atlas maintenance changes data, so it is a dry run unless you pass --apply. A bare invocation reports what would happen and does nothing:

atlas maintenance purge-ignored-history            # count and sample
atlas maintenance purge-ignored-history --apply    # actually delete

Both the rehearsal and the real run are recorded in the platform's task history, visible under Admin → Task history and via atlas jobs history.