@cloudbeat/atlas-cli 0.2.0 → 0.4.0

package/dist/docs/commands.md

@@ -0,0 +1,155 @@
+# 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
+
+```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
+```
+
+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](/guide/test-files) for how files are laid out and divided
+between machines.
+
+## Running
+
+```sh
+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](/cli/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
+
+```sh
+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.
+
+`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-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
+
+```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](/agents/) for what that enables, and
+[Setting It Up](/agents/setup) for the details.
+
+## Recording
+
+```sh
+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](/recorder/).

package/dist/docs/files.md

@@ -0,0 +1,86 @@
+# Test Files
+
+A project holds your test plan and every data file it reads. Upload them
+whenever they change — this is independent of running a test, and files stay in
+the project until you replace or delete them.
+
+## Uploading
+
+From the **Files** tab, upload the `.jmx` and its data files. From the CLI:
+
+```bash
+atlas files upload -p SHOP ./checkout.jmx ./data/users.csv ./data/products.csv
+```
+
+Uploading a file whose name already exists **replaces** it.
+
+## How files are laid out
+
+**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 reference data files from your plan 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
+```
+
+If a data file path can't be resolved, every thread in that thread group throws
+before issuing a single request. There are no failed samples, so the summary
+shows `0.00%` errors and the dashboard simply **omits that thread group** while
+the others look healthy.
+
+If a thread group is missing from your results, this is the first thing to check.
+
+## How data files are divided
+
+When a test runs on several machines, Atlas **divides** your data files between
+them rather than giving every machine the whole file. With 1,000 rows across 5
+generators, each gets roughly 200 rows, and no two machines use the same row.
+
+This is what you usually want: a load test where 5 machines all replay the same
+200 users isn't testing what you think it is.
+
+**Header rows are handled for you.** If your plan's CSV Data Set Config says the
+file has a header, that header is copied to every machine's slice and only the
+data rows are divided.
+
+Files are divided byte for byte — column order, quoting, embedded commas and
+newlines all survive exactly as uploaded.
+
+To switch dividing off and send whole files to every machine, use `--no-split`
+(CLI) or clear the split option on the Run Test tab.
+
+`.csv` and `.txt` files are divided. `.jmx` and everything else is copied whole
+to every machine.
+
+## Downloading and deleting
+
+```bash
+atlas files list -p SHOP
+atlas files download -p SHOP checkout.jmx
+atlas files rm -p SHOP old-data.csv
+```
+
+In the web interface, the Files tab has a download and a delete action per file.
+
+## 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 eat memory during a headless
+  run, and Atlas collects results separately.
+
+Full details in [Test Plan Requirements](/reference/test-plans).

package/dist/docs/generators.md

@@ -0,0 +1,52 @@
+# Load Generators
+
+A **load generator** is a machine that runs JMeter and produces load. Atlas
+copies your test plan to each one and starts them together.
+
+Most teams share a pool that is already set up — in that case you can skip this
+section entirely and just pick machines when you [run a test](/guide/running-tests).
+
+Read on if you need to add machines of your own.
+
+## Two kinds
+
+| | |
+|---|---|
+| **Servers** | Fixed machines that exist whether or not a test is running. Cloud VMs Atlas can power on and off, or your own hardware. |
+| **Clusters** | Elastic capacity. Units are created when a test starts and destroyed when it ends. |
+
+Both appear under **Fleet** in the sidebar, on separate tabs.
+
+## Why run your own?
+
+The usual reason is that your application isn't reachable from the internet.
+A load generator inside your own network can reach it, and only needs an
+**outbound** connection to Atlas — no inbound access, no firewall changes, no
+VPN.
+
+The other reason is geography: generating load from where your users actually
+are gives you a more honest number.
+
+## Power state
+
+Machines Atlas can control are **powered on when a test needs them and switched
+off when it ends**, so you don't pay for idle capacity. This is why a switched-off
+machine can still be selected on the Run Test tab.
+
+Machines Atlas can't power — your own hardware — are assumed to be always on and
+are never powered off.
+
+## Status
+
+The Fleet page shows two independent things per machine:
+
+- whether the **machine** is on or off
+- whether its **connection** to Atlas is live
+
+A machine can be on but not connected, which usually means the agent isn't
+running. See [Troubleshooting](/reference/troubleshooting).
+
+## Next
+
+- [Adding a Machine](/generators/adding)
+- [Clusters](/generators/clusters)

package/dist/docs/getting-started.md

