@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 SKT ./SKT-2026.jmx ./data/mosdot.csv ./data/rashut.csv
atlas files list -p SKT

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

atlas files download -p SKT SKT-2026.jmx      # fetch a copy back
atlas files rm -p SKT 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:

./mosdot.csv          ✅  recommended
mosdot.csv            ✅  also works

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

C:\Users\me\Data\mosdot.csv      ❌  a Windows path cannot be found on a Linux generator
/home/me/data/mosdot.csv         ❌  absolute paths won't exist there either
./data/mosdot.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 SKT --jmx SKT-2026.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 SKT-20260818-194201
atlas results SKT-20260818-194201
atlas stop SKT-20260818-194201

--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 SKT ./SKT-2026.jmx ./data/mosdot.csv

atlas run -p SKT --jmx SKT-2026.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 SKT 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 record [url] | record a browser session | | atlas config get / set | default instance URL and project |

Most commands take -p, --project <name> and --json. Run atlas <command> --help for the full list of options.

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 SKT
atlas config set url https://atlas.cloudbeat.io