Skip to content

Commands ​

Every command takes --json, and -p, --project <name> where a project applies. Run atlas <command> --help for the full list of options. A failure under --json prints the error as JSON on standard error.

Overview ​

CommandWhat it does
atlas loginsign in with a password or an API token
atlas logoutforget the stored credential
atlas whoamishow who you're signed in as
atlas projectslist the projects you can access
atlas projects create <name>create a project (account admins)
atlas files listlist a project's files
atlas files upload <files...>upload test plans and data files
atlas files download <filename>download one file
atlas files rm <filename>delete a file
atlas runstart a test
atlas status <testId>check whether a test is still running
atlas results <testId>show the aggregation report
atlas summary <testId>show the run's AI Summary
atlas outcome <testId> [value]show or set the run's outcome
atlas stop <testId>stop a running test
atlas testslist a project's recent runs
atlas timeseries <testId>active users, response time and error rate over time
atlas errors <testId>the distinct errors a test produced
atlas capacitywhat you can run on: machines, clusters and usage limits
atlas plan check [file]check a test plan will run and report before you use it
atlas record [url]record a browser session
atlas schemadescribe every command and option (for scripts and AI agents)
atlas skills list / installinstall the AI-assistant guidance into your project
atlas docs [topic]read the documentation without leaving the terminal
atlas config get / setdefault instance URL and project

Files ​

sh
atlas files upload -p SHOP ./checkout.jmx ./data/users.csv
atlas files list -p SHOP
atlas files download -p SHOP checkout.jmx
atlas files rm -p SHOP old-data.csv --yes

A project that doesn't exist yet can be created on the way: add --create (or create it first with atlas projects create SHOP). Creating a project needs an account admin and CLI 0.8.0 or later.

Uploading a file whose name already exists replaces it. rm asks for confirmation, and refuses without --yes when there is no terminal — so a pipeline can't delete a file by accident.

See Test Files for how files are laid out and divided between machines.

Running ​

sh
atlas run -p SHOP --jmx checkout.jmx --servers 5 --wait
OptionMeaning
--servers <n>use any n available load generators
--server <name>pick one by name; repeat for several
--cluster <name> --units <n>run on n units in a cluster
--jmx <filename>which plan to run (needed only if the project holds more than one)
--args "<jmeter args>"extra JMeter arguments
--no-splitsend whole data files to every machine
--waitfollow the run and print the report at the end
--timeout <duration>how long --wait waits, e.g. 30m (default 2h)
--gate <thresholds>fail on a threshold breach — see Running in CI
--junit <file>write a JUnit report
--ai-summaryhave an AI Summary written when the run ends; with --wait, print it
--no-set-outcomewith --gate, don't record the gates' verdict as the run's outcome
--origin <ci|cli>say whether this runs in a CI pipeline or your terminal; without it, the CI variable decides

Without --wait the command returns as soon as the test is submitted and prints the test ID.

Checking on a run ​

sh
atlas status SHOP-20260818-K3F9
atlas results SHOP-20260818-K3F9
atlas results SHOP-20260818-K3F9 --json
atlas stop SHOP-20260818-K3F9

results prints the aggregation report — one row per request, plus totals.

AI Summary ​

sh
atlas summary SHOP-20260818-K3F9               # print the run's AI Summary
atlas summary SHOP-20260818-K3F9 --request     # write one if there is none, and wait for it
atlas summary SHOP-20260818-K3F9 --regenerate  # write a new one
atlas summary SHOP-20260818-K3F9 --json        # the whole summary, for scripts and AI agents

The same AI Summary as on the results page: what failed and why, how response times behaved, and how the run compares with earlier runs of the same plan. Reading a summary never writes one; --request and --regenerate do, and count toward the account's monthly AI Summary allowance. If AI Summary is off for the account, the command exits with 2; if a summary could not be written, with 3.

atlas summary always works with the summary of the whole run, never with a filtered view someone summarized on the results page.

Outcome ​

sh
atlas outcome SHOP-20260818-K3F9                          # show it
atlas outcome SHOP-20260818-K3F9 passed --note "Release 4.2"
atlas outcome SHOP-20260818-K3F9 passed --baseline        # also make it the baseline
atlas outcome SHOP-20260818-K3F9 ignored                  # leave it out of comparisons
atlas outcome SHOP-20260818-K3F9 clear

The same outcome as on the results page. --baseline makes the run the one later runs of its test plan are compared with, replacing the current baseline; --unset-baseline stops it being the baseline.

Tip

stop reports what actually happened rather than always claiming success. If a machine couldn't be reached, it says so and the run stays open, so a test can't keep running unnoticed.

Checking a test plan ​

sh
atlas plan check ./checkout.jmx -p SHOP     # a local file, against the project
atlas plan check -p SHOP --jmx checkout.jmx # the plan already in the project

Catches the problems that otherwise show up as an empty dashboard after the run: a data file the plan reads but the project doesn't have, a plan Atlas can't attach its reporting to, a structure broken by hand-editing, or no enabled thread group. It exits non-zero when the plan wouldn't produce results, so CI can stop before spending machine time.

It also tells you whether the plan's user count can be set at run time, and reports the things Atlas fixes for you — data-file paths from another machine, and GUI listeners left switched on.

Analysing a run ​

sh
atlas tests -p SHOP --limit 10          # recent runs, newest first
atlas timeseries SHOP-20260818-K3F9   # users, response time and errors over time
atlas errors SHOP-20260818-K3F9       # every distinct error, with its share
atlas errors SHOP-20260818-K3F9 --full --label "01.01 /home"

timeseries shows the shape of a run — where users peaked and where response times started to climb. errors shows one row per distinct failure with the request and response behind it, which is usually enough to tell a broken test plan from a struggling application.

What you can run on ​

sh
atlas capacity

Machines and clusters available to you, how many are free, and how much of your usage allowance is left. Worth checking before sizing a large test.

AI assistants ​

sh
atlas skills list              # what this version carries
atlas skills install           # into this project (.claude/skills/ + AGENTS.md)
atlas skills install --user    # for every project on this machine
atlas skills install --force   # replace files you have already edited

Installs the guidance an AI coding assistant needs to drive Atlas properly. See Atlas for AI Agents for what that enables, and Setting It Up for the details.

Recording ​

sh
atlas record https://example.com -o flow.jmx
atlas record https://example.com -o flow.jmx --upload -p SHOP
OptionMeaning
-o, --out <file>output file (an existing plan is added to, not replaced)
-n, --name <name>name for the recorded scenario
--cookies <file>preload cookies to skip a login step
--profile <dir>reuse a browser profile for a persistent session
--upload -p <project>upload the finished plan into a project
--createwith --upload: create the project first if it doesn't exist

See Recorder.

Atlas — load testing by CloudBeat · Cookie settings