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 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 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 --yes

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

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-194201
atlas results SHOP-20260818-194201
atlas results SHOP-20260818-194201 --json
atlas stop SHOP-20260818-194201

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

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 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

atlas tests -p SHOP --limit 10          # recent runs, newest first
atlas timeseries SHOP-20260818-194201   # users, response time and errors over time
atlas errors SHOP-20260818-194201       # every distinct error, with its share
atlas errors SHOP-20260818-194201 --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 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

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

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

See Recorder.