@cloudbeat/atlas-cli 0.2.0 → 0.4.0

package/README.md

@@ -43,15 +43,15 @@ whenever they change — this is independent of running a test, and uploaded
 files stay in the project until you replace or delete them.
 
 ```bash
-atlas files upload -p SKT ./SKT-2026.jmx ./data/mosdot.csv ./data/rashut.csv
-atlas files list -p SKT
+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.
 
 ```bash
-atlas files download -p SKT SKT-2026.jmx      # fetch a copy back
-atlas files rm -p SKT old-data.csv            # delete one
+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
@@ -64,16 +64,16 @@ generator.
 So in your test plan, reference data files by a plain relative path:
 
 ```
-./mosdot.csv          ✅  recommended
-mosdot.csv            ✅  also works
+./users.csv          ✅  recommended
+users.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
+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
@@ -93,7 +93,7 @@ Two related things worth checking before your first run:
 ## Running a test
 
 ```bash
-atlas run -p SKT --jmx SKT-2026.jmx --servers 5 --wait
+atlas run -p SHOP --jmx checkout.jmx --servers 5 --wait
 ```
 
 `--wait` follows the run to completion and prints the aggregation report.
@@ -101,9 +101,9 @@ Without it, the command returns as soon as the test has been submitted, and you
 can check on it later:
 
 ```bash
-atlas status SKT-20260818-194201
-atlas results SKT-20260818-194201
-atlas stop SKT-20260818-194201
+atlas status SHOP-20260818-194201
+atlas results SHOP-20260818-194201
+atlas stop SHOP-20260818-194201
 ```
 
 `--jmx` is only needed when a project holds more than one test plan.
@@ -139,9 +139,9 @@ 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 files upload -p SHOP ./checkout.jmx ./data/users.csv
 
-atlas run -p SKT --jmx SKT-2026.jmx --servers 5 \
+atlas run -p SHOP --jmx checkout.jmx --servers 5 \
           --gate "error_rate<1,p95<2000" \
           --junit results.xml
 ```
@@ -191,7 +191,7 @@ plan:
 atlas record https://example.com -o flow.jmx
 ```
 
-Add `--upload -p SKT` to put the finished plan straight into a project, ready
+Add `--upload -p SHOP` to put the finished plan straight into a project, ready
 to run.
 
 | | |
@@ -221,11 +221,38 @@ it if it isn't present.
 | `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 |
 
-Most commands take `-p, --project <name>` and `--json`. Run
-`atlas <command> --help` for the full list of options.
+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
+
+```bash
+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
 
@@ -242,6 +269,12 @@ configuration file.
 To avoid repeating yourself:
 
 ```bash
