@primitivedotdev/cli 0.24.0

package/dist/oclif/commands/login.js

@@ -0,0 +1,236 @@
+import { spawn } from "node:child_process";
+import { hostname } from "node:os";
+import { Command, Errors, Flags } from "@oclif/core";
+import { getAccount, PrimitiveApiClient, pollCliLogin, startCliLogin, } from "@primitivedotdev/sdk/api";
+import { API_ERROR_CODES, extractErrorCode, extractErrorPayload, removeStaleSavedCredentialOnUnauthorized, writeErrorWithHints, } from "../api-command.js";
+import { acquireCliCredentialsLock, credentialsPath, loadCliCredentials, normalizeApiBaseUrl1, normalizeApiBaseUrl2, saveCliCredentials, } from "../auth.js";
+const MAX_CLI_LOGIN_POLL_INTERVAL_SECONDS = 60;
+function cliError(message) {
+    return new Errors.CLIError(message, { exit: 1 });
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function openBrowser(url) {
+    const command = process.platform === "darwin"
+        ? "open"
+        : process.platform === "win32"
+            ? "cmd"
+            : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+    const child = spawn(command, args, { detached: true, stdio: "ignore" });
+    child.on("error", () => undefined);
+    child.unref();
+}
+function unwrapData(value) {
+    const envelope = value;
+    return envelope?.data ?? null;
+}
+function retryAfterSeconds(result) {
+    const response = result.response;
+    const raw = response?.headers.get("retry-after");
+    if (!raw)
+        return null;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+}
+export async function checkExistingLogin(params) {
+    const baseUrlOverridden = params.apiBaseUrl1 !== undefined;
+    const probeApiBaseUrl1 = baseUrlOverridden
+        ? normalizeApiBaseUrl1(params.apiBaseUrl1)
+        : params.credentials.api_base_url_1;
+    const apiClient = new PrimitiveApiClient({
+        apiKey: params.credentials.api_key,
+        apiBaseUrl1: probeApiBaseUrl1,
+    });
+    const result = await (params.checkAccount ??
+        ((client) => getAccount({
+            client: client.client,
+            responseStyle: "fields",
+        })))(apiClient);
+    if (!result.error)
+        return { status: "valid" };
+    const payload = extractErrorPayload(result.error);
+    const auth = {
+        apiKey: params.credentials.api_key,
+        apiBaseUrl1: probeApiBaseUrl1,
+        // Host-2 isn't relevant to checkExistingLogin (login is on host-1
+        // only), but the auth shape requires it. Use the default.
+        apiBaseUrl2: normalizeApiBaseUrl2(undefined),
+        credentials: params.credentials,
+        source: "stored",
+    };
+    const removed = removeStaleSavedCredentialOnUnauthorized({
+        auth,
+        baseUrlOverridden,
+        configDir: params.configDir,
+        payload,
+    });
+    if (removed)
+        return { status: "removed_stale" };
+    const code = extractErrorCode(payload);
+    return {
+        status: "blocked",
+        payload,
+        message: code === API_ERROR_CODES.unauthorized
+            ? "Saved Primitive CLI credentials were rejected. Run `primitive logout` to remove them before logging in again."
+            : "A saved Primitive CLI login exists, but the CLI could not verify whether it is still valid. Run `primitive logout` before logging in again.",
+    };
+}
+class LoginCommand extends Command {
+    static description = "Log in by opening Primitive in your browser and saving an org-scoped CLI API key locally.";
+    static summary = "Log in with browser approval";
+    static examples = [
+        "<%= config.bin %> login",
+        "<%= config.bin %> login --device-name work-laptop",
+        "<%= config.bin %> login --force",
+    ];
+    static flags = {
+        "api-base-url-1": Flags.string({
+            description: "Override the primary API base URL. Internal testing only; not documented to customers.",
+            env: "PRIMITIVE_API_BASE_URL_1",
+            hidden: true,
+        }),
+        "device-name": Flags.string({
+            description: "Device name shown in the browser approval screen",
+        }),
+        "no-browser": Flags.boolean({
+            description: "Do not attempt to open the browser automatically",
+        }),
+        force: Flags.boolean({
+            char: "f",
+            description: "Replace saved credentials without first verifying the existing login",
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(LoginCommand);
+        let releaseCredentialsLock;
+        try {
+            releaseCredentialsLock = acquireCliCredentialsLock(this.config.configDir);
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            throw cliError(detail);
+        }
+        try {
+            await this.runWithCredentialLock(flags);
+        }
+        finally {
+            releaseCredentialsLock();
+        }
+    }
+    async runWithCredentialLock(flags) {
+        const apiBaseUrl1 = normalizeApiBaseUrl1(flags["api-base-url-1"]);
+        let existing;
+        try {
+            existing = loadCliCredentials(this.config.configDir);
+        }
+        catch (error) {
+            if (!flags.force)
+                throw error;
+            const detail = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`Replacing unreadable Primitive CLI credentials because --force was set: ${detail}\n`);
+            existing = null;
+        }
+        if (existing && flags.force) {
+            process.stderr.write("Replacing saved Primitive CLI credentials after browser approval because --force was set.\n");
+        }
+        else if (existing) {
+            const existingStatus = await checkExistingLogin({
+                apiBaseUrl1: flags["api-base-url-1"],
+                configDir: this.config.configDir,
+                credentials: existing,
+            });
+            if (existingStatus.status === "removed_stale") {
+                process.stderr.write("Continuing with a new Primitive CLI login...\n");
+            }
+            else if (existingStatus.status === "blocked") {
+                writeErrorWithHints(existingStatus.payload);
+                throw cliError(existingStatus.message);
+            }
+            else {
+                const org = existing.org_name ? ` for ${existing.org_name}` : "";
+                throw cliError(`Already logged in${org}. Run \`primitive logout\` before logging in again.`);
+            }
+        }
+        const apiClient = new PrimitiveApiClient({ apiBaseUrl1 });
+        const deviceName = flags["device-name"] ?? hostname();
+        const started = await startCliLogin({
+            body: {
+                device_name: deviceName,
+            },
+            client: apiClient.client,
+            responseStyle: "fields",
+        });
+        if (started.error) {
+            writeErrorWithHints(extractErrorPayload(started.error));
+            throw cliError("Could not start Primitive CLI login.");
+        }
+        const start = unwrapData(started.data);
+        if (!start) {
+            throw cliError("Primitive API returned an empty CLI login response.");
+        }
+        process.stderr.write(`Your login code is: ${start.user_code}\n`);
+        if (!flags["no-browser"]) {
+            openBrowser(start.verification_uri_complete);
+            process.stderr.write("Opening Primitive in your browser...\n");
+        }
+        process.stderr.write(`If the browser did not open, visit: ${start.verification_uri_complete}\n`);
+        process.stderr.write("Waiting for browser approval...\n");
+        const deadline = Date.now() + start.expires_in * 1000;
+        let interval = Math.min(Math.max(1, start.interval), MAX_CLI_LOGIN_POLL_INTERVAL_SECONDS);
+        let nextPollDelay = 1;
+        while (Date.now() < deadline) {
+            await sleep(nextPollDelay * 1000);
+            nextPollDelay = interval;
+            const polled = await pollCliLogin({
+                body: { device_code: start.device_code },
+                client: apiClient.client,
+                responseStyle: "fields",
+            });
+            if (polled.data) {
+                const login = unwrapData(polled.data);
+                if (!login) {
+                    throw cliError("Primitive API returned an empty CLI poll response.");
+                }
+                saveCliCredentials(this.config.configDir, {
+                    api_key: login.api_key,
+                    api_base_url_1: apiBaseUrl1,
+                    created_at: new Date().toISOString(),
+                    key_id: login.key_id,
+                    key_prefix: login.key_prefix,
+                    org_id: login.org_id,
+                    org_name: login.org_name,
+                });
+                const org = login.org_name ? ` (${login.org_name})` : "";
+                process.stderr.write(`Logged in to org ${login.org_id}${org}.\n`);
+                process.stderr.write(`Saved credentials to ${credentialsPath(this.config.configDir)}.\n`);
+                return;
+            }
+            const payload = extractErrorPayload(polled.error);
+            const code = extractErrorCode(payload);
+            if (code === API_ERROR_CODES.authorizationPending) {
+                nextPollDelay = interval;
+                continue;
+            }
+            if (code === API_ERROR_CODES.slowDown) {
+                interval = Math.min(retryAfterSeconds(polled) ?? interval + 5, MAX_CLI_LOGIN_POLL_INTERVAL_SECONDS);
+                nextPollDelay = interval;
+                continue;
+            }
+            if (code === API_ERROR_CODES.accessDenied) {
+                throw cliError("Primitive CLI login was denied in the browser.");
+            }
+            if (code === API_ERROR_CODES.expiredToken) {
+                throw cliError("Primitive CLI login expired. Run `primitive login` again.");
+            }
+            if (code === API_ERROR_CODES.invalidDeviceCode) {
+                throw cliError("Primitive CLI login device code is invalid. Run `primitive login` again.");
+            }
+            writeErrorWithHints(payload);
+            throw cliError("Primitive CLI login failed while polling for approval.");
+        }
+        throw cliError("Primitive CLI login expired. Run `primitive login` again.");
+    }
+}
+export default LoginCommand;

package/dist/oclif/commands/logout.js

@@ -0,0 +1,87 @@
+import { Command, Errors, Flags } from "@oclif/core";
+import { cliLogout, PrimitiveApiClient } from "@primitivedotdev/sdk/api";
+import { API_ERROR_CODES, extractErrorCode, extractErrorPayload, writeErrorWithHints, } from "../api-command.js";
+import { acquireCliCredentialsLock, deleteCliCredentials, loadCliCredentials, normalizeApiBaseUrl1, } from "../auth.js";
+function cliError(message) {
+    return new Errors.CLIError(message, { exit: 1 });
+}
+function unwrapData(value) {
+    const envelope = value;
+    return envelope?.data ?? null;
+}
+class LogoutCommand extends Command {
+    static description = "Log out by revoking the saved Primitive CLI API key and deleting local credentials.";
+    static summary = "Log out and revoke the saved CLI key";
+    static examples = ["<%= config.bin %> logout"];
+    static flags = {
+        "api-base-url-1": Flags.string({
+            description: "Override the primary API base URL. Internal testing only; not documented to customers.",
+            env: "PRIMITIVE_API_BASE_URL_1",
+            hidden: true,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(LogoutCommand);
+        let releaseCredentialsLock;
+        try {
+            releaseCredentialsLock = acquireCliCredentialsLock(this.config.configDir);
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            throw cliError(detail);
+        }
+        try {
+            await this.runWithCredentialLock(flags);
+        }
+        finally {
+            releaseCredentialsLock();
+        }
+    }
+    async runWithCredentialLock(flags) {
+        let credentials;
+        try {
+            credentials = loadCliCredentials(this.config.configDir);
+        }
+        catch (error) {
+            deleteCliCredentials(this.config.configDir);
+            const detail = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`Removed unreadable Primitive CLI credentials. Backing API key was not revoked: ${detail}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        if (!credentials) {
+            throw cliError("Not logged in. Run `primitive login` to create saved CLI credentials.");
+        }
+        const apiBaseUrl1 = flags["api-base-url-1"]
+            ? normalizeApiBaseUrl1(flags["api-base-url-1"])
+            : credentials.api_base_url_1;
+        const apiClient = new PrimitiveApiClient({
+            apiKey: credentials.api_key,
+            apiBaseUrl1,
+        });
+        const result = await cliLogout({
+            body: { key_id: credentials.key_id },
+            client: apiClient.client,
+            responseStyle: "fields",
+        });
+        if (result.error) {
+            const payload = extractErrorPayload(result.error);
+            const code = extractErrorCode(payload);
+            if (code === API_ERROR_CODES.unauthorized ||
+                code === API_ERROR_CODES.notFound) {
+                deleteCliCredentials(this.config.configDir);
+                writeErrorWithHints(payload);
+                process.stderr.write("Removed saved Primitive CLI credentials because the backing API key is already unavailable.\n");
+                process.exitCode = 1;
+                return;
+            }
+            writeErrorWithHints(payload);
+            throw cliError("Could not revoke the saved Primitive CLI API key.");
+        }
+        const logout = unwrapData(result.data);
+        deleteCliCredentials(this.config.configDir);
+        const keyId = logout?.key_id ?? credentials.key_id;
+        process.stderr.write(`Logged out and revoked API key ${keyId}.\n`);
+    }
+}
+export default LogoutCommand;

package/dist/oclif/commands/send.js

@@ -0,0 +1,221 @@
+import { Command, Errors, Flags } from "@oclif/core";
+import { listDomains, PrimitiveApiClient, sendEmail, } from "@primitivedotdev/sdk/api";
+import { API_ERROR_CODES, extractErrorCode, extractErrorPayload, formatErrorPayload, removeStaleSavedCredentialOnUnauthorized, runWithTiming, TIME_FLAG_DESCRIPTION, writeErrorWithHints, } from "../api-command.js";
+import { resolveCliAuth } from "../auth.js";
+// `primitive send` is the agent-grade shortcut for the most common
+// case: send a fresh outbound email. It wraps `sending:send-email`
+// with two ergonomic defaults that the underlying operation can't
+// express through manifest-driven flag generation alone:
+//
+//   1. `--from` defaults to `agent@<first-verified-domain>` when
+//      omitted. Most agents don't know which domains their org has
+//      verified for outbound; making them list-domains first to
+//      derive a from-address is exactly the kind of email-ops cruft
+//      this command exists to hide. Customers with multiple
+//      domains, or who want a different local-part, pass --from
+//      explicitly.
+//   2. `--subject` defaults to the first non-empty line of the body
+//      (capped). Empty subjects get spam-scored, so we always emit
+//      something. Callers who want full control pass --subject.
+//
+// `--body` here is the message body (text). The full `send-email`
+// operation distinguishes `body_text` and `body_html`; this
+// shortcut keeps it simple by exposing `--body` for text and
+// `--html` for the HTML alternative. Users who need both can pass
+// both flags or fall back to `sending:send-email` for the full
+// flag list.
+//
+// Compared to `swaks` (which agents likely have in their training
+// data): this is `swaks`-shaped on purpose so an agent
+// pattern-matching from there lands in the happy path. We just
+// don't need swaks's `--server` / `--auth-*` flags because the
+// HTTPS API key is the auth and the server is implicit.
+// 200 chars is a generous cap that almost never trips on natural
+// first-line subjects (a sentence is typically <120 chars). The
+// previous 70-char limit was tight enough that legitimate one-line
+// bodies routinely produced ellipsis-truncated subjects in inbox
+// listings, e.g. `"this is the simplest possible send: agent typed
+// two flags and hit\\n e..."` from the AGX walkthrough. Real spam
+// scoring engines don't penalize subjects under ~200 chars, so 200
+// is both more useful and still well under the practical wire limit.
+const SUBJECT_MAX_LENGTH = 200;
+function deriveSubject(body) {
+    for (const line of body.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        return trimmed.length > SUBJECT_MAX_LENGTH
+            ? `${trimmed.slice(0, SUBJECT_MAX_LENGTH - 3)}...`
+            : trimmed;
+    }
+    return "Message";
+}
+function isVerifiedDomain(domain) {
+    return domain.is_active === true;
+}
+async function pickDefaultFromAddress(apiClient, authFailureContext) {
+    const result = await listDomains({
+        client: apiClient.client,
+        responseStyle: "fields",
+    });
+    if (result.error) {
+        const errorPayload = extractErrorPayload(result.error);
+        // If the underlying failure is an auth problem, don't pretend
+        // --from will fix it: the actual sendEmail call would 401 too.
+        // Surface the auth hint via writeErrorWithHints and bail with
+        // a focused message instead of the verbose "underlying error"
+        // wrapping.
+        if (extractErrorCode(errorPayload) === API_ERROR_CODES.unauthorized) {
+            writeErrorWithHints(errorPayload);
+            removeStaleSavedCredentialOnUnauthorized({
+                ...authFailureContext,
+                payload: errorPayload,
+            });
+            // exit: 1 to match the run() unauthorized path (which uses
+            // `process.exitCode = 1`). oclif's CLIError defaults to 2,
+            // so without this override the same "unauthorized" condition
+            // exits 2 when surfaced from listDomains and 1 when surfaced
+            // from sendEmail, breaking callers that branch on exit code.
+            throw new Errors.CLIError("Cannot send: API key is missing or invalid (see hint above).", { exit: 1 });
+        }
+        throw new Errors.CLIError(`Could not look up your verified domains to default --from. Pass --from explicitly. Underlying error: ${formatErrorPayload(errorPayload)}`);
+    }
+    const envelope = result.data;
+    const first = envelope?.data?.find(isVerifiedDomain);
+    if (!first) {
+        throw new Errors.CLIError("No active verified outbound domain found on this account; pass --from explicitly. To set up outbound, claim a domain via `primitive domains:add-domain` and verify it.");
+    }
+    // Local-part: "agent". Any local-part is accepted on managed
+    // *.primitive.email subdomains, so this works out of the box for
+    // the auto-issued domain pool. For customers with BYO domains
+    // and their own MX, "agent@" may or may not be a routable
+    // mailbox; if you have a specific address you want to use, pass
+    // --from explicitly.
+    return `agent@${first.domain}`;
+}
+class SendCommand extends Command {
+    static description = `Send an outbound email. Agent-grade shortcut for sending:send-email with sensible defaults.
+
+  --from defaults to agent@<your-first-verified-outbound-domain> when omitted.
+  --subject defaults to the first line of the body when omitted.
+
+  For the full flag set (custom message-id threading on the wire,
+  references arrays, etc.), use \`primitive sending:send-email\`.`;
+    static summary = "Send an email (simplified, agent-friendly)";
+    static examples = [
+        "<%= config.bin %> send --to alice@example.com --body 'Hi Alice!'",
+        "<%= config.bin %> send --to alice@example.com --from support@yourcompany.com --subject 'Quick question' --body 'Are you free Thursday?'",
+        "<%= config.bin %> send --to alice@example.com --html '<p>Hello!</p>'",
+        "<%= config.bin %> send --to alice@example.com --body 'Confirmed' --wait",
+        "<%= config.bin %> send --to inbox@your-managed-domain.primitive.email --body 'self-loop smoke test' --wait  # any *.primitive.email address routes back to the sending account; useful for proving outbound + inbound work end-to-end",
+    ];
+    static flags = {
+        "api-key": Flags.string({
+            description: "Primitive API key (defaults to PRIMITIVE_API_KEY or saved `primitive login` credentials)",
+            env: "PRIMITIVE_API_KEY",
+        }),
+        "api-base-url-1": Flags.string({
+            description: "Override the primary API base URL. Internal testing only; not documented to customers.",
+            env: "PRIMITIVE_API_BASE_URL_1",
+            hidden: true,
+        }),
+        "api-base-url-2": Flags.string({
+            description: "Override the attachments-supporting send host base URL. Internal testing only; not documented to customers.",
+            env: "PRIMITIVE_API_BASE_URL_2",
+            hidden: true,
+        }),
+        to: Flags.string({
+            description: "Recipient address (e.g. alice@example.com).",
+            required: true,
+        }),
+        from: Flags.string({
+            description: "Sender address. Defaults to agent@<your-first-verified-outbound-domain>.",
+        }),
+        subject: Flags.string({
+            description: "Subject line. Defaults to the first line of --body / --html when omitted.",
+        }),
+        body: Flags.string({
+            description: "Plain-text message body. Either --body or --html (or both) is required.",
+        }),
+        html: Flags.string({
+            description: "HTML message body. Either --body or --html (or both) is required.",
+        }),
+        "in-reply-to": Flags.string({
+            description: "Message-Id of the parent email when threading a reply on the wire. For replying to an inbound message you received, prefer `primitive sending:reply-to-email --id <inbound-id>`.",
+        }),
+        wait: Flags.boolean({
+            description: "Block until the receiving MTA returns an outcome. Without --wait, the call returns once Primitive has accepted the message for delivery.",
+        }),
+        "wait-timeout-ms": Flags.integer({
+            description: "Maximum time to wait when --wait is set. Defaults to 30000ms.",
+        }),
+        time: Flags.boolean({
+            description: TIME_FLAG_DESCRIPTION,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(SendCommand);
+        if (!flags.body && !flags.html) {
+            throw new Errors.CLIError("Either --body or --html (or both) is required.");
+        }
+        await runWithTiming(flags.time, async () => {
+            const baseUrlOverridden = flags["api-base-url-1"] !== undefined ||
+                flags["api-base-url-2"] !== undefined;
+            const auth = resolveCliAuth({
+                apiKey: flags["api-key"],
+                apiBaseUrl1: flags["api-base-url-1"],
+                apiBaseUrl2: flags["api-base-url-2"],
+                configDir: this.config.configDir,
+            });
+            const apiClient = new PrimitiveApiClient({
+                apiKey: auth.apiKey,
+                apiBaseUrl1: auth.apiBaseUrl1,
+                apiBaseUrl2: auth.apiBaseUrl2,
+            });
+            const authFailureContext = {
+                auth,
+                baseUrlOverridden,
+                configDir: this.config.configDir,
+            };
+            const from = flags.from ??
+                (await pickDefaultFromAddress(apiClient, authFailureContext));
+            const subject = flags.subject ?? (flags.body ? deriveSubject(flags.body) : "Message");
+            const result = await sendEmail({
+                body: {
+                    from,
+                    to: flags.to,
+                    subject,
+                    ...(flags.body !== undefined ? { body_text: flags.body } : {}),
+                    ...(flags.html !== undefined ? { body_html: flags.html } : {}),
+                    ...(flags["in-reply-to"] !== undefined
+                        ? { in_reply_to: flags["in-reply-to"] }
+                        : {}),
+                    ...(flags.wait !== undefined ? { wait: flags.wait } : {}),
+                    ...(flags["wait-timeout-ms"] !== undefined
+                        ? { wait_timeout_ms: flags["wait-timeout-ms"] }
+                        : {}),
+                },
+                // /send-mail goes to the attachments-supporting host. The
+                // wrapper exposes the host-2 client as _sendClient for this
+                // and any other host-2 operation that lands here. Customer
+                // SDK callers should use PrimitiveClient.send() instead so
+                // the routing stays internal.
+                client: apiClient._sendClient,
+                responseStyle: "fields",
+            });
+            if (result.error) {
+                const errorPayload = extractErrorPayload(result.error);
+                writeErrorWithHints(errorPayload);
+                removeStaleSavedCredentialOnUnauthorized({
+                    ...authFailureContext,
+                    payload: errorPayload,
+                });
+                process.exitCode = 1;
+                return;
+            }
+            const envelope = result.data;
+            this.log(JSON.stringify(envelope?.data ?? null, null, 2));
+        });
+    }
+}
+export default SendCommand;

package/dist/oclif/commands/whoami.js

@@ -0,0 +1,94 @@
+import { Command, Errors, Flags } from "@oclif/core";
+import { getAccount, PrimitiveApiClient } from "@primitivedotdev/sdk/api";
+import { extractErrorPayload, removeStaleSavedCredentialOnUnauthorized, runWithTiming, TIME_FLAG_DESCRIPTION, writeErrorWithHints, } from "../api-command.js";
+import { resolveCliAuth } from "../auth.js";
+// `primitive whoami` is the credentials smoke-test the AGX
+// walkthrough kept asking for. Before this command, a user with a
+// suspect API key had no fast way to verify "is my key live and
+// pointed at the org I expect" short of trying any other call and
+// reading a 401. That ambiguity bit two consecutive walkthroughs.
+//
+// Implementation: thin wrapper over /api/v1/account that prints
+// the account email, plan, id, and onboarding status. Any auth
+// problem surfaces as the standard error envelope, same as the
+// generated commands.
+class WhoamiCommand extends Command {
+    static description = `Print the account currently authenticated by the API key. Useful as a credentials smoke test: confirms the key is live and shows which account it belongs to.`;
+    static summary = "Print the authenticated account (credentials smoke test)";
+    static examples = [
+        "<%= config.bin %> whoami",
+        "<%= config.bin %> whoami --api-key prim_...",
+    ];
+    static flags = {
+        "api-key": Flags.string({
+            description: "Primitive API key (defaults to PRIMITIVE_API_KEY or saved `primitive login` credentials)",
+            env: "PRIMITIVE_API_KEY",
+        }),
+        "api-base-url-1": Flags.string({
+            description: "Override the primary API base URL. Internal testing only; not documented to customers.",
+            env: "PRIMITIVE_API_BASE_URL_1",
+            hidden: true,
+        }),
+        "api-base-url-2": Flags.string({
+            description: "Override the attachments-supporting send host base URL. Internal testing only; not documented to customers.",
+            env: "PRIMITIVE_API_BASE_URL_2",
+            hidden: true,
+        }),
+        time: Flags.boolean({
+            description: TIME_FLAG_DESCRIPTION,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(WhoamiCommand);
+        await runWithTiming(flags.time, async () => {
+            const baseUrlOverridden = flags["api-base-url-1"] !== undefined ||
+                flags["api-base-url-2"] !== undefined;
+            const auth = resolveCliAuth({
+                apiKey: flags["api-key"],
+                apiBaseUrl1: flags["api-base-url-1"],
+                apiBaseUrl2: flags["api-base-url-2"],
+                configDir: this.config.configDir,
+            });
+            const apiClient = new PrimitiveApiClient({
+                apiKey: auth.apiKey,
+                apiBaseUrl1: auth.apiBaseUrl1,
+                apiBaseUrl2: auth.apiBaseUrl2,
+            });
+            const result = await getAccount({
+                client: apiClient.client,
+                responseStyle: "fields",
+            });
+            if (result.error) {
+                const errorPayload = extractErrorPayload(result.error);
+                writeErrorWithHints(errorPayload);
+                removeStaleSavedCredentialOnUnauthorized({
+                    auth,
+                    baseUrlOverridden,
+                    configDir: this.config.configDir,
+                    payload: errorPayload,
+                });
+                process.exitCode = 1;
+                return;
+            }
+            const envelope = result.data;
+            const account = envelope?.data;
+            if (!account) {
+                process.stderr.write("Server returned an empty account body; this should not happen for a valid key.\n");
+                throw new Errors.CLIError("unexpected empty response");
+            }
+            // Concise human-readable summary on stderr; the full account
+            // JSON goes to stdout so a script can pipe it.
+            const onboarding = account.onboarding_completed === true
+                ? "complete"
+                : account.onboarding_step
+                    ? `in progress (step: ${account.onboarding_step})`
+                    : "incomplete";
+            process.stderr.write(`Authenticated as ${account.email}\n`);
+            process.stderr.write(`  Account id: ${account.id}\n`);
+            process.stderr.write(`  Plan:       ${account.plan}\n`);
+            process.stderr.write(`  Onboarding: ${onboarding}\n`);
+            this.log(JSON.stringify(account, null, 2));
+        });
+    }
+}
+export default WhoamiCommand;