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
| Command | What it does |
|---|---|
atlas login | sign in with a password or an API token |
atlas logout | forget the stored credential |
atlas whoami | show who you're signed in as |
atlas projects | list the projects you can access |
atlas projects create <name> | create a project (account admins) |
atlas files list | list 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 run | start 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 tests | list 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 capacity | what 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 schema | describe every command and option (for scripts and AI agents) |
atlas skills list / install | install the AI-assistant guidance into your project |
atlas docs [topic] | read the documentation without leaving the terminal |
atlas config get / set | default instance URL and project |
Files
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 --yesA 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
atlas run -p SHOP --jmx checkout.jmx --servers 5 --wait| Option | Meaning |
|---|---|
--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-split | send whole data files to every machine |
--wait | follow 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-summary | have an AI Summary written when the run ends; with --wait, print it |
--no-set-outcome | with --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
atlas status SHOP-20260818-K3F9
atlas results SHOP-20260818-K3F9
atlas results SHOP-20260818-K3F9 --json
atlas stop SHOP-20260818-K3F9results prints the aggregation report — one row per request, plus totals.
AI Summary
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 agentsThe 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
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 clearThe 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
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 projectCatches 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
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
atlas capacityMachines 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
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 editedInstalls 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
atlas record https://example.com -o flow.jmx
atlas record https://example.com -o flow.jmx --upload -p SHOP| Option | Meaning |
|---|---|
-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 |
--create | with --upload: create the project first if it doesn't exist |
See Recorder.