dungbeetle 0.1.2 → 0.1.3

package/README.md

@@ -3,7 +3,6 @@
 </p>
 
 # Dungbeetle
-
 <p align="center">
   <a href="https://www.npmjs.com/package/dungbeetle"><img src="https://img.shields.io/npm/v/dungbeetle" alt="npm version"></a>
   <a href="https://github.com/DungbeetleTech/client/actions/workflows/ci.yml"><img src="https://github.com/DungbeetleTech/client/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
@@ -11,7 +10,7 @@
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-FSL--1.1--ALv2-blue" alt="License: FSL-1.1-ALv2"></a>
 </p>
 
-> Web, desktop, terminal, and eventually anything — zero adoption cost and runs anywhere.
+> The regression safety net for AI agents and the humans they work for — web, desktop, terminal, anything. Zero adoption cost, runs anywhere.
 
 Dungbeetle captures your app's output as stable, reviewable JSON and produces
 **semantic diffs** instead of brittle pixel comparisons. Output is normalized (timestamps,
@@ -42,10 +41,6 @@ reference — lives at the Dungbeetle docs site:
 
 **→ <https://dungbeetle.dev>**
 
-<!-- The docs domain is a placeholder until the site goes live. When the
-     production URL is set, update this one link (and the matching pointers in
-     SUPPORT.md and CONTRIBUTING.md). -->
-
 ## Requirements
 
 - **Node.js 22.5.0 or newer.**

package/dist/brand.d.ts

@@ -1,2 +1,2 @@
 export declare const BRAND_NAME: string;
-export declare const BRAND_SUBTITLE = "Web, desktop, terminal, and eventually anything \u2014 zero adoption cost and runs anywhere.";
+export declare const BRAND_SUBTITLE = "The regression safety net for AI agents and the humans they work for \u2014 web, desktop, terminal, anything. Zero adoption cost, runs anywhere.";

package/dist/brand.js

@@ -6,4 +6,4 @@
 export const BRAND_NAME = process.env.BRAND_NAME?.trim() || "Dungbeetle";
 // Shared brand copy — one source, mirrored by the README/docs (which build
 // separately and can't import this).
-export const BRAND_SUBTITLE = "Web, desktop, terminal, and eventually anything — zero adoption cost and runs anywhere.";
+export const BRAND_SUBTITLE = "The regression safety net for AI agents and the humans they work for — web, desktop, terminal, anything. Zero adoption cost, runs anywhere.";

package/dist/cloud.d.ts

@@ -1,8 +1,13 @@
+export declare const DEFAULT_SERVER_URL = "https://dungbeetle.example.com";
 export type ClientCredentials = {
     clientId: string;
     clientSecret: string;
 };
-export type PushOptions = ClientCredentials & {
+export type AgentTokenCredentials = {
+    token: string;
+};
+export type CloudCredentials = ClientCredentials | AgentTokenCredentials;
+export type PushOptions = CloudCredentials & {
     serverUrl: string;
     reportPath: string;
     branch?: string;
@@ -22,7 +27,7 @@ export type BaselineSource = {
     snapshotPath: string;
     screenshotPath?: string;
 };
-export type PushBaselinesOptions = ClientCredentials & {
+export type PushBaselinesOptions = CloudCredentials & {
     serverUrl: string;
     baselines: BaselineSource[];
 };
@@ -40,3 +45,27 @@ export declare function pushAnonReport(options: {
     serverUrl: string;
     report: unknown;
 }): Promise<AnonPushResult>;
+export type DeviceAuthorization = {
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    verificationUriComplete: string;
+    expiresIn: number;
+    interval: number;
+};
+export type IssuedAgentToken = {
+    token: string;
+    label: string;
+    scopes: string[];
+    repository: {
+        id: string;
+        name: string;
+    };
+};
+export declare function requestDeviceCode(options: {
+    serverUrl: string;
+    label: string;
+    scopes?: string[];
+}): Promise<DeviceAuthorization>;
+export declare function waitForDeviceToken(serverUrl: string, authorization: DeviceAuthorization): Promise<IssuedAgentToken>;
+export declare function revokeAgentToken(serverUrl: string, token: string): Promise<boolean>;

package/dist/cloud.js

@@ -2,6 +2,11 @@ import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { isErrno, isRecord } from "./guards.js";
 import { BRAND_NAME } from "./brand.js";
+import { stripControlChars } from "./terminal/ansi.js";
+// The hosted Dungbeetle cloud — where every cloud command points by default.
+// `--server` / `DUNGBEETLE_SERVER_URL` exist for self-hosted deployments only;
+// users of the hosted service should never need to set them.
+export const DEFAULT_SERVER_URL = "https://dungbeetle.example.com";
 // The API major version this CLI speaks. The server echoes its own version in the
 // `Dungbeetle-Api-Version` header on every API response; a mismatch means the CLI and
 // server are incompatible, so we fail with a clear message rather than confusing
@@ -9,7 +14,10 @@ import { BRAND_NAME } from "./brand.js";
 const CLIENT_API_VERSION = 1;
 const API_BASE = `/api/v${CLIENT_API_VERSION}`;
 function assertApiVersion(response, origin) {
-    const serverVersion = response.headers.get("dungbeetle-api-version");
+    const raw = response.headers.get("dungbeetle-api-version");
+    // The header is server-controlled; strip control chars before echoing it into
+    // a terminal error (a hostile server could otherwise inject ANSI escapes).
+    const serverVersion = raw === null ? null : stripControlChars(raw).slice(0, 32);
     if (serverVersion !== null && serverVersion !== String(CLIENT_API_VERSION)) {
         throw new Error(`${BRAND_NAME} API version mismatch: this CLI speaks v${CLIENT_API_VERSION} but ${origin} ` +
             `speaks v${serverVersion}. Upgrade the CLI or the server so they match.`);
@@ -175,10 +183,11 @@ export async function pushBaselines(options) {
     }
     return uploaded;
 }
-// Client credentials are sent as HTTP Basic, so over plaintext http:// they are
-// exposed to anyone on-path. Warn loudly for non-loopback http targets; loopback
-// (local dev) stays quiet. Localhost over http is fine; a remote http server is
-// a real credential-exposure risk that deserves a heads-up.
+// Credentials (Basic pairs, agent tokens, device codes) travel in the clear
+// over plaintext http://, exposed to anyone on-path. Warn loudly for
+// non-loopback http targets; loopback (local dev) stays quiet. Localhost over
+// http is fine; a remote http server is a real credential-exposure risk that
+// deserves a heads-up.
 function warnIfInsecure(endpoint) {
     if (endpoint.protocol === "https:") {
         return;
@@ -186,7 +195,7 @@ function warnIfInsecure(endpoint) {
     const host = endpoint.hostname;
     const isLoopback = host === "localhost" || host === "127.0.0.1" || host === "::1";
     if (!isLoopback) {
-        process.stderr.write(`warning: sending client credentials over plaintext ${endpoint.protocol}// to ${endpoint.host}. ` +
+        process.stderr.write(`warning: sending credentials over plaintext ${endpoint.protocol}// to ${endpoint.host}. ` +
             `Use https:// so they are not exposed on the network.\n`);
     }
 }
@@ -219,6 +228,11 @@ function basicAuthHeader(credentials) {
     const basic = Buffer.from(`${credentials.clientId}:${credentials.clientSecret}`, "utf8").toString("base64");
     return `Basic ${basic}`;
 }
+// Client-credential pairs go out as HTTP Basic (unchanged); agent tokens as
+// Bearer. Every authenticated call funnels through here.
+function authHeader(credentials) {
+    return "token" in credentials ? `Bearer ${credentials.token}` : basicAuthHeader(credentials);
+}
 async function postJson(serverUrl, pathname, credentials, body) {
     const endpoint = new URL(pathname, serverUrl);
     warnIfInsecure(endpoint);
@@ -228,7 +242,7 @@ async function postJson(serverUrl, pathname, credentials, body) {
             method: "POST",
             headers: {
                 "content-type": "application/json",
-                authorization: basicAuthHeader(credentials)
+                authorization: authHeader(credentials)
             },
             body: JSON.stringify(body)
         });
@@ -271,6 +285,173 @@ export async function pushAnonReport(options) {
     }
     return { id: run.id, url: run.url };
 }
+// Start a device authorization: the server hands back a short user code for the
+// human and a high-entropy device code this CLI polls with.
+export async function requestDeviceCode(options) {
+    const endpoint = new URL("/auth/device/code", options.serverUrl);
+    warnIfInsecure(endpoint);
+    let response;
+    try {
+        response = await fetch(endpoint, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                label: options.label,
+                ...(options.scopes && options.scopes.length > 0 ? { scopes: options.scopes } : {})
+            })
+        });
+    }
+    catch (error) {
+        throw new Error(`Could not reach ${BRAND_NAME} server at ${endpoint.origin}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (response.status === 429) {
+        const retryAfter = retryAfterSeconds(response);
+        throw new Error(`The server is rate-limiting sign-in requests; try again ${retryAfter !== undefined ? `in ${retryAfter}s` : "shortly"}.`);
+    }
+    if (!response.ok) {
+        const detail = await safeErrorMessage(response);
+        throw new Error(`Sign-in failed (HTTP ${response.status})${detail ? `: ${detail}` : ""}.`);
+    }
+    const body = await readJsonCapped(response);
+    if (!isRecord(body) ||
+        typeof body.device_code !== "string" ||
+        typeof body.user_code !== "string" ||
+        typeof body.verification_uri !== "string" ||
+        typeof body.verification_uri_complete !== "string" ||
+        typeof body.expires_in !== "number" ||
+        typeof body.interval !== "number") {
+        throw new Error("Server response did not include a valid device authorization.");
+    }
+    return {
+        deviceCode: body.device_code,
+        userCode: body.user_code,
+        verificationUri: body.verification_uri,
+        verificationUriComplete: body.verification_uri_complete,
+        expiresIn: body.expires_in,
+        interval: body.interval
+    };
+}
+// Poll until the human approves in the browser and the token is minted.
+// Respects the server-suggested interval, backs off 5s on `slow_down` (honoring
+// a Retry-After header when present), and gives up with a clear message when
+// the authorization expires or is denied.
+export async function waitForDeviceToken(serverUrl, authorization) {
+    // Clamp server-supplied timing so a hostile or buggy server can neither make
+    // us hot-loop (interval 0) nor hang for hours (absurd interval / expiry). The
+    // whole flow is bounded to at most an hour; each poll waits 1–120s.
+    const MIN_INTERVAL_S = 1;
+    const MAX_INTERVAL_S = 120;
+    const MAX_LIFETIME_MS = 60 * 60 * 1000;
+    const clampInterval = (s) => Number.isFinite(s) ? Math.min(Math.max(s, MIN_INTERVAL_S), MAX_INTERVAL_S) : MIN_INTERVAL_S;
+    const lifetimeMs = Number.isFinite(authorization.expiresIn)
+        ? Math.min(Math.max(authorization.expiresIn, 0) * 1000, MAX_LIFETIME_MS)
+        : MAX_LIFETIME_MS;
+    const deadline = Date.now() + lifetimeMs;
+    let intervalSeconds = clampInterval(authorization.interval);
+    for (;;) {
+        // Never sleep past the deadline, so timeout is honored promptly even with a
+        // large interval.
+        const waitMs = Math.min(intervalSeconds * 1000, deadline - Date.now());
+        if (waitMs > 0) {
+            await sleep(waitMs);
+        }
+        if (Date.now() >= deadline) {
+            throw new Error("Timed out waiting for approval — the sign-in code expired. Run `dungbeetle login` to start over.");
+        }
+        const poll = await pollDeviceToken(serverUrl, authorization.deviceCode);
+        if (poll.status === "issued") {
+            return poll.issued;
+        }
+        if (poll.status === "slow_down") {
+            intervalSeconds = clampInterval(Math.max(intervalSeconds + 5, poll.retryAfterSeconds ?? 0));
+        }
+    }
+}
+async function pollDeviceToken(serverUrl, deviceCode) {
+    const endpoint = new URL("/auth/device/token", serverUrl);
+    let response;
+    try {
+        response = await fetch(endpoint, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ device_code: deviceCode }),
+            // Bound each poll so a server that never finishes the response can't hang
+            // the loop indefinitely (the deadline is only checked between polls).
+            signal: AbortSignal.timeout(30_000)
+        });
+    }
+    catch (error) {
+        throw new Error(`Could not reach ${BRAND_NAME} server at ${endpoint.origin}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (response.status === 429) {
+        return { status: "slow_down", retryAfterSeconds: retryAfterSeconds(response) };
+    }
+    if (response.ok) {
+        const body = await readJsonCapped(response);
+        if (!isRecord(body) ||
+            typeof body.token !== "string" ||
+            typeof body.label !== "string" ||
+            !Array.isArray(body.scopes) ||
+            !isRecord(body.repository) ||
+            typeof body.repository.id !== "string" ||
+            typeof body.repository.name !== "string") {
+            throw new Error("Server response did not include a valid agent token.");
+        }
+        return {
+            status: "issued",
+            issued: {
+                token: body.token,
+                label: body.label,
+                scopes: body.scopes.filter((scope) => typeof scope === "string"),
+                repository: { id: body.repository.id, name: body.repository.name }
+            }
+        };
+    }
+    const error = await safeErrorMessage(response);
+    switch (error) {
+        case "authorization_pending":
+            return { status: "pending" };
+        case "slow_down":
+            return { status: "slow_down", retryAfterSeconds: retryAfterSeconds(response) };
+        case "access_denied":
+            throw new Error("The request was denied.");
+        case "expired_token":
+            throw new Error("The sign-in code expired before it was approved. Run `dungbeetle login` to start over.");
+        default:
+            throw new Error(`Sign-in failed (HTTP ${response.status})${error ? `: ${error}` : ""}.`);
+    }
+}
+// Best-effort self-revoke of an agent token (a Bearer token may always revoke
+// itself). Returns whether the server confirmed the revocation — `logout`
+// removes the local credential either way.
+export async function revokeAgentToken(serverUrl, token) {
+    try {
+        const endpoint = new URL(`${API_BASE}/token`, serverUrl);
+        warnIfInsecure(endpoint);
+        const response = await fetch(endpoint, {
+            method: "DELETE",
+            headers: { authorization: `Bearer ${token}` }
+        });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+}
+function retryAfterSeconds(response) {
+    // headers.get() returns null when absent — Number(null) is 0, not NaN, so an
+    // explicit null check is needed to avoid reporting a bogus "0s" wait. Only the
+    // numeric (delta-seconds) form is honored; the HTTP-date form is ignored.
+    const header = response.headers.get("retry-after");
+    if (header === null) {
+        return undefined;
+    }
+    const value = Number(header);
+    return Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 // Upload one screenshot artifact as raw bytes, content-addressed by `digest`.
 async function putArtifact(options, digest, data) {
     const endpoint = new URL(`${API_BASE}/screenshots/${digest}`, options.serverUrl);
@@ -280,7 +461,7 @@ async function putArtifact(options, digest, data) {
             method: "PUT",
             headers: {
                 "content-type": "application/octet-stream",
-                authorization: basicAuthHeader(options)
+                authorization: authHeader(options)
             },
             body: new Uint8Array(data)
         });
@@ -326,7 +507,13 @@ async function readJsonCapped(response) {
 async function safeErrorMessage(response) {
     try {
         const body = (await readJsonCapped(response));
-        return isRecord(body) && typeof body.error === "string" ? body.error : undefined;
+        if (!isRecord(body) || typeof body.error !== "string") {
+            return undefined;
+        }
+        // The message is server-controlled and gets printed straight to the user's
+        // terminal, so strip control chars (ANSI-escape injection) and cap length —
+        // matching how server-supplied labels/URLs are already sanitized elsewhere.
+        return stripControlChars(body.error).slice(0, 500);
     }
     catch {
         return undefined;

package/dist/credentials.d.ts

@@ -0,0 +1,13 @@
+export type StoredCredential = {
+    token: string;
+    label?: string;
+    repository?: {
+        id: string;
+        name: string;
+    };
+    createdAt?: string;
+};
+export declare function credentialsPath(): string;
+export declare function loadStoredCredential(serverUrl: string): Promise<StoredCredential | null>;
+export declare function saveStoredCredential(serverUrl: string, entry: StoredCredential): Promise<void>;
+export declare function deleteStoredCredential(serverUrl: string): Promise<boolean>;

package/dist/credentials.js

@@ -0,0 +1,106 @@
+// Persistent agent-token store — the CLI's first on-disk credential.
+//
+// `dungbeetle login` saves the agent token minted by the device flow here, keyed
+// by server origin, so `push`/`push-baselines` work without env vars. Deliberately
+// a plain file (0600, in $XDG_CONFIG_HOME) rather than a keychain so it works
+// headless — CI containers and remote agents — exactly like `gh`/`flyctl`.
+import { randomBytes } from "node:crypto";
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { isRecord } from "./guards.js";
+// Where credentials live: $XDG_CONFIG_HOME/dungbeetle/credentials.json, falling
+// back to ~/.config. Exported so commands can tell the user where their
+// credential is stored (or was removed from).
+export function credentialsPath() {
+    const xdg = process.env.XDG_CONFIG_HOME;
+    const base = xdg && xdg.trim() !== "" ? xdg : path.join(os.homedir(), ".config");
+    return path.join(base, "dungbeetle", "credentials.json");
+}
+// Credentials are keyed by URL origin so `--server http://srv:3000/` and
+// `--server http://srv:3000` resolve to the same entry.
+function serverOrigin(serverUrl) {
+    return new URL(serverUrl).origin;
+}
+export async function loadStoredCredential(serverUrl) {
+    const store = await readStore();
+    return store.servers[serverOrigin(serverUrl)] ?? null;
+}
+export async function saveStoredCredential(serverUrl, entry) {
+    const store = await readStore();
+    store.servers[serverOrigin(serverUrl)] = entry;
+    await writeStore(store);
+}
+// Remove the entry for a server. Returns whether anything was actually removed,
+// so `logout` can distinguish "signed out" from "was never signed in".
+export async function deleteStoredCredential(serverUrl) {
+    const store = await readStore();
+    const origin = serverOrigin(serverUrl);
+    if (!(origin in store.servers)) {
+        return false;
+    }
+    delete store.servers[origin];
+    await writeStore(store);
+    return true;
+}
+// A corrupt or unreadable file must never brick the CLI: treat it as empty and
+// let the next save rewrite it. Entries without a token string are dropped.
+async function readStore() {
+    const empty = { version: 1, servers: {} };
+    let raw;
+    try {
+        raw = await readFile(credentialsPath(), "utf8");
+    }
+    catch {
+        return empty;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return empty;
+    }
+    if (!isRecord(parsed) || !isRecord(parsed.servers)) {
+        return empty;
+    }
+    const servers = {};
+    for (const [origin, entry] of Object.entries(parsed.servers)) {
+        if (!isRecord(entry) || typeof entry.token !== "string" || entry.token.length === 0) {
+            continue;
+        }
+        const repository = isRecord(entry.repository) &&
+            typeof entry.repository.id === "string" &&
+            typeof entry.repository.name === "string"
+            ? { id: entry.repository.id, name: entry.repository.name }
+            : undefined;
+        servers[origin] = {
+            token: entry.token,
+            ...(typeof entry.label === "string" ? { label: entry.label } : {}),
+            ...(repository ? { repository } : {}),
+            ...(typeof entry.createdAt === "string" ? { createdAt: entry.createdAt } : {})
+        };
+    }
+    return { version: 1, servers };
+}
+// Write atomically (tmp file + rename) so a crash mid-write can never leave a
+// truncated store, and keep the file owner-only: it holds live tokens.
+async function writeStore(store) {
+    const filePath = credentialsPath();
+    const dir = path.dirname(filePath);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const tmpPath = path.join(dir, `.credentials.${randomBytes(6).toString("hex")}.tmp`);
+    await writeFile(tmpPath, `${JSON.stringify(store, null, 2)}\n`, {
+        encoding: "utf8",
+        mode: 0o600
+    });
+    try {
+        await rename(tmpPath, filePath);
+    }
+    catch (error) {
+        await rm(tmpPath, { force: true });
+        throw error;
+    }
+    // The creation mode is masked by the process umask; chmod pins it regardless.
+    await chmod(filePath, 0o600);
+}

package/dist/index.js

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: FSL-1.1-ALv2
 // Dungbeetle CLI — Copyright 2026 DungbeetleDev. See LICENSE.
 import { mkdir, readFile, writeFile } from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
 import { createRequire } from "node:module";
 import { Command } from "commander";
@@ -13,7 +14,8 @@ import { renderConsoleReport, writeHtmlReport, writeJsonReport } from "./reporte
 import { buildScreenshotComparison, screenshotBuffer, testBaselines, updateBaselines } from "./runner.js";
 import { startManagedLifecycle } from "./lifecycle.js";
 import { Spinner } from "./tty.js";
-import { pushAnonReport, pushBaselines, pushReport } from "./cloud.js";
+import { DEFAULT_SERVER_URL, pushAnonReport, pushBaselines, pushReport, requestDeviceCode, revokeAgentToken, waitForDeviceToken } from "./cloud.js";
+import { credentialsPath, deleteStoredCredential, loadStoredCredential, saveStoredCredential } from "./credentials.js";
 import { baselinePathForTarget } from "./baselines.js";
 import { captureTarget } from "./capture.js";
 import { compareSnapshots } from "./compare.js";
@@ -191,8 +193,8 @@ program
     .command("push")
     .description(`Upload a run report to a ${BRAND_NAME} cloud server.`)
     .option("--report <path>", "Path to a JSON report produced by test/ci")
-    .option("--server <url>", "Server base URL", process.env.DUNGBEETLE_SERVER_URL)
-    .option("--client-id <id>", "Repository client id", process.env.DUNGBEETLE_CLIENT_ID)
+    .option("--server <url>", "Server base URL (set only when self-hosting)", process.env.DUNGBEETLE_SERVER_URL ?? DEFAULT_SERVER_URL)
+    .option("--client-id <id>", "Repository client id (optional after `dungbeetle login`)", process.env.DUNGBEETLE_CLIENT_ID)
     .option("--client-secret <secret>", "Repository client secret (prefer DUNGBEETLE_CLIENT_SECRET — flags leak into shell history and process lists)", process.env.DUNGBEETLE_CLIENT_SECRET)
     .option("--branch <name>", "Branch label to attach to the run")
     .option("--commit <sha>", "Commit SHA to attach to the run")
@@ -200,7 +202,7 @@ program
     if (!options.server) {
         throw new Error("Missing server URL; pass --server or set DUNGBEETLE_SERVER_URL.");
     }
-    const credentials = requireClientCredentials(options);
+    const credentials = await resolveCloudCredentials(options.server, options);
     if (!options.report) {
         throw new Error("Missing report path; pass --report <path>.");
     }
@@ -227,15 +229,15 @@ program
     .description(`Upload local baselines to a ${BRAND_NAME} cloud server (versioned).`)
     .option("--config <path>", "Config path")
     .option("--cwd <path>", "Project directory", process.cwd())
-    .option("--server <url>", "Server base URL", process.env.DUNGBEETLE_SERVER_URL)
-    .option("--client-id <id>", "Repository client id", process.env.DUNGBEETLE_CLIENT_ID)
+    .option("--server <url>", "Server base URL (set only when self-hosting)", process.env.DUNGBEETLE_SERVER_URL ?? DEFAULT_SERVER_URL)
+    .option("--client-id <id>", "Repository client id (optional after `dungbeetle login`)", process.env.DUNGBEETLE_CLIENT_ID)
     .option("--client-secret <secret>", "Repository client secret (prefer DUNGBEETLE_CLIENT_SECRET — flags leak into shell history and process lists)", process.env.DUNGBEETLE_CLIENT_SECRET)
     .option("--target <name...>", "Only upload selected target names")
     .action(async (options) => {
     if (!options.server) {
         throw new Error("Missing server URL; pass --server or set DUNGBEETLE_SERVER_URL.");
     }
-    const credentials = requireClientCredentials(options);
+    const credentials = await resolveCloudCredentials(options.server, options);
     const cwd = path.resolve(options.cwd);
     const config = await loadConfig(options.config, cwd);
     const selected = new Set(options.target ?? []);
@@ -271,6 +273,64 @@ program
         console.log(`${item.target} → v${item.version} (${note})`);
     }
 });
+program
+    .command("login")
+    .description(`Connect this machine to a ${BRAND_NAME} cloud server as an agent.`)
+    .option("--server <url>", "Server base URL (set only when self-hosting)", process.env.DUNGBEETLE_SERVER_URL ?? DEFAULT_SERVER_URL)
+    .option("--label <name>", "Agent label shown in the dashboard", `dungbeetle CLI on ${os.hostname()}`)
+    .option("--scopes <scopes...>", "Requested scopes (e.g. runs:write baselines:write)")
+    .action(async (options) => {
+    if (!options.server) {
+        throw new Error("Missing server URL; pass --server or set DUNGBEETLE_SERVER_URL.");
+    }
+    const authorization = await requestDeviceCode({
+        serverUrl: options.server,
+        label: options.label,
+        scopes: options.scopes
+    });
+    // The code and URL come from a server the user can point anywhere — strip
+    // control characters and validate the URL before echoing, like run URLs.
+    console.log(`First, copy your one-time code: ${stripControlChars(authorization.userCode)}`);
+    console.log(`Then approve this agent in your browser: ${safeUrl(authorization.verificationUriComplete)}`);
+    console.log("Waiting for approval…");
+    const issued = await waitForDeviceToken(options.server, authorization);
+    await saveStoredCredential(options.server, {
+        token: issued.token,
+        label: issued.label,
+        repository: issued.repository,
+        createdAt: new Date().toISOString()
+    });
+    console.log(`Connected as "${stripControlChars(issued.label)}" to repository ` +
+        `${stripControlChars(issued.repository.name)}.`);
+    console.log(`Scopes: ${issued.scopes.map((scope) => stripControlChars(scope)).join(" ")}`);
+    console.log(`Credential stored at ${credentialsPath()}.`);
+});
+program
+    .command("logout")
+    .description(`Revoke this machine's agent token on a ${BRAND_NAME} cloud server and forget it.`)
+    .option("--server <url>", "Server base URL (set only when self-hosting)", process.env.DUNGBEETLE_SERVER_URL ?? DEFAULT_SERVER_URL)
+    .action(async (options) => {
+    if (!options.server) {
+        throw new Error("Missing server URL; pass --server or set DUNGBEETLE_SERVER_URL.");
+    }
+    const origin = new URL(options.server).origin;
+    const stored = await loadStoredCredential(options.server);
+    if (!stored) {
+        console.log(`No stored credential for ${origin}; nothing to do.`);
+        return;
+    }
+    // Best-effort remote revoke: the local credential is removed either way, so
+    // a dead server can't keep you "logged in".
+    const revoked = await revokeAgentToken(options.server, stored.token);
+    await deleteStoredCredential(options.server);
+    if (revoked) {
+        console.log(`Revoked the agent token on ${origin} and removed it from ${credentialsPath()}.`);
+    }
+    else {
+        console.log(`Could not revoke the token on ${origin} (it may already be revoked); ` +
+            `removed it from ${credentialsPath()}.`);
+    }
+});
 program
     .command("anon")
     .description(`Capture a target and share it on a ${BRAND_NAME} cloud server — no account needed.`)
@@ -279,7 +339,7 @@ program
     .option("--screenshot", "Also capture full-page screenshots (needs a Chrome/Chromium)", false)
     .option("--cmd <command>", "Capture a terminal command's output instead of a URL")
     .option("--name <name>", "Label for the capture")
-    .option("--server <url>", "Server base URL", process.env.DUNGBEETLE_SERVER_URL)
+    .option("--server <url>", "Server base URL (set only when self-hosting)", process.env.DUNGBEETLE_SERVER_URL ?? DEFAULT_SERVER_URL)
     .action(async (url, options) => {
     if (!options.server) {
         throw new Error("Missing server URL; pass --server or set DUNGBEETLE_SERVER_URL.");
@@ -438,16 +498,26 @@ program.parseAsync(process.argv).catch((error) => {
     console.error(error instanceof Error ? error.message : String(error));
     process.exitCode = 1;
 });
-// Both upload commands need the repository's client credentials; resolve them
-// from flags or the DUNGBEETLE_CLIENT_ID / DUNGBEETLE_CLIENT_SECRET environment vars.
-function requireClientCredentials(options) {
-    if (!options.clientId) {
-        throw new Error("Missing client id; pass --client-id or set DUNGBEETLE_CLIENT_ID.");
+// Both upload commands need cloud credentials. Explicit client id/secret —
+// flags or the DUNGBEETLE_CLIENT_ID / DUNGBEETLE_CLIENT_SECRET environment
+// vars — win and go out as HTTP Basic, exactly as before. Otherwise fall back
+// to an agent token stored by `dungbeetle login` for this server (Bearer).
+async function resolveCloudCredentials(serverUrl, options) {
+    if (options.clientId || options.clientSecret) {
+        if (!options.clientId) {
+            throw new Error("Missing client id; pass --client-id or set DUNGBEETLE_CLIENT_ID.");
+        }
+        if (!options.clientSecret) {
+            throw new Error("Missing client secret; pass --client-secret or set DUNGBEETLE_CLIENT_SECRET.");
+        }
+        return { clientId: options.clientId, clientSecret: options.clientSecret };
     }
-    if (!options.clientSecret) {
-        throw new Error("Missing client secret; pass --client-secret or set DUNGBEETLE_CLIENT_SECRET.");
+    const stored = await loadStoredCredential(serverUrl);
+    if (stored) {
+        return { token: stored.token };
     }
-    return { clientId: options.clientId, clientSecret: options.clientSecret };
+    throw new Error("No cloud credentials found; run `dungbeetle login`, or pass --client-id/--client-secret " +
+        "(or set DUNGBEETLE_CLIENT_ID / DUNGBEETLE_CLIENT_SECRET).");
 }
 async function exists(filePath) {
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dungbeetle",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Web, desktop, terminal, and eventually anything — zero adoption cost and runs anywhere.",
   "type": "module",
   "engines": {