@cloudbeat/atlas-cli

Run Atlas load tests from your terminal or a CI pipeline, and record browser sessions into JMeter test plans.

npm install -g @cloudbeat/atlas-cli
atlas --help

Requires Node.js 18 or newer.

Getting started

Point the CLI at your Atlas instance and sign in.

For everyday use:

atlas login --url https://atlas.cloudbeat.io -u [email protected]

You'll be prompted for your password. The session lasts 8 hours.

For CI, create an API token on the Profile page of your Atlas instance and use that instead — it doesn't expire on its own and can be revoked at any time:

atlas login --token atlas_pat_...

Credentials are stored in ~/.atlas/config.json, readable only by you.

An API token acts as the person who created it and has the same permissions. It cannot be used to create more tokens or to change a password, so it is safe to hand to a build pipeline. Revoking it on the Profile page stops it working immediately.

Uploading files

A project holds your test plan and any data files it reads. Upload them whenever they change — this is independent of running a test, and uploaded files stay in the project until you replace or delete them.

atlas files upload -p SHOP ./checkout.jmx ./data/users.csv ./data/products.csv
atlas files list -p SHOP

Uploading a file with a name that already exists replaces it.

atlas files download -p SHOP checkout.jmx      # fetch a copy back
atlas files rm -p SHOP old-data.csv            # delete one

How files are laid out — and how to reference them

All of a project's files live together in one flat folder. There are no subdirectories: whatever you upload lands side by side, and when a test runs, the test plan and its data files sit in the same directory on every load generator.

So in your test plan, reference data files by a plain relative path:

./users.csv          ✅  recommended
users.csv            ✅  also works

Not by an absolute path, and not through a folder:

C:\Users\me\Data\users.csv      ❌  a Windows path cannot be found on a Linux generator
/home/me/data/users.csv         ❌  absolute paths won't exist there either
./data/users.csv                ❌  the folder structure is not preserved

This catches people out most often with test plans authored in JMeter on Windows, where CSV Data Set Config entries usually hold a full C:\… path. Open each one and reduce it to ./filename. If a path can't be resolved at run time, every thread in that thread group stops immediately — the test appears to run but that group reports no results at all.

Two related things worth checking before your first run:

• Every file the plan references must actually be uploaded. Upload the plan and its data files together.
• Disable GUI listeners left switched on in the plan — View Results Tree, Aggregate Report, Simple Data Writer. They consume a lot of memory during a headless run, and Atlas collects its results separately.

Running a test

atlas run -p SHOP --jmx checkout.jmx --servers 5 --wait

--wait follows the run to completion and prints the aggregation report. Without it, the command returns as soon as the test has been submitted, and you can check on it later:

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

--jmx is only needed when a project holds more than one test plan.

Load generators that are switched off are started for you and shut down again when the test finishes.

Choosing where it runs

| | | |---|---| | --servers 5 | use any 5 available load generators | | --server gen-01 --server gen-02 | pick specific ones by name | | --cluster my-cluster --units 10 | run on 10 containers in an elastic cluster |

Other run options

| | | |---|---| | --jmx <filename> | which uploaded plan to run (defaults to the project's) | | --args "<jmeter args>" | extra JMeter arguments | | --no-split | send whole data files to every generator instead of dividing them up | | --timeout 30m | how long --wait will wait before giving up (default 2h) | | --json | machine-readable output |

Using it in CI

Set the connection details as environment variables and let the exit code fail the build:

export ATLAS_URL=https://atlas.cloudbeat.io
export ATLAS_TOKEN=atlas_pat_...

# Only if the plan or its data live in this repository and may have changed.
atlas files upload -p SHOP ./checkout.jmx ./data/users.csv

atlas run -p SHOP --jmx checkout.jmx --servers 5 \
          --gate "error_rate<1,p95<2000" \
          --junit results.xml

If your test plan is maintained in Atlas rather than in the repository, drop the upload step — the run command works on its own.

Pass/fail thresholds

--gate fails the command when a threshold is breached. Thresholds are checked against the run's overall totals:

| metric | meaning | |--------|---------| | error_rate | percentage of failed requests | | avg | average response time, ms | | p90, p95, p99 | percentile response times, ms | | max | slowest response, ms | | throughput | requests per second | | requests | total requests |

Use <, <=, > or >=. Separate several with commas, or repeat --gate. Setting a gate implies --wait, since there is nothing to check until the test has finished.

Exit codes

| code | meaning | |------|---------| | 0 | the test ran and every threshold passed | | 1 | the test ran but a --gate threshold was breached | | 2 | something was wrong with the request — bad option, unknown project, not signed in | | 3 | the test failed or timed out, or the server could not be reached |

JUnit report

--junit results.xml writes a standard JUnit file with one test case per threshold, so CI shows each one as its own pass or fail. The run's headline numbers are included as properties.

Recording a scenario

atlas record opens a browser, records what you do, and writes a JMeter test plan:

atlas record https://example.com -o flow.jmx

Add --upload -p SHOP to put the finished plan straight into a project, ready to run.

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

The recorder is distributed separately because it downloads its own browser, which most CI machines don't need. atlas record will tell you how to install it if it isn't present.

Command reference

| | | |---|---| | 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 (--yes to skip the prompt) | | atlas run | start a test | | atlas status <testId> | check whether a test is still running | | atlas results <testId> | show the aggregation report for a test | | 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 install | set up an AI assistant to drive Atlas properly | | atlas docs [topic] | read the documentation without leaving the terminal | | atlas config get / set | default instance URL and project |

Every command takes --json, and -p, --project <name> where a project applies. Run atlas <command> --help for the full list of options.

When a command fails with --json, the error is printed as JSON on standard error, so a script can read clean output on standard out and still see why a run stopped.

Working with an AI assistant

atlas skills install

Writes task-specific guidance into the current project — .claude/skills/ for Claude Code, and AGENTS.md for Copilot, Cursor and anything else that reads it — covering the end-to-end flow, recording, dynamic values, sizing a run and reading results. --user installs for every project, --force replaces files you have edited. Start a new assistant session afterwards.

atlas schema --json describes the whole command surface, and atlas docs prints the documentation without a network connection.

Settings

Command-line options win over environment variables, which win over the saved configuration file.

| variable | meaning | |----------|---------| | ATLAS_URL | your Atlas instance | | ATLAS_TOKEN | API token | | ATLAS_PROJECT | project to use when --project is omitted | | ATLAS_DEBUG | set to any value to print full error details |

To avoid repeating yourself:

atlas config set project SHOP
atlas config set url https://atlas.cloudbeat.io

Compatibility

Use 0.6.0 or later. Atlas results are private: reading them takes your login or API token. Earlier versions read results without one, so against a current Atlas their atlas results, atlas tests, atlas analyze and the result check behind --wait, --gate and --junit fail with exit code 2. The run itself still starts. Upgrade with npm install -g @cloudbeat/atlas-cli@latest.

The dashboard link the CLI prints opens the run in Atlas, after signing in. To show results to someone without an Atlas login, share the run from its dashboard.

Otherwise the CLI works with any Atlas instance. From 0.3.0 the CLI talks to a new API path, and falls back automatically when it finds an older instance that does not serve it — so you do not need to match versions between the CLI and your Atlas server.