-atlas config set project SKT
+atlas config set project SHOP
 atlas config set url https://atlas.cloudbeat.io
 ```
+
+## Compatibility
+
+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.

package/dist/api.js

@@ -8,6 +8,9 @@ const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const config_1 = require("./config");
 const ui_1 = require("./ui");
+/** Where the control-plane API lives today, and where it used to live. */
+const API_PREFIX = '/app/api';
+const LEGACY_API_PREFIX = '/admin/api';
 // ── Client ───────────────────────────────────────────────────────────────────
 class AtlasApi {
     url;
@@ -22,6 +25,33 @@ class AtlasApi {
     get baseUrl() {
         return this.url;
     }
+    /**
+     * The control-plane API prefix.
+     *
+     * It moved from /admin/api to /app/api when the browser UI moved to /app.
+     * Servers keep serving the old prefix so CLIs released before that keep
+     * working; this handles the other direction — a current CLI pointed at an
+     * Atlas that predates the move. The first 404 under the new prefix switches
+     * to the old one for the life of the process, so there is no extra round
+     * trip against an up-to-date server.
+     */
+    prefix = API_PREFIX;
+    prefixResolved = false;
+    get api() {
+        return this.prefix;
+    }
+    /** Fetch that retries once under the legacy prefix if the route is absent. */
+    async fetchApi(routePath, init) {
+        const res = await fetch(`${this.url}${routePath}`, init);
+        if (res.status === 404 && !this.prefixResolved && routePath.startsWith(API_PREFIX)) {
+            this.prefix = LEGACY_API_PREFIX;
+            this.prefixResolved = true;
+            const legacy = routePath.replace(API_PREFIX, LEGACY_API_PREFIX);
+            return { res: await fetch(`${this.url}${legacy}`, init), routePath: legacy };
+        }
+        this.prefixResolved = true;
+        return { res, routePath };
+    }
     authHeaders() {
         if (!this.token) {
             throw new ui_1.CliError('Not authenticated. Run `atlas login`, or set ATLAS_TOKEN to an API token.', ui_1.EXIT.USAGE);
@@ -34,9 +64,9 @@ class AtlasApi {
         const headers = auth ? this.authHeaders() : {};
         if (opts.body !== undefined)
             headers['Content-Type'] = 'application/json';
-        let res;
+        let attempt;
         try {
-            res = await fetch(`${this.url}${routePath}`, {
+            attempt = await this.fetchApi(routePath, {
                 method,
                 headers,
                 body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
@@ -45,7 +75,7 @@ class AtlasApi {
         catch (err) {
             throw new ui_1.CliError(`Cannot reach ${this.url}: ${err.message}`, ui_1.EXIT.ERROR);
         }
-        return this.parse(method, routePath, res);
+        return this.parse(method, attempt.routePath, attempt.res);
     }
     async parse(method, routePath, res) {
         const text = await res.text();
@@ -67,9 +97,11 @@ class AtlasApi {
     }
     // ── auth ──────────────────────────────────────────────────────────────────
     async login(username, password) {
-        let res;
+        // Usually the very first call a CLI makes, so this is where the prefix
+        // normally gets resolved against an older server.
+        let attempt;
         try {
-            res = await fetch(`${this.url}/admin/api/auth/login`, {
+            attempt = await this.fetchApi(`${this.api}/auth/login`, {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json' },
                 body: JSON.stringify({ username, password }),
@@ -78,14 +110,14 @@ class AtlasApi {
         catch (err) {
             throw new ui_1.CliError(`Cannot reach ${this.url}: ${err.message}`, ui_1.EXIT.ERROR);
         }
-        return this.parse('POST', '/admin/api/auth/login', res);
+        return this.parse('POST', attempt.routePath, attempt.res);
     }
     async me() {
-        return this.request('GET', '/admin/api/auth/me');
+        return this.request('GET', `${this.api}/auth/me`);
     }
     // ── projects & files ──────────────────────────────────────────────────────
     async projects() {
-        return this.request('GET', '/admin/api/projects');
+        return this.request('GET', `${this.api}/projects`);
     }
     /** Projects are addressed by name on the CLI; the API wants the id. */
     async projectByName(name) {
@@ -98,7 +130,7 @@ class AtlasApi {
         return hit;
     }
     async files(projectId) {
-        return this.request('GET', `/admin/api/projects/${projectId}/files`);
+        return this.request('GET', `${this.api}/projects/${projectId}/files`);
     }
     async uploadFiles(projectId, paths) {
         const form = new FormData();
@@ -110,7 +142,7 @@ class AtlasApi {
         }
         let res;
         try {
-            res = await fetch(`${this.url}/admin/api/projects/${projectId}/files`, {
+            res = await fetch(`${this.url}${this.api}/projects/${projectId}/files`, {
                 method: 'POST',
                 headers: this.authHeaders(), // no Content-Type: fetch sets the multipart boundary
                 body: form,
@@ -119,33 +151,39 @@ class AtlasApi {
         catch (err) {
             throw new ui_1.CliError(`Upload failed: ${err.message}`, ui_1.EXIT.ERROR);
         }
-        return this.parse('POST', `/admin/api/projects/${projectId}/files`, res);
+        return this.parse('POST', `${this.api}/projects/${projectId}/files`, res);
     }
     async downloadFile(projectId, filename) {
-        const res = await fetch(`${this.url}/admin/api/projects/${projectId}/files/${encodeURIComponent(filename)}/download`, { headers: this.authHeaders() });
+        const res = await fetch(`${this.url}${this.api}/projects/${projectId}/files/${encodeURIComponent(filename)}/download`, { headers: this.authHeaders() });
         if (!res.ok)
             throw new ui_1.CliError(`Download failed: ${res.status} ${res.statusText}`, ui_1.EXIT.ERROR);
         return Buffer.from(await res.arrayBuffer());
     }
     async deleteFile(projectId, filename) {
-        await this.request('DELETE', `/admin/api/projects/${projectId}/files/${encodeURIComponent(filename)}`);
+        await this.request('DELETE', `${this.api}/projects/${projectId}/files/${encodeURIComponent(filename)}`);
     }
     // ── fleet ─────────────────────────────────────────────────────────────────
     async servers() {
-        return this.request('GET', '/admin/api/servers');
+        return this.request('GET', `${this.api}/servers`);
     }
     async clusters() {
-        return this.request('GET', '/admin/api/clusters');
+        return this.request('GET', `${this.api}/clusters`);
+    }
+    async quota() {
+        return this.request('GET', `${this.api}/auth/quota`);
+    }
+    async fleet() {
+        return this.request('GET', `${this.api}/auth/fleet`);
     }
     // ── runs ──────────────────────────────────────────────────────────────────
     async run(projectId, body) {
-        return this.request('POST', `/admin/api/projects/${projectId}/run`, { body });
+        return this.request('POST', `${this.api}/projects/${projectId}/run`, { body });
     }
     async queueEntry(queueId) {
-        return this.request('GET', `/admin/api/tests/queue/${queueId}`);
+        return this.request('GET', `${this.api}/tests/queue/${queueId}`);
     }
     async stop(testId) {
-        return this.request('POST', `/admin/api/tests/${encodeURIComponent(testId)}/stop`, { body: {} });
+        return this.request('POST', `${this.api}/tests/${encodeURIComponent(testId)}/stop`, { body: {} });
     }
     // ── results (public dashboard API) ─────────────────────────────────────────
     async summary(testId) {
@@ -154,6 +192,20 @@ class AtlasApi {
     async testStatus(testId) {
         return this.request('GET', `/api/tests/${encodeURIComponent(testId)}/status`, { auth: false });
     }
+    /** Runs for a project, most recent first (the dashboard's test list). */
+    async tests(project) {
+        return this.request('GET', `/api/projects/${encodeURIComponent(project)}/tests`, { auth: false });
+    }
+    /** 30s-bucketed points: active users, average response time, error rate. */
+    async timeseries(testId, label) {
+        const q = label ? `?label=${encodeURIComponent(label)}` : '';
+        return this.request('GET', `/api/tests/${encodeURIComponent(testId)}/timeseries${q}`, { auth: false });
+    }
+    /** One document per distinct error type, with the full request/response. */
+    async errors(testId, label) {
+        const q = label ? `?label=${encodeURIComponent(label)}` : '';
+        return this.request('GET', `/api/tests/${encodeURIComponent(testId)}/errors${q}`, { auth: false });
+    }
 }
 exports.AtlasApi = AtlasApi;
 //# sourceMappingURL=api.js.map

package/dist/cli.js

@@ -14,6 +14,13 @@ const files_1 = require("./commands/files");
 const run_1 = require("./commands/run");
 const results_1 = require("./commands/results");
 const record_1 = require("./commands/record");
+const tests_1 = require("./commands/tests");
+const analyze_1 = require("./commands/analyze");
+const capacity_1 = require("./commands/capacity");
+const schema_1 = require("./commands/schema");
+const docs_1 = require("./commands/docs");
+const skills_1 = require("./commands/skills");
+const plan_1 = require("./commands/plan");
 // eslint-disable-next-line @typescript-eslint/no-var-requires
 const { version } = require('../package.json');
 const program = new commander_1.Command();
@@ -37,13 +44,26 @@ Examples:
   atlas run -p SKT --jmx SKT-2026.jmx --servers 5 --wait \\
             --gate "error_rate<1,p95<2000" --junit results.xml
   atlas record https://example.com -o flow.jmx --upload -p SKT
+
+For scripts and AI agents:
+  atlas schema --json      every command, argument and option
+  atlas docs               the documentation, offline
+  atlas skills install     teach an AI assistant to drive Atlas properly
+  --json                   on every command; failures print JSON on stderr
 `);
 (0, auth_1.registerAuth)(program);
 (0, projects_1.registerProjects)(program);
 (0, files_1.registerFiles)(program);
 (0, run_1.registerRun)(program);
 (0, results_1.registerResults)(program);