@@ -0,0 +1,85 @@
+# Getting Started
+
+This walks through one complete test: uploading a plan, running it, and reading
+the result. It should take a few minutes.
+
+## Sign in
+
+Open your Atlas instance and go to **/app** — for a typical installation that
+is [atlas.cloudbeat.io/app](https://atlas.cloudbeat.io/app). Sign in with
+your email address and password.
+
+If you have access to more than one account, you'll be asked which to work in.
+You can switch later from the account selector in the sidebar.
+
+## Open a project
+
+A **project** holds your test plan, its data files, and the history of every run.
+Pick one from **Projects** in the sidebar, or ask your administrator to create
+one if the list is empty.
+
+The project page has three tabs:
+
+| Tab | What it holds |
+|---|---|
+| **Results** | Every run of this project, newest first |
+| **Files** | The test plan and data files |
+| **Run Test** | Start a new run |
+
+## Upload your test plan
+
+Go to **Files** and upload your `.jmx` along with every data file it reads.
+
+Test plans written in JMeter on Windows usually reference data files by a full
+`C:\...\data.csv` path, which does not exist on a load generator. Open each
+**CSV Data Set Config** and reduce the filename to `./data.csv`.
+
+If a path can't be found at run time, every thread in that thread group stops
+before sending a single request — the test appears to run, but that group
+reports nothing at all. See [Test Plan Requirements](/reference/test-plans).
+
+## Run it
+
+Go to **Run Test**, choose where to run:
+
+- **Servers** — pick individual load generators. Machines that are switched off
+  can still be selected; they are powered on for you.
+- **Cluster** — run on a cluster and say how many units you want.
+
+If the project holds more than one `.jmx`, pick which one to run. Then press
+**Run**.
+
+You do not need to deploy or prepare anything first. Atlas reserves the
+machines, copies your files, and starts JMeter.
+
+## Watch it run
+
+The page switches to a live view showing each stage — powering on, deploying,
+then running — with a **Stop** button.
+
+Once results start arriving, open the dashboard for the run from the **Results**
+tab. You'll see:
+
+- **Active users**, **response time** and **error rate** on one chart
+- Headline numbers: duration, peak users, requests per second, average response
+  time, error rate
+- A per-request table you can sort and drill into
+
+The dashboard updates itself while the test runs. See
+[Reading Results](/guide/results) for what each number means.
+
+## Stop it, or let it finish
+
+A test ends on its own when the plan says so — a thread group's duration or loop
+count running out. Press **Stop** to end it early.
+
+When a run finishes, the load generators are released and any that Atlas powered
+on are switched off again.
+
+## Next steps
+
+- [Running a Test](/guide/running-tests) — all the options, and how data files
+  are divided between machines
+- [Reading Results](/guide/results) — the dashboard in detail
+- [CLI](/cli/install) — do all of this from a terminal or a CI pipeline
+- [Recorder](/recorder/) — generate a test plan by clicking through your app

package/dist/docs/index.json

@@ -0,0 +1,110 @@
+[
+  {
+    "topic": "getting-started",
+    "title": "Getting Started",
+    "summary": "This walks through one complete test: uploading a plan, running it, and reading the result. It should take a few minutes.",
+    "source": "guide/getting-started.md"
+  },
+  {
+    "topic": "projects",
+    "title": "Projects",
+    "summary": "A project is the unit everything else hangs off. It holds:",
+    "source": "guide/projects.md"
+  },
+  {
+    "topic": "files",
+    "title": "Test Files",
+    "summary": "A project holds your test plan and every data file it reads. Upload them whenever they change — this is independent of running a test, and files stay in the project until you replace or delete them.",
+    "source": "guide/test-files.md"
+  },
+  {
+    "topic": "running",
+    "title": "Running a Test",
+    "summary": "Open a project, go to **Run Test**, choose where to run, and press **Run**.",
+    "source": "guide/running-tests.md"
+  },
+  {
+    "topic": "results",
+    "title": "Reading Results",
+    "summary": "Every run has a dashboard. Open it from a project's **Results** tab, or from the test list at `/<project>`.",
+    "source": "guide/results.md"
+  },
+  {
+    "topic": "ai-agents",
+    "title": "Atlas for AI Agents",
+    "summary": "**Describe the test. Let the agent build it.**",
+    "source": "agents/index.md"
+  },
+  {
+    "topic": "agent-setup",
+    "title": "Setting It Up",
+    "summary": "Two commands to install, one to sign in. The guidance is bundled with the CLI, so there is nothing to download separately and nothing to keep in sync by hand.",
+    "source": "agents/setup.md"
+  },
+  {
+    "topic": "agent-tasks",
+    "title": "What an Agent Can Do",
+    "summary": "The whole lifecycle, from an empty project to a report you can send someone. Each section below is a real thing to ask for, what the agent does about it, and what it should ask you along the way.",
+    "source": "agents/capabilities.md"
+  },
+  {
+    "topic": "skills",
+    "title": "The Skills",
+    "summary": "`atlas skills install` writes six skills plus a vendor-neutral `AGENTS.md`. Each skill is a short document covering one part of load testing: what to do, in what order, and which mistakes to avoid.",
+    "source": "agents/skills.md"
+  },
+  {
+    "topic": "automation",
+    "title": "Building Your Own Integration",
+    "summary": "The same surfaces the bundled skills use are there for your own scripts, bots and agents. No SDK, no separate API client: the CLI is the integration point, and everything it does is scriptable.",
+    "source": "agents/automation.md"
+  },
+  {
+    "topic": "generators",
+    "title": "Load Generators",
+    "summary": "A **load generator** is a machine that runs JMeter and produces load. Atlas copies your test plan to each one and starts them together.",
+    "source": "generators/index.md"
+  },
+  {
+    "topic": "clusters",
+    "title": "Clusters",
+    "summary": "A **cluster** is elastic capacity: instead of fixed machines that sit there between tests, units are created when a test starts and destroyed when it ends.",
+    "source": "generators/clusters.md"
+  },
+  {
+    "topic": "recorder",
+    "title": "Recording a Scenario",
+    "summary": "If you don't have a JMeter test plan yet, the recorder makes one by watching you use your application. You click through a flow in a real browser — log in, search, check out — and it writes a `.jmx` you can run as a load test.",
+    "source": "recorder/index.md"
+  },
+  {
+    "topic": "commands",
+    "title": "Commands",
+    "summary": "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.",
+    "source": "cli/commands.md"
+  },
+  {
+    "topic": "auth",
+    "title": "Signing In",
+    "summary": "You'll be prompted for your password. The session lasts **8 hours**.",
+    "source": "cli/authentication.md"
+  },
+  {
+    "topic": "ci",
+    "title": "Running in CI",
+    "summary": "The point of running Atlas from CI is to catch a performance regression the same way you catch a failing unit test — automatically, on the build that caused it.",
+    "source": "cli/ci.md"
+  },
+  {
+    "topic": "test-plans",
+    "title": "Test Plan Requirements",
+    "summary": "Atlas runs standard JMeter test plans, but a plan written on a desktop needs a few changes before it runs correctly on a fleet of Linux load generators. These are the things that actually catch people out.",
+    "source": "reference/test-plans.md"
+  },
+  {
+    "topic": "troubleshooting",
+    "title": "Troubleshooting",
+    "summary": "The usual cause is a **data file path that can't be resolved**. Every thread in that group fails before sending a request, so there are no errors to report — the group simply isn't there.",
+    "source": "reference/troubleshooting.md"
+  }
+]

package/dist/docs/projects.md

@@ -0,0 +1,50 @@
+# Projects
+
+A project is the unit everything else hangs off. It holds:
+
+- one or more **test plans** (`.jmx`)
+- the **data files** those plans read
+- the **history** of every run, with its results
+
+Projects are also how access is granted: you see the projects you have been
+given access to, and nothing else.
+
+## The project page
+
+### Results
+
+Every run of this project, newest first. Each row shows when it started, how
+long it ran, and the peak number of concurrent users it reached. Click a run to
+open its dashboard.
+
+You can give a run a **name** — click the name cell and type. This is worth
+doing when you run variations against each other, since `SHOP-20260818-194201`
+tells you when a run happened but not what it was for. "Baseline, 500 users" is
+easier to find three weeks later.
+
+### Files
+
+Upload, download and delete the project's files. See
+[Test Files](/guide/test-files).
+
+### Run Test
+
+Start a run. See [Running a Test](/guide/running-tests).
+
+## Choosing which plan runs
+
+A project can hold several test plans. One of them is the project's **default** —
+the one used when you don't say otherwise.
+
+When a project holds more than one `.jmx`, the Run Test tab shows a dropdown to
+pick between them, and remembers your last choice for that project. From the
+CLI, pass `--jmx`:
+
+```bash
+atlas run -p SHOP --jmx checkout-peak.jmx --servers 5
+```
+
+## Creating a project
+
+Projects are created by administrators. If you need one, ask — you'll need to
+say which account it belongs to, since that determines who can see it.

package/dist/docs/recorder.md

@@ -0,0 +1,143 @@
+# Recording a Scenario
+
+If you don't have a JMeter test plan yet, the recorder makes one by watching you
+use your application. You click through a flow in a real browser — log in,
+search, check out — and it writes a `.jmx` you can run as a load test.
+
+## Install
+
+```sh
+npm install -g @cloudbeat/atlas-recorder
+```
+
+This downloads a private browser build (a few hundred MB) used for capture. It
+won't touch the browsers you already have. Requires Node.js 18 or newer.
+
+It's a separate package from the CLI because CI machines run tests but never
+record them.
+
+## Record
+
+```sh
+atlas-rec record https://example.com -o checkout.jmx -n "Checkout"
+```
+
+Or through the CLI, which can upload the result straight into a project:
+
+```sh
+atlas record https://example.com -o checkout.jmx --upload -p SHOP
+```
+
+A browser window opens with a small control panel in the corner. Click through
+your flow, then press **Stop**.
+
+Your recording is saved when you press Stop, when you close the window, and on
+Ctrl+C — closing the window by mistake won't lose it.
+
+## What you get
+
+Each thing you do — a click, a form submit, a page change — becomes a labelled
+**transaction**, with the requests it triggered grouped underneath. A report then
+tells you "Checkout took 3.2s" rather than just listing URLs.
+
+While recording you can:
+
+- **rename** a transaction so the report reads in your language, not the app's URLs
+- **➕ New** to start a new transaction before you click, when one page holds two
+  steps worth measuring separately
+- expand a transaction and **exclude** or **delete** individual requests
+- **⏸ Pause** while you set something up you don't want recorded
+
+## What's kept, and what isn't
+
+**Kept:** the requests your application makes — pages, API calls, form posts.
+
+**Skipped:** images, stylesheets, fonts and known analytics traffic. These
+inflate a load test without telling you anything about your application. Include
+one from the control panel if you need it.
+
+## Dynamic values are handled
+
+If a request sends something it was given earlier — a CSRF token, a session ID,
+an item ID from a search result — the recorder finds where that value came from
+and pulls it out of the live response at run time instead of replaying the
+recorded one. Without this, a recorded plan usually fails on the second run,
+when the token has changed.
+
+Each of these gets a check attached, so if the value ever stops coming back the
+sample fails loudly rather than quietly posting a stale token.
+
+## Adding to an existing plan
+
+Point `-o` at a plan that already exists and the new recording is **added** to it
+as another thread group, leaving what's there untouched. A `.bak` copy is written
+first.
+
+```sh
+atlas-rec record https://example.com -o suite.jmx -n "Checkout"
+atlas-rec record https://example.com -o suite.jmx -n "Search"
+```
+
+## Recording behind a login
+
+**Reuse a signed-in session** — saved when you stop, reloaded next time:
+
+```sh
+atlas-rec record https://app.example.com -o app.jmx --profile ./session.json
+```
+
+**Bring cookies from your own browser** — export them and pass `--cookies`:
+
+```sh
+atlas-rec record https://app.example.com/home -o app.jmx --cookies ./cookies.json
+```
+
+## Options
+
+| Option | Meaning |
+|---|---|
+| `-o, --out <file>` | Where to write. An existing plan is added to; otherwise created |
+| `-n, --name <name>` | Name for the scenario |
+| `-t, --threads <n>` | Number of users — only when creating a new plan |
+| `-l, --loops <n>` | Iterations per user — only when creating a new plan |
+| `--profile <file>` | Save and reuse a signed-in session |
+| `--cookies <file>` | Start already signed in, using exported cookies |
+| `--correlations <file>` | Pin named parameters to a value of your choosing |
+| `--no-correlate` | Replay recorded values as-is |
+| `--no-timestamps` | Keep recorded timestamps instead of using the current time |
+
+## Check the plan before running it at scale
+
+The recorder captures a single pass through your app. Anything that only appears
+sometimes — a cookie banner, an A/B variant, a retry — is recorded only if it
+happened while you clicked.
+
+When a step redirects, the redirect is followed *and* the destination is recorded
+on its own, so that step can hit the destination twice per iteration. Delete the
+duplicate from the control panel, or from the plan afterwards, if it would skew
+your numbers.
+
+**Think-time pauses** are recorded but switched off, so the plan runs flat out
+until you decide otherwise. Enable the `Settings - Sleeps` block in the plan and
+set the durations you want.
+
+## Driven by an agent, or a script
+
+A recording does not have to be clicked by a person. The same session can be
+controlled command by command — `snapshot` to see the page, `click`, `fill`,
+`tx new` to name the step that follows — which is how an AI assistant records a
+flow for you, and how a script can automate one.
+
+The browser stays visible throughout and your own clicks are recorded too, so
+you can take over for a login and hand it back.
+
+```sh
+atlas-rec start https://shop.example.com -o flow.jmx -n "Checkout"
+atlas-rec snapshot
+atlas-rec tx new "Search"
+atlas-rec click --role button --name "Search"
+atlas-rec stop
+```
+
+See [Your Own Integration](/agents/automation) for the full set, and
+[Atlas for AI Agents](/agents/) to let an assistant do it.