@autifyhq/aximo-cli 0.8.0 → 0.10.0

package/README.md

@@ -38,7 +38,7 @@ Want to run tests on **your own hardware** instead of the cloud? See [Device (BY
 
 ## Configuration
 
-Each credential resolves independently: the value in `$AXIMO_HOME/config.json` (written by `aximo configure`) wins, then the environment variable, then the default.
+Each credential resolves independently: the environment variable wins, then the value in `$AXIMO_HOME/config.json` (written by `aximo configure`), then the default.
 
 | Variable         | Required | Default                    | Notes                                                        |
 | ---------------- | -------- | -------------------------- | ------------------------------------------------------------ |
@@ -60,7 +60,7 @@ export AXIMO_API_KEY=your-api-key
 export AXIMO_BASE_URL=https://aximo-sbx.autify.dev   # optional, prod is the default
 ```
 
-Credentials and device registrations are **per-environment** — to switch between production and sandbox (`https://aximo-sbx.autify.dev`), re-run `aximo configure` with the other `--base-url`.
+Credentials and device registrations are **per-environment** — to switch between production and sandbox (`https://aximo-sbx.autify.dev`), re-run `aximo configure` with the other `--base-url`, or export `AXIMO_BASE_URL`/`AXIMO_API_KEY`, which override the saved config.
 
 ## Commands
 
@@ -75,8 +75,10 @@ Run `aximo <command> --help` for detailed usage. `aximo schema [command.path]` r
 | `aximo session get`          | Get session status                                             |
 | `aximo session save-as-case` | Save a finished session as a reusable test case                |
 | `aximo case create`          | Create a test case                                             |
+| `aximo case update`          | Update a test case                                             |
 | `aximo case delete`          | Delete a test case                                             |
 | `aximo plan create`          | Create a test plan                                             |
+| `aximo plan update`          | Update a test plan                                             |
 | `aximo plan add-case`        | Add a case to a plan                                           |
 | `aximo plan remove-case`     | Remove a case from a plan                                      |
 | `aximo trigger case run`     | Trigger a dashboard-created test case                          |
@@ -116,7 +118,7 @@ Mutating commands support `--json '<raw body>'` for direct OpenAPI payloads and
 aximo health check
 ```
 
-Returns `{ok: true, data: {status: "ok"}}` when the API is reachable and your API key is valid.
+Returns `{ok: true, data: {status: "ok", auth: "ok"}}` when the API is reachable and your API key is valid — after the health endpoint responds, the command verifies the key with an authenticated probe. If the API is reachable but the key is rejected, it exits non-zero with an `unauthorized` error envelope.
 
 ### Projects
 
@@ -150,6 +152,9 @@ aximo case create --project-id <id> --scenario <text> \
   [--format gherkin|markdown|plain_text] [--start-url <url>] \
   [--directory-id <id>] [--json '<body>'] [--dry-run]
 
+aximo case update <caseId> [--title <t>] [--description <d>] [--scenario <text>] \
+  [--type web|mobile|desktop|multi_device] [--format gherkin|markdown|plain_text] \
+  [--start-url <url>] [--json '<body>'] [--dry-run]
 aximo case delete <caseId> [--dry-run]
 
 aximo session save-as-case <sessionId> \
@@ -164,11 +169,14 @@ aximo session save-as-case <sessionId> \
 
 ```bash
 aximo plan create --project-id <id> --title <t> [--description <d>] [--json '<body>'] [--dry-run]
+aximo plan update <planId> [--title <t>] [--description <d>] \
+  [--execution-mode parallel|sequential] [--stop-on-failure true|false] \
+  [--json '<body>'] [--dry-run]
 aximo plan add-case    <planId> --case-id <caseId> [--json '<body>'] [--dry-run]
 aximo plan remove-case <planId> <caseId> [--dry-run]
 ```
 
-Build a runnable plan: `plan create` → `plan add-case` (repeat per case) → `aximo trigger plan run`. Plans created this way have API access enabled by default. Cases must belong to the same workspace as the plan.
+Build a runnable plan: `plan create` → `plan add-case` (repeat per case) → `aximo trigger plan run`. Plans created this way have API access enabled by default. Cases must belong to the same workspace as the plan. `plan update` changes only the flags you pass; `--execution-mode` sets the plan's stored Execution setting (sequential runs one case at a time in plan order) and `--stop-on-failure` marks the remaining cases as skipped after a failure, which only takes effect on sequential runs.
 
 ### Triggers (test cases and plans)
 
@@ -181,17 +189,21 @@ aximo trigger plan get  <planId> <planRunId>
 
 Triggers a test case or plan. API access must be enabled on the resource — on by default for cases/plans created via this CLI; for dashboard-created ones, enable it in the Aximo dashboard settings. `trigger case run` returns a `sessionId` you can poll; `trigger plan run` returns a per-case breakdown.
 
+`trigger plan run` accepts `--execution-mode parallel|sequential` to override the plan's stored Execution setting for that run only (omitted = plan setting; plans default to parallel). Sequential runs one case at a time in plan order, and the plan's stop-on-failure option applies only when the effective mode is sequential.
+
 ### Uploads
 
 ```bash
 aximo upload create --file-name <name> [--file-size <bytes>] [--platform ANDROID|IOS]
-aximo upload put    <uploadId> --file <path>
+aximo upload put    <uploadId> --file <path> [--url <presignedUrl>]
 aximo upload submit <uploadId>
 aximo upload get    <uploadId>
 aximo upload list   [--file-type ANDROID_APP|IOS_APP]
 ```
 
-Typical flow: `create` → `put` (sends binary to the presigned URL) → `submit` → poll `get` until `status=succeeded` → extract `uploadArn` for mobile sessions. `upload list` auto-re-uploads expired Device Farm entries.
+Typical flow: `create` → take `presignedUrl` from the output → `put <uploadId> --file app.apk --url "<presignedUrl>"` → `submit` → poll `get` until `status=succeeded` → extract `uploadArn` for mobile sessions. `upload list` auto-re-uploads expired Device Farm entries.
+
+When `presignedUrl` is an absolute S3 URL (cloud deployments) the CLI PUTs the bytes straight to it with no API-key header. When it is a relative API path (local-storage deployments) — or `--url` is omitted — the CLI falls back to an authenticated PUT through the API. If that fallback fails with HTTP 405, the deployment is S3-backed: re-run with `--url`.
 
 ### Schema
 
@@ -611,7 +623,7 @@ claude mcp add aximo -- aximo mcp
 
 VS Code (Copilot agent mode) uses the same entry under a `servers` key in `.vscode/mcp.json`.
 
-The server exposes 16 tools: 10 read-only ones for inspecting sessions and cases (`aximo_get_session_timeline` is the load-bearing one for Playwright export) plus 6 that author content (create and delete cases, create plans, save a session as a case). See the [MCP reference](./skills/aximo-cli/references/mcp.md) for per-client config paths, the full tool table, the Playwright export prompt, and a no-client smoke test.
+The server exposes 18 tools: 12 read-only ones for inspecting sessions, cases, and plan runs (`aximo_get_session_timeline` is the load-bearing one for Playwright export; `aximo_list_plan_runs` and `aximo_get_plan_run` cover run-status polling) plus 6 that author content (create and delete cases, create plans, save a session as a case). See the [MCP reference](./skills/aximo-cli/references/mcp.md) for per-client config paths, the full tool table, the Playwright export prompt, and a no-client smoke test.
 
 ## Agent Skills
 

package/dist/client.d.ts

@@ -2,7 +2,7 @@ export declare const DEFAULT_BASE_URL = "https://aximo.autify.com";
 export declare function getApiKey(): string;
 export declare function getBaseUrl(): string;
 export interface RequestOptions {
-    method?: "GET" | "POST" | "PUT" | "DELETE";
+    method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
     query?: Record<string, string | number | boolean | undefined>;
     body?: unknown;
     rawBody?: BodyInit | undefined;
@@ -15,6 +15,12 @@ export interface ClientDeps {
     fetchImpl?: typeof fetch;
 }
 export declare function request<T>(path: string, options?: RequestOptions, deps?: ClientDeps): Promise<T>;
+/**
+ * Unauthenticated PUT to an absolute URL (e.g. an S3 presigned URL). No
+ * x-api-key/Authorization header — presigned URLs carry their auth in the
+ * query string, and extra auth headers can break S3 signature validation.
+ */
+export declare function putToPresignedUrl(url: string, rawBody: BodyInit, contentType: string, deps?: ClientDeps): Promise<void>;
 export declare function requestBuffer(path: string, deps?: ClientDeps): Promise<Buffer>;
 /** Authenticated GET that streams the response body to a file (no full-buffering). */
 export declare function requestToFile(path: string, destPath: string, deps?: ClientDeps): Promise<void>;

package/dist/client.js

@@ -2,7 +2,9 @@ import { loadConfig } from "./config.js";
 export const DEFAULT_BASE_URL = "https://aximo.autify.com";
 export function getApiKey() {
     const config = loadConfig();
-    const key = config.apiKey ?? process.env["AXIMO_API_KEY"];
+    // Explicit env vars win over saved config so an exported key is never
+    // silently overridden by a stale config.json from another environment.
+    const key = process.env["AXIMO_API_KEY"] ?? config.apiKey;
     if (!key) {
         throw new Error("No API key configured. Run `aximo configure`, set AXIMO_API_KEY in your environment, or use `node --env-file=.env`.");
     }
@@ -10,7 +12,7 @@ export function getApiKey() {
 }
 export function getBaseUrl() {
     const config = loadConfig();
-    const raw = config.baseUrl ?? process.env["AXIMO_BASE_URL"] ?? DEFAULT_BASE_URL;
+    const raw = process.env["AXIMO_BASE_URL"] ?? config.baseUrl ?? DEFAULT_BASE_URL;
     return raw.replace(/\/+$/, "");
 }
 function httpError(status, message, retryAfter) {
@@ -76,6 +78,23 @@ export async function request(path, options = {}, deps = {}) {
         return undefined;
     return JSON.parse(text);
 }
+/**
+ * Unauthenticated PUT to an absolute URL (e.g. an S3 presigned URL). No
+ * x-api-key/Authorization header — presigned URLs carry their auth in the
+ * query string, and extra auth headers can break S3 signature validation.
+ */
+export async function putToPresignedUrl(url, rawBody, contentType, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const res = await fetchImpl(url, {
+        method: "PUT",
+        headers: { "Content-Type": contentType },
+        body: rawBody,
+    });
+    if (!res.ok) {
+        const retryAfter = res.headers.get("retry-after") ?? undefined;
+        throw httpError(res.status, await errorMessage(res), retryAfter);
+    }
+}
 export async function requestBuffer(path, deps = {}) {
     const apiKey = deps.apiKey ?? getApiKey();
     const baseUrl = deps.baseUrl ?? getBaseUrl();

package/dist/client.test.js

@@ -1,3 +1,6 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
 import { server, http, HttpResponse, TEST_BASE_URL } from "./test-utils.js";
 import { getApiKey, getBaseUrl, request } from "./client.js";
@@ -48,6 +51,39 @@ describe("getBaseUrl", () => {
         process.env["AXIMO_BASE_URL"] = TEST_BASE_URL;
     });
 });
+describe("credential precedence", () => {
+    let tempHome;
+    let prevHome;
+    beforeAll(() => {
+        prevHome = process.env["AXIMO_HOME"];
+        tempHome = mkdtempSync(join(tmpdir(), "aximo-client-"));
+        writeFileSync(join(tempHome, "config.json"), JSON.stringify({ apiKey: "config-key", baseUrl: "https://config.example.test" }));
+        process.env["AXIMO_HOME"] = tempHome;
+    });
+    afterAll(() => {
+        if (prevHome !== undefined)
+            process.env["AXIMO_HOME"] = prevHome;
+        else
+            delete process.env["AXIMO_HOME"];
+        rmSync(tempHome, { recursive: true, force: true });
+    });
+    it("prefers env vars over config.json values", () => {
+        expect(getApiKey()).toBe("test-key");
+        expect(getBaseUrl()).toBe(TEST_BASE_URL);
+    });
+    it("falls back to config.json when env vars are unset", () => {
+        delete process.env["AXIMO_API_KEY"];
+        delete process.env["AXIMO_BASE_URL"];
+        try {
+            expect(getApiKey()).toBe("config-key");
+            expect(getBaseUrl()).toBe("https://config.example.test");
+        }
+        finally {
+            process.env["AXIMO_API_KEY"] = "test-key";
+            process.env["AXIMO_BASE_URL"] = TEST_BASE_URL;
+        }
+    });
+});
 describe("request", () => {
     it("sends x-api-key header and parses JSON", async () => {
         let seenKey = null;

package/dist/commands/case/case.test.js

@@ -1,6 +1,7 @@
 import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
 import { HttpResponse, http, server, TEST_BASE_URL } from "../../test-utils.js";
 import { runCaseCreate } from "./create.js";
+import { runCaseUpdate } from "./update.js";
 import { runCaseDelete } from "./delete.js";
 beforeAll(() => {
     process.env["AXIMO_API_KEY"] = "test-key";
@@ -118,3 +119,64 @@ describe("runCaseDelete", () => {
         }
     });
 });
+describe("runCaseUpdate", () => {
+    it("PATCHes the provided fields and returns the updated case", async () => {
+        let seen;
+        server.use(http.patch(`${TEST_BASE_URL}/api/cases/c1`, async ({ request: req }) => {
+            seen = await req.json();
+            return HttpResponse.json({
+                success: true,
+                case: {
+                    id: "c1",
+                    projectId: "p1",
+                    type: "web",
+                    title: "Renamed case",
+                    description: null,
+                    scenario: "Given a user",
+                    format: "plain_text",
+                    startUrl: null,
+                    updatedAt: "2026-07-16T00:00:00Z",
+                },
+            });
+        }));
+        const result = await runCaseUpdate({
+            caseId: "c1",
+            title: "Renamed case",
+            scenario: "Given a user",
+            format: "plain_text",
+        });
+        expect(result.ok).toBe(true);
+        if (result.ok && !("dryRun" in result.data)) {
+            expect(result.data.case.title).toBe("Renamed case");
+        }
+        expect(seen).toMatchObject({
+            title: "Renamed case",
+            scenario: "Given a user",
+            format: "plain_text",
+        });
+    });
+    it("rejects when no fields are provided", async () => {
+        const result = await runCaseUpdate({ caseId: "c1" });
+        expect(result.ok).toBe(false);
+        if (!result.ok)
+            expect(result.error.code).toBe("validation_error");
+    });
+    it("rejects invalid type and format values client-side", async () => {
+        const badType = await runCaseUpdate({ caseId: "c1", type: "banana" });
+        expect(badType.ok).toBe(false);
+        if (!badType.ok)
+            expect(badType.error.code).toBe("validation_error");
+        const badFormat = await runCaseUpdate({ caseId: "c1", format: "klingon" });
+        expect(badFormat.ok).toBe(false);
+        if (!badFormat.ok)
+            expect(badFormat.error.code).toBe("validation_error");
+    });
+    it("--dry-run returns the PATCH request without calling the API", async () => {
+        const result = await runCaseUpdate({ caseId: "c1", title: "t", dryRun: true });
+        expect(result.ok).toBe(true);
+        if (result.ok && "dryRun" in result.data) {
+            expect(result.data.method).toBe("PATCH");
+            expect(result.data.url).toBe(`${TEST_BASE_URL}/api/cases/c1`);
+        }
+    });
+});

package/dist/commands/case/create.d.ts

@@ -23,7 +23,7 @@ declare const _default: import("citty").CommandDef<{
     };
     readonly type: {
         readonly type: "string";
-        readonly description: "web | mobile | desktop";
+        readonly description: "web | mobile | desktop | multi_device";
     };
     readonly title: {
         readonly type: "string";

package/dist/commands/case/create.js

@@ -3,7 +3,7 @@ import { request } from "../../client.js";
 import { handleApiError } from "../../errors.js";
 import { dryRunEnvelope, resolveJsonOverride } from "../../mutate.js";
 import { formatSuccess, printResult, validationError } from "../../output.js";
-import { optionalString, requireString } from "../../validate.js";
+import { optionalString, requireString, parseCaseFormat, parseCaseType } from "../../validate.js";
 export async function runCaseCreate(options, deps) {
     let body;
     const override = resolveJsonOverride(options.json);
@@ -17,10 +17,10 @@ export async function runCaseCreate(options, deps) {
             body = {
                 projectId: requireString("projectId", options.projectId),
                 scenario: requireString("scenario", options.scenario),
-                type: optionalString("type", options.type),
+                type: parseCaseType(options.type),
                 title: optionalString("title", options.title),
                 description: optionalString("description", options.description),
-                format: optionalString("format", options.format),
+                format: parseCaseFormat(options.format),
                 startUrl: optionalString("startUrl", options.startUrl),
                 directoryId: optionalString("directoryId", options.directoryId),
             };
@@ -45,7 +45,7 @@ export default defineCommand({
     args: {
         "project-id": { type: "string" },
         scenario: { type: "string" },
-        type: { type: "string", description: "web | mobile | desktop" },
+        type: { type: "string", description: "web | mobile | desktop | multi_device" },
         title: { type: "string" },
         description: { type: "string" },
         format: { type: "string", description: "gherkin | markdown | plain_text" },

package/dist/commands/case/index.js

@@ -3,6 +3,7 @@ export default defineCommand({
     meta: { name: "case", description: "Test case commands" },
     subCommands: {
         create: () => import("./create.js").then((m) => m.default),
+        update: () => import("./update.js").then((m) => m.default),
         delete: () => import("./delete.js").then((m) => m.default),
     },
 });

package/dist/commands/case/update.d.ts

@@ -0,0 +1,50 @@
+import { type ClientDeps } from "../../client.js";
+import { type DryRunResult } from "../../mutate.js";
+import type { Envelope, UpdateCaseResult } from "../../types.js";
+export interface UpdateCaseOptions {
+    caseId?: unknown;
+    title?: unknown;
+    description?: unknown;
+    scenario?: unknown;
+    type?: unknown;
+    format?: unknown;
+    startUrl?: unknown;
+    json?: unknown;
+    dryRun?: unknown;
+}
+export declare function runCaseUpdate(options: UpdateCaseOptions, deps?: ClientDeps): Promise<Envelope<UpdateCaseResult | DryRunResult>>;
+declare const _default: import("citty").CommandDef<{
+    readonly caseId: {
+        readonly type: "positional";
+        readonly required: true;
+    };
+    readonly title: {
+        readonly type: "string";
+    };
+    readonly description: {
+        readonly type: "string";
+    };
+    readonly scenario: {
+        readonly type: "string";
+    };
+    readonly type: {
+        readonly type: "string";
+        readonly description: "web | mobile | desktop | multi_device";
+    };
+    readonly format: {
+        readonly type: "string";
+        readonly description: "gherkin | markdown | plain_text";
+    };
+    readonly "start-url": {
+        readonly type: "string";
+    };
+    readonly json: {
+        readonly type: "string";
+        readonly description: "Raw JSON request body (replaces individual flags)";
+    };
+    readonly "dry-run": {
+        readonly type: "boolean";
+        readonly description: "Validate and show request without calling API";
+    };
+}>;
+export default _default;

package/dist/commands/case/update.js

@@ -0,0 +1,78 @@
+import { defineCommand } from "citty";
+import { request } from "../../client.js";
+import { handleApiError } from "../../errors.js";
+import { dryRunEnvelope, resolveJsonOverride } from "../../mutate.js";
+import { formatSuccess, printResult, validationError } from "../../output.js";
+import { optionalString, parseCaseFormat, parseCaseType, requireId } from "../../validate.js";
+export async function runCaseUpdate(options, deps) {
+    let caseId;
+    let body;
+    const override = resolveJsonOverride(options.json);
+    if (override && "error" in override)
+        return override.error;
+    try {
+        caseId = requireId("caseId", options.caseId);
+    }
+    catch (err) {
+        return validationError(err);
+    }
+    if (override) {
+        body = override.body;
+    }
+    else {
+        try {
+            body = {
+                title: optionalString("title", options.title),
+                description: optionalString("description", options.description),
+                scenario: optionalString("scenario", options.scenario),
+                type: parseCaseType(options.type),
+                format: parseCaseFormat(options.format),
+                startUrl: optionalString("startUrl", options.startUrl),
+            };
+        }
+        catch (err) {
+            return validationError(err);
+        }
+        if (Object.values(body).every((v) => v === undefined)) {
+            return validationError(new Error("at least one field to update is required"));
+        }
+    }
+    const path = `/api/cases/${encodeURIComponent(caseId)}`;
+    if (options.dryRun) {
+        return dryRunEnvelope("PATCH", path, body);
+    }
+    try {
+        const res = await request(path, { method: "PATCH", body }, deps ?? {});
+        return formatSuccess(res);
+    }
+    catch (err) {
+        return handleApiError(err);
+    }
+}
+export default defineCommand({
+    meta: { name: "update", description: "Update a test case" },
+    args: {
+        caseId: { type: "positional", required: true },
+        title: { type: "string" },
+        description: { type: "string" },
+        scenario: { type: "string" },
+        type: { type: "string", description: "web | mobile | desktop | multi_device" },
+        format: { type: "string", description: "gherkin | markdown | plain_text" },
+        "start-url": { type: "string" },
+        json: { type: "string", description: "Raw JSON request body (replaces individual flags)" },
+        "dry-run": { type: "boolean", description: "Validate and show request without calling API" },
+    },
+    async run({ args }) {
+        printResult(await runCaseUpdate({
+            caseId: args.caseId,
+            title: args.title,
+            description: args.description,
+            scenario: args.scenario,
+            type: args.type,
+            format: args.format,
+            startUrl: args["start-url"],
+            json: args.json,
+            dryRun: args["dry-run"],
+        }));
+    },
+});

package/dist/commands/device/connect.js

@@ -1,5 +1,5 @@
-import { defineCommand } from "citty";
 import { existsSync, readFileSync } from "node:fs";
+import { defineCommand } from "citty";
 import { getBaseUrl } from "../../client.js";
 import { formatError, printResult } from "../../output.js";
 import { getDeviceConfigPath } from "./paths.js";
@@ -29,10 +29,28 @@ function getRelayUrl() {
 }
 async function connectToRelay(config) {
     const { ensurePythonReady, startDesktopRemote } = await import("../../desktop-server/setup.js");
+    const { confirmProceed, formatPreflightLines, runLocalPreflight } = await import("../../desktop-server/preflight.js");
     console.log("Preparing Python environment...");
     const { pythonPath, scriptPath, agentVersion } = await ensurePythonReady();
     console.log(`Python ready: ${pythonPath}`);
     console.log(`Agent version: ${agentVersion}`);
+    // Last point where a human is present: sessions are triggered remotely, so this
+    // is the only place a failed check can offer to stop before it wastes a run.
+    const preflight = runLocalPreflight({ pythonPath, scriptPath });
+    if (preflight.kind === "ok") {
+        for (const line of formatPreflightLines(preflight.report))
+            console.log(line);
+        if (!(await confirmProceed(preflight.report))) {
+            console.log("Not connecting. Fix the checks above and run 'aximo device connect' again.");
+            return;
+        }
+    }
+    else if (preflight.kind === "error") {
+        console.log(`Desktop environment: could not be checked (${preflight.detail}).`);
+    }
+    else {
+        console.log("Desktop environment: checks unavailable for this agent version.");
+    }
     const relayUrl = getRelayUrl();
     console.log(`Starting desktop agent, relay: ${relayUrl}`);
     let remoteProcess = startDesktopRemote(pythonPath, scriptPath, {

package/dist/commands/device/doctor.d.ts

@@ -1,4 +1,5 @@
 import { type ClientDeps } from "../../client.js";
+import { type LocalPreflight } from "../../desktop-server/preflight.js";
 import type { Envelope } from "../../types.js";
 export type CheckStatus = "pass" | "warn" | "fail" | "info";
 export interface Check {
@@ -30,6 +31,7 @@ export interface AgentTlsDeps {
     probe?: (host: string, port: number, ca: Buffer) => Promise<TlsProbeResult>;
 }
 export declare function checkAgentTlsTrust(deps?: AgentTlsDeps): Promise<Check>;
+export declare function checkDesktopEnvironment(runPreflight?: () => LocalPreflight): Check[];
 export interface RunDoctorOptions {
     skipRelay?: boolean;
     skipApi?: boolean;

package/dist/commands/device/doctor.js

@@ -7,6 +7,7 @@ import { WebSocket } from "ws";
 import { getBaseUrl, request } from "../../client.js";
 import { loadConfig } from "../../config.js";
 import { readCachedManifest } from "../../desktop-server/agent-sync.js";
+import { runLocalPreflight } from "../../desktop-server/preflight.js";
 import { installedPythonTag, PYTHON_RELEASE, PYTHON_VERSION } from "../../desktop-server/setup.js";
 import { formatSuccess, printResult } from "../../output.js";
 import { readDeviceConfig } from "./device-config.js";
@@ -450,6 +451,41 @@ async function checkCurrentStatus(deviceId, deps) {
         };
     }
 }
+// The desktop agent is the only thing that can see the tester's screen, input
+// source and permissions, so doctor reports what it reports rather than
+// reimplementing the probes here.
+const MANUAL_DESKTOP_HINT = {
+    darwin: "Grant Accessibility + Screen Recording in System Settings → Privacy & Security",
+    win32: "Run from an elevated terminal if the test touches admin windows",
+    linux: "Use an X11/Xorg session; Wayland blocks capture and synthetic input",
+};
+export function checkDesktopEnvironment(runPreflight = runLocalPreflight) {
+    const result = runPreflight();
+    if (result.kind === "ok") {
+        return result.report.checks.map((check) => ({ ...check, name: `desktop: ${check.name}` }));
+    }
+    const hint = MANUAL_DESKTOP_HINT[platform()];
+    if (result.kind === "error") {
+        return [
+            {
+                name: "desktop environment",
+                status: "fail",
+                message: `the agent could not check this machine: ${result.detail}`,
+                hint: "Run: aximo device reset --deps && aximo device setup",
+            },
+        ];
+    }
+    return [
+        {
+            name: "desktop environment",
+            status: "info",
+            message: "not checked — the agent is not installed yet",
+            ...(hint
+                ? { hint: `Run: aximo device setup. ${hint}` }
+                : { hint: "Run: aximo device setup" }),
+        },
+    ];
+}
 function checkPlatformExtras() {
     const p = platform();
     if (p === "linux") {
@@ -468,16 +504,6 @@ function checkPlatformExtras() {
             },
         ];
     }
-    if (p === "darwin") {
-        return [
-            {
-                name: "macos permissions",
-                status: "info",
-                message: "Accessibility + Screen Recording must be granted manually",
-                hint: "System Settings → Privacy & Security → Accessibility / Screen Recording",
-            },
-        ];
-    }
     return [];
 }
 function logDirUsage() {
@@ -509,6 +535,7 @@ export async function runDeviceDoctor(options = {}, deps) {
     checks.push(checkPythonDeps());
     checks.push(checkAgentFiles());
     checks.push(...checkPlatformExtras());
+    checks.push(...checkDesktopEnvironment());
     checks.push(logDirUsage());
     if (!options.skipApi && checks[0]?.status !== "fail") {
         checks.push(await checkAgentUpToDate(deps));

package/dist/commands/device/doctor.test.js

@@ -3,7 +3,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from "vitest";
 import { HttpResponse, http, server, TEST_BASE_URL } from "../../test-utils.js";
-import { checkAgentTlsTrust, relayProbeUrl, runDeviceDoctor } from "./doctor.js";
+import { checkAgentTlsTrust, checkDesktopEnvironment, relayProbeUrl, runDeviceDoctor, } from "./doctor.js";
 let tempHome;
 beforeAll(() => {
     tempHome = mkdtempSync(join(tmpdir(), "aximo-doctor-"));
@@ -153,3 +153,28 @@ describe("checkAgentTlsTrust", () => {
         expect(c.message).toContain("missing file");
     });
 });
+describe("checkDesktopEnvironment", () => {
+    const REPORT = {
+        agent: { platform: "Darwin" },
+        checks: [
+            { name: "accessibility permission", status: "fail", message: "not granted" },
+            { name: "capture target", status: "info", message: "capturing the primary monitor" },
+        ],
+    };
+    it("reports what the agent found, namespaced so its checks are distinguishable", () => {
+        const checks = checkDesktopEnvironment(() => ({ kind: "ok", report: REPORT }));
+        expect(checks.map((c) => c.name)).toEqual([
+            "desktop: accessibility permission",
+            "desktop: capture target",
+        ]);
+        expect(checks[0]?.status).toBe("fail");
+    });
+    // Before `aximo device setup` there is no agent to ask, so doctor still has to
+    // say something useful rather than claim the desktop is fine.
+    it("falls back to a manual note when the agent cannot be run", () => {
+        const checks = checkDesktopEnvironment(() => ({ kind: "not-installed" }));
+        expect(checks).toHaveLength(1);
+        expect(checks[0]?.status).toBe("info");
+        expect(checks[0]?.hint ?? checks[0]?.message).toContain(process.platform === "darwin" ? "System Settings" : "aximo device setup");
+    });
+});

package/dist/commands/health/check.js

@@ -4,13 +4,25 @@ import { handleApiError } from "../../errors.js";
 import { request } from "../../client.js";
 export async function runHealthCheck(deps) {
     try {
-        // /api/health may return empty body; we normalize to { status: "ok" }
-        await request("/api/health", {}, deps ?? {});
-        return formatSuccess({ status: "ok" });
+        // Only reachability matters; skip body parsing so a non-JSON body can't fail the check.
+        await request("/api/health", { expectJson: false }, deps ?? {});
     }
     catch (err) {
         return handleApiError(err);
     }
+    try {
+        // /api/health requires no auth, so verify the API key with an authenticated probe.
+        await request("/api/organizations/projects", { expectJson: false }, deps ?? {});
+        return formatSuccess({ status: "ok", auth: "ok" });
+    }
+    catch (err) {
+        const envelope = handleApiError(err);
+        const status = err.status;
+        if (status === 401 || status === 403) {
+            envelope.error.message = `API is reachable but the API key was rejected: ${envelope.error.message}`;
+        }
+        return envelope;
+    }
 }
 export default defineCommand({
     meta: { name: "check", description: "Check Aximo API health" },