+(0, tests_1.registerTests)(program);
+(0, analyze_1.registerAnalyze)(program);
+(0, capacity_1.registerCapacity)(program);
+(0, plan_1.registerPlan)(program);
 (0, record_1.registerRecord)(program);
+(0, schema_1.registerSchema)(program);
+(0, docs_1.registerDocs)(program);
+(0, skills_1.registerSkills)(program);
 // Small config helper so CI/dev can pin a default project or URL without env.
 const config = program.command('config').description('Read or write CLI settings');
 config
@@ -69,15 +89,23 @@ config
 async function main() {
     await program.parseAsync(process.argv);
 }
+/** A caller that asked for JSON gets JSON on the way out too — on stderr, so a
+ *  pipeline parsing stdout never has to tell output from failure. */
+function failed(message, code) {
+    if (process.argv.includes('--json')) {
+        console.error(JSON.stringify({ error: { message, code } }, null, 2));
+    }
+    else {
+        ui_1.log.error(message);
+    }
+    process.exit(code);
+}
 main().catch((err) => {
     // Expected failures print a message; anything else is a bug and keeps its stack.
-    if (err instanceof ui_1.CliError) {
-        ui_1.log.error(err.message);
-        process.exit(err.code);
-    }
-    ui_1.log.error(err.message ?? String(err));
+    if (err instanceof ui_1.CliError)
+        failed(err.message, err.code);
     if (process.env.ATLAS_DEBUG)
         console.error(err);
-    process.exit(ui_1.EXIT.ERROR);
+    failed(err.message ?? String(err), ui_1.EXIT.ERROR);
 });
 //# sourceMappingURL=cli.js.map

package/dist/commands/analyze.js

@@ -0,0 +1,118 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerAnalyze = registerAnalyze;
+const cli_table3_1 = __importDefault(require("cli-table3"));
+const chalk_1 = __importDefault(require("chalk"));
+const api_1 = require("../api");
+const ui_1 = require("../ui");
+/** Rows a human can scan; --json always carries every point. */
+const MAX_HUMAN_ROWS = 24;
+/** Keep the first, the last and an even spread between — a run is 175 buckets
+ *  at 30s, and the shape is what a person is reading the table for. */
+function sample(items, max) {
+    if (items.length <= max)
+        return items;
+    const step = (items.length - 1) / (max - 1);
+    return Array.from({ length: max }, (_, i) => items[Math.round(i * step)]);
+}
+function clock(iso) {
+    return new Date(iso).toLocaleTimeString(undefined, { hour: '2-digit', minute: '2-digit', second: '2-digit' });
+}
+function printPoints(points) {
+    const table = new cli_table3_1.default({
+        head: ['TIME', 'USERS', 'AVG MS', 'ERR%'].map(h => chalk_1.default.dim(h)),
+        colAligns: ['left', 'right', 'right', 'right'],
+        style: { head: [], border: [] },
+    });
+    for (const p of sample(points, MAX_HUMAN_ROWS)) {
+        table.push([
+            clock(p.timestamp),
+            String(p.activeUsers),
+            String(p.avgMs),
+            p.errorRate === 0 ? chalk_1.default.green('0%') : chalk_1.default.red(`${p.errorRate}%`),
+        ]);
+    }
+    console.log(table.toString());
+}
+function truncate(s, n) {
+    const one = (s ?? '').replace(/\s+/g, ' ').trim();
+    return one.length > n ? one.slice(0, n - 1) + '…' : one;
+}
+function printErrors(errors) {
+    const table = new cli_table3_1.default({
+        head: ['CODE', 'COUNT', 'SHARE', 'LABEL', 'MESSAGE'].map(h => chalk_1.default.dim(h)),
+        colAligns: ['left', 'right', 'right', 'left', 'left'],
+        style: { head: [], border: [] },
+        wordWrap: false,
+    });
+    for (const e of errors) {
+        table.push([
+            truncate(e.responseCode, 24) || chalk_1.default.dim('—'),
+            String(e.count),
+            `${e.errorPct}%`,
+            truncate(e.label, 32),
+            truncate(e.failureMessage, 60),
+        ]);
+    }
+    console.log(table.toString());
+}
+function registerAnalyze(program) {
+    program
+        .command('timeseries <testId>')
+        .description('Active users, response time and error rate in 30s buckets')
+        .option('--label <label>', 'one sampler/transaction instead of the whole test')
+        .option('--json', 'machine-readable output — every point, not a sample')
+        .action(async (testId, opts) => {
+        const api = api_1.AtlasApi.fromConfig();
+        const { points } = await api.timeseries(testId, opts.label);
+        if (opts.json) {
+            (0, ui_1.json)({ testId, label: opts.label ?? '_all', points });
+            return;
+        }
+        if (points.length === 0) {
+            throw new ui_1.CliError(`No metrics found for "${testId}".`, ui_1.EXIT.ERROR);
+        }
+        const peakUsers = Math.max(...points.map(p => p.activeUsers));
+        const peakAvg = Math.max(...points.map(p => p.avgMs));
+        printPoints(points);
+        if (points.length > MAX_HUMAN_ROWS) {
+            ui_1.log.dim(`${points.length} points, ${MAX_HUMAN_ROWS} shown — use --json for all of them.`);
+        }
+        ui_1.log.info(`peak users ${chalk_1.default.bold(String(peakUsers))}  ·  peak avg ${chalk_1.default.bold(`${peakAvg}ms`)}`);
+    });
+    program
+        .command('errors <testId>')
+        .description('Distinct error types for a run, with request and response detail')
+        .option('--label <label>', 'errors for one sampler/transaction only')
+        .option('--full', 'print the full request/response of each error')
+        .option('--json', 'machine-readable output')
+        .action(async (testId, opts) => {
+        const api = api_1.AtlasApi.fromConfig();
+        const { errors, totalErrors } = await api.errors(testId, opts.label);
+        if (opts.json) {
+            (0, ui_1.json)({ testId, label: opts.label ?? '_all', totalErrors, errors });
+            return;
+        }
+        if (errors.length === 0) {
+            ui_1.log.ok(`No errors recorded for ${testId}${opts.label ? ` on "${opts.label}"` : ''}.`);
+            return;
+        }
+        printErrors(errors);
+        ui_1.log.info(`${errors.length} distinct error type(s), ${totalErrors} occurrence(s).`);
+        if (opts.full) {
+            for (const e of errors) {
+                console.log();
+                ui_1.log.info(chalk_1.default.bold(`${e.responseCode} ${e.label}`));
+                ui_1.log.dim(e.requestUrl);
+                if (e.requestBody)
+                    ui_1.log.dim(`request: ${truncate(e.requestBody, 500)}`);
+                if (e.responseBody)
+                    ui_1.log.dim(`response: ${truncate(e.responseBody, 500)}`);
+            }
+        }
+    });
+}
+//# sourceMappingURL=analyze.js.map

package/dist/commands/capacity.js

@@ -0,0 +1,99 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerCapacity = registerCapacity;
+const cli_table3_1 = __importDefault(require("cli-table3"));
+const chalk_1 = __importDefault(require("chalk"));
+const api_1 = require("../api");
+const ui_1 = require("../ui");
+/** An agent sizing a run needs to know what it is allowed to ask for before it
+ *  asks the user. This is fleet + clusters + caps + quota in one call. */
+function printServers(servers) {
+    const table = new cli_table3_1.default({
+        head: ['SERVER', 'STATUS', 'PROVIDER', 'BUSY'].map(h => chalk_1.default.dim(h)),
+        style: { head: [], border: [] },
+    });
+    for (const s of servers) {
+        table.push([
+            s.name,
+            s.status === 'on' ? chalk_1.default.green('on') : s.status === 'off' ? chalk_1.default.dim('off') : chalk_1.default.yellow('unknown'),
+            s.provider,
+            s.jmeter_running ? chalk_1.default.yellow('running a test') : chalk_1.default.dim('free'),
+        ]);
+    }
+    console.log(table.toString());
+}
+function printClusters(clusters) {
+    const table = new cli_table3_1.default({
+        head: ['CLUSTER', 'TYPE', 'CONTROLLERS'].map(h => chalk_1.default.dim(h)),
+        style: { head: [], border: [] },
+    });
+    for (const c of clusters) {
+        const connected = `${c.connectedControllers}/${c.controllers}`;
+        table.push([
+            c.name,
+            c.provider_type,
+            c.connectedControllers > 0 ? chalk_1.default.green(connected) : chalk_1.default.red(connected),
+        ]);
+    }
+    console.log(table.toString());
+}
+function registerCapacity(program) {
+    program
+        .command('capacity')
+        .description('What this credential can run on: servers, clusters, fleet caps and quota')
+        .option('--json', 'machine-readable output')
+        .action(async (opts) => {
+        const api = api_1.AtlasApi.fromConfig();
+        const [servers, clusters] = await Promise.all([api.servers(), api.clusters()]);
+        // Caps and quota are newer than the fleet endpoints; an Atlas that predates
+        // them should still answer the main question rather than failing outright.
+        const optional = async (call) => call.catch(() => null);
+        const [fleet, quota] = await Promise.all([
+            optional(api.fleet()),
+            optional(api.quota()),
+        ]);
+        const free = servers.filter(s => !s.jmeter_running);
+        if (opts.json) {
+            (0, ui_1.json)({
+                servers,
+                clusters,
+                fleet,
+                quota,
+                available: { servers: free.length, of: servers.length },
+            });
+            return;
+        }
+        if (servers.length) {
+            printServers(servers);
+            ui_1.log.info(`${free.length} of ${servers.length} server(s) free.`);
+        }
+        else {
+            ui_1.log.warn('No fixed servers available to this credential.');
+        }
+        if (clusters.length) {
+            console.log();
+            printClusters(clusters);
+            ui_1.log.dim('Clusters allocate containers per run — size them with `atlas run --cluster <name> --units <n>`.');
+        }
+        if (fleet) {
+            console.log();
+            const cap = (used, max) => (max == null ? `${used} (no cap)` : `${used} of ${max}`);
+            ui_1.log.info(`nodes ${cap(fleet.nodes, fleet.maxNodes)}  ·  concurrent agents ${cap(fleet.agents, fleet.maxAgents)}`);
+        }
+        if (quota?.limited) {
+            const used = quota.usedHours ?? 0;
+            const limit = quota.limitHours ?? 0;
+            const line = `usage ${used}h of ${limit}h${quota.pct != null ? ` (${quota.pct}%)` : ''}`;
+            if (quota.blocked)
+                ui_1.log.error(`${line} — runs are blocked until the limit is raised or the period resets.`);
+            else if ((quota.pct ?? 0) >= 80)
+                ui_1.log.warn(line);
+            else
+                ui_1.log.info(line);
+        }
+    });
+}
+//# sourceMappingURL=capacity.js.map

package/dist/commands/docs.js

@@ -0,0 +1,57 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerDocs = registerDocs;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const chalk_1 = __importDefault(require("chalk"));
+const ui_1 = require("../ui");
+/** Written by scripts/bundle-docs.js at build time. */
+const DOCS_DIR = path_1.default.join(__dirname, '..', 'docs');
+function loadIndex() {
+    const file = path_1.default.join(DOCS_DIR, 'index.json');
+    if (!fs_1.default.existsSync(file))
+        return [];
+    try {
+        return JSON.parse(fs_1.default.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return [];
+    }
+}
+function registerDocs(program) {
+    program
+        .command('docs [topic]')
+        .description('Print the documentation for a topic (offline); no topic lists them')
+        .option('--json', 'machine-readable output')
+        .action((topic, opts) => {
+        const index = loadIndex();
+        if (index.length === 0) {
+            throw new ui_1.CliError('No documentation is bundled with this build. Read it at https://atlas.cloudbeat.io/docs', ui_1.EXIT.ERROR);
+        }
+        if (!topic) {
+            if (opts.json) {
+                (0, ui_1.json)({ topics: index });
+                return;
+            }
+            ui_1.log.info(chalk_1.default.bold('Topics'));
+            for (const t of index) {
+                console.log(`  ${chalk_1.default.cyan(t.topic.padEnd(16))}${t.summary || t.title}`);
+            }
+            ui_1.log.dim('atlas docs <topic>   ·   https://atlas.cloudbeat.io/docs');
+            return;
+        }
+        const hit = index.find(t => t.topic === topic.toLowerCase());
+        if (!hit) {
+            throw new ui_1.CliError(`No topic "${topic}". Known: ${index.map(t => t.topic).join(', ')}`, ui_1.EXIT.USAGE);
+        }
+        const body = fs_1.default.readFileSync(path_1.default.join(DOCS_DIR, `${hit.topic}.md`), 'utf8');
+        if (opts.json)
+            (0, ui_1.json)({ topic: hit.topic, title: hit.title, markdown: body });
+        else
+            console.log(body);
+    });
+}
+//# sourceMappingURL=docs.js.map