@primitivedotdev/sdk 0.18.0 → 0.20.0

package/dist/{index-CbEivn3S.d.ts → index-CDlwyxdp.d.ts}

@@ -230,10 +230,10 @@ declare function safeValidateEmailReceivedEvent(input: unknown): ValidationResul
  * specific email's raw bytes or attachment bundle from a per-deployment
  * download endpoint. It binds:
  *
- * - `email_id` — the specific email the token authorizes.
- * - `aud` — a caller-chosen audience label (e.g. the resource kind being
+ * - `email_id`: the specific email the token authorizes.
+ * - `aud`: a caller-chosen audience label (e.g. the resource kind being
  *   downloaded). Tokens minted for one audience will not verify under another.
- * - `exp` — an absolute expiration time (unix seconds).
+ * - `exp`: an absolute expiration time (unix seconds).
  *
  * Format: `<base64url(payload)>.<base64url(signature)>` where `signature`
  * is HMAC-SHA256 over the base64url-encoded payload using the shared secret.
@@ -277,9 +277,9 @@ declare function generateDownloadToken(params: GenerateDownloadTokenOptions): st
 interface VerifyDownloadTokenOptions {
   /** The token string to verify. */
   token: string;
-  /** Expected email ID — must match the token payload exactly. */
+  /** Expected email ID. Must match the token payload exactly. */
   emailId: string;
-  /** Expected audience — must match the token payload exactly. */
+  /** Expected audience. Must match the token payload exactly. */
   audience: string;
   /** Shared HMAC secret. */
   secret: string;
@@ -290,7 +290,7 @@ interface VerifyDownloadTokenOptions {
  * Result of verifying a download token.
  *
  * On failure, `error` is a short human-readable reason suitable for logs.
- * Do not surface it to untrusted clients — it may reveal which check failed.
+ * Do not surface it to untrusted clients; it may reveal which check failed.
  */
 type VerifyDownloadTokenResult = {
   valid: true;
@@ -302,7 +302,7 @@ type VerifyDownloadTokenResult = {
  * Verify a signed download token.
  *
  * Returns a discriminated-union result. The function never throws for
- * verification failures — only malformed inputs at the crypto layer would
+ * verification failures. Only malformed inputs at the crypto layer would
  * surface. Callers should check `result.valid` and log `result.error`.
  *
  * @param params - Verification inputs.

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { A as UnknownEvent, C as ParsedDataFailed, D as RawContentDownloadOnly, E as RawContent, M as WebhookAttachment, N as WebhookEvent, O as RawContentInline, S as ParsedDataComplete, T as ParsedStatus, _ as ForwardResultInline, a as DmarcPolicy, b as KnownWebhookEvent, c as EmailAnalysis, d as EventType, f as ForwardAnalysis, g as ForwardResultAttachmentSkipped, h as ForwardResultAttachmentAnalyzed, i as DkimSignature, j as ValidateEmailAuthResult, k as SpfResult, l as EmailAuth, m as ForwardResult, n as AuthVerdict, o as DmarcResult, p as ForwardOriginalSender, r as DkimResult, s as EmailAddress, t as AuthConfidence, u as EmailReceivedEvent, v as ForwardVerdict, w as ParsedError, x as ParsedData, y as ForwardVerification } from "./types-9vXGZjPd.js";
 import { a as buildReplySubject, c as parseHeaderAddress, i as buildForwardSubject, n as ReceivedEmailAddress, o as formatAddress, r as ReceivedEmailThread, s as normalizeReceivedEmail, t as ReceivedEmail } from "./received-email-DNjpq_Wt.js";
-import { a as PrimitiveApiError, c as PrimitiveClientOptions, d as SendResult, f as SendThreadInput, h as createPrimitiveClient, l as ReplyInput, n as ForwardInput, p as client, s as PrimitiveClient, u as SendInput } from "./index-CHWqMBs6.js";
-import { A as VerifyOptions, B as PAYLOAD_ERRORS, C as signStandardWebhooksPayload, D as PRIMITIVE_CONFIRMED_HEADER, E as LEGACY_SIGNATURE_HEADER, F as VerifyDownloadTokenResult, G as VERIFICATION_ERRORS, H as RAW_EMAIL_ERRORS, I as generateDownloadToken, J as WebhookPayloadErrorCode, K as WebhookErrorCode, L as verifyDownloadToken, M as verifyWebhookSignature, N as GenerateDownloadTokenOptions, O as PRIMITIVE_SIGNATURE_HEADER, P as VerifyDownloadTokenOptions, Q as WebhookVerificationErrorCode, R as safeValidateEmailReceivedEvent, S as StandardWebhooksVerifyOptions, T as LEGACY_CONFIRMED_HEADER, U as RawEmailDecodeError, V as PrimitiveWebhookError, W as RawEmailDecodeErrorCode, X as WebhookValidationErrorCode, Y as WebhookValidationError, Z as WebhookVerificationError, _ as emailReceivedEventJsonSchema, a as confirmedHeaders, b as STANDARD_WEBHOOK_TIMESTAMP_HEADER, c as handleWebhook, d as isRawIncluded, f as parseWebhookEvent, g as validateEmailAuth, h as WEBHOOK_VERSION, i as WebhookHeaders, j as signWebhookPayload, k as SignResult, l as isDownloadExpired, m as verifyRawEmailDownload, n as HandleWebhookOptions, o as decodeRawEmail, p as receive, q as WebhookPayloadError, r as ReceiveRequestOptions, s as getDownloadTimeRemaining, t as DecodeRawEmailOptions, u as isEmailReceivedEvent, v as STANDARD_WEBHOOK_ID_HEADER, w as verifyStandardWebhooksSignature, x as StandardWebhooksSignResult, y as STANDARD_WEBHOOK_SIGNATURE_HEADER, z as validateEmailReceivedEvent } from "./index-CbEivn3S.js";
+import { a as PrimitiveApiError, c as PrimitiveClientOptions, d as SendInput, f as SendResult, g as createPrimitiveClient, l as ReplyInput, m as client, n as ForwardInput, p as SendThreadInput, s as PrimitiveClient } from "./index-C6ObsYjq.js";
+import { A as VerifyOptions, B as PAYLOAD_ERRORS, C as signStandardWebhooksPayload, D as PRIMITIVE_CONFIRMED_HEADER, E as LEGACY_SIGNATURE_HEADER, F as VerifyDownloadTokenResult, G as VERIFICATION_ERRORS, H as RAW_EMAIL_ERRORS, I as generateDownloadToken, J as WebhookPayloadErrorCode, K as WebhookErrorCode, L as verifyDownloadToken, M as verifyWebhookSignature, N as GenerateDownloadTokenOptions, O as PRIMITIVE_SIGNATURE_HEADER, P as VerifyDownloadTokenOptions, Q as WebhookVerificationErrorCode, R as safeValidateEmailReceivedEvent, S as StandardWebhooksVerifyOptions, T as LEGACY_CONFIRMED_HEADER, U as RawEmailDecodeError, V as PrimitiveWebhookError, W as RawEmailDecodeErrorCode, X as WebhookValidationErrorCode, Y as WebhookValidationError, Z as WebhookVerificationError, _ as emailReceivedEventJsonSchema, a as confirmedHeaders, b as STANDARD_WEBHOOK_TIMESTAMP_HEADER, c as handleWebhook, d as isRawIncluded, f as parseWebhookEvent, g as validateEmailAuth, h as WEBHOOK_VERSION, i as WebhookHeaders, j as signWebhookPayload, k as SignResult, l as isDownloadExpired, m as verifyRawEmailDownload, n as HandleWebhookOptions, o as decodeRawEmail, p as receive, q as WebhookPayloadError, r as ReceiveRequestOptions, s as getDownloadTimeRemaining, t as DecodeRawEmailOptions, u as isEmailReceivedEvent, v as STANDARD_WEBHOOK_ID_HEADER, w as verifyStandardWebhooksSignature, x as StandardWebhooksSignResult, y as STANDARD_WEBHOOK_SIGNATURE_HEADER, z as validateEmailReceivedEvent } from "./index-CDlwyxdp.js";
 
 //#region src/index.d.ts
 declare const primitive: {

package/dist/index.js

@@ -1,6 +1,6 @@
 import { a as parseHeaderAddress, i as normalizeReceivedEmail, n as buildReplySubject, r as formatAddress, t as buildForwardSubject } from "./received-email-D6tKtWwW.js";
-import { a as client, i as PrimitiveClient, r as PrimitiveApiError, s as createPrimitiveClient } from "./api-DrAZhxS-.js";
-import { A as PRIMITIVE_CONFIRMED_HEADER, B as RAW_EMAIL_ERRORS, C as STANDARD_WEBHOOK_ID_HEADER, D as verifyStandardWebhooksSignature, E as signStandardWebhooksPayload, F as verifyDownloadToken, G as WebhookVerificationError, H as VERIFICATION_ERRORS, I as safeValidateEmailReceivedEvent, L as validateEmailReceivedEvent, M as signWebhookPayload, N as verifyWebhookSignature, O as LEGACY_CONFIRMED_HEADER, P as generateDownloadToken, R as PAYLOAD_ERRORS, S as emailReceivedEventJsonSchema, T as STANDARD_WEBHOOK_TIMESTAMP_HEADER, U as WebhookPayloadError, V as RawEmailDecodeError, W as WebhookValidationError, _ as DmarcResult, a as isDownloadExpired, b as ParsedStatus, c as parseWebhookEvent, d as WEBHOOK_VERSION, f as validateEmailAuth, g as DmarcPolicy, h as DkimResult, i as handleWebhook, j as PRIMITIVE_SIGNATURE_HEADER, k as LEGACY_SIGNATURE_HEADER, l as receive, m as AuthVerdict, n as decodeRawEmail, o as isEmailReceivedEvent, p as AuthConfidence, r as getDownloadTimeRemaining, s as isRawIncluded, t as confirmedHeaders, u as verifyRawEmailDownload, v as EventType, w as STANDARD_WEBHOOK_SIGNATURE_HEADER, x as SpfResult, y as ForwardVerdict, z as PrimitiveWebhookError } from "./webhook-zkN4wUTs.js";
+import { a as client, i as PrimitiveClient, r as PrimitiveApiError, s as createPrimitiveClient } from "./api-DNF21MDo.js";
+import { A as PRIMITIVE_CONFIRMED_HEADER, B as RAW_EMAIL_ERRORS, C as STANDARD_WEBHOOK_ID_HEADER, D as verifyStandardWebhooksSignature, E as signStandardWebhooksPayload, F as verifyDownloadToken, G as WebhookVerificationError, H as VERIFICATION_ERRORS, I as safeValidateEmailReceivedEvent, L as validateEmailReceivedEvent, M as signWebhookPayload, N as verifyWebhookSignature, O as LEGACY_CONFIRMED_HEADER, P as generateDownloadToken, R as PAYLOAD_ERRORS, S as emailReceivedEventJsonSchema, T as STANDARD_WEBHOOK_TIMESTAMP_HEADER, U as WebhookPayloadError, V as RawEmailDecodeError, W as WebhookValidationError, _ as DmarcResult, a as isDownloadExpired, b as ParsedStatus, c as parseWebhookEvent, d as WEBHOOK_VERSION, f as validateEmailAuth, g as DmarcPolicy, h as DkimResult, i as handleWebhook, j as PRIMITIVE_SIGNATURE_HEADER, k as LEGACY_SIGNATURE_HEADER, l as receive, m as AuthVerdict, n as decodeRawEmail, o as isEmailReceivedEvent, p as AuthConfidence, r as getDownloadTimeRemaining, s as isRawIncluded, t as confirmedHeaders, u as verifyRawEmailDownload, v as EventType, w as STANDARD_WEBHOOK_SIGNATURE_HEADER, x as SpfResult, y as ForwardVerdict, z as PrimitiveWebhookError } from "./webhook-rUjGV6Zu.js";
 //#region src/index.ts
 const primitive = {
 	client,

package/dist/oclif/api-command.js

@@ -1,6 +1,16 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import { Command, Errors, Flags } from "@oclif/core";
 import { operations, PrimitiveApiClient } from "../api/index.js";
+import { deleteCliCredentials, resolveCliAuth, } from "./auth.js";
+export const API_ERROR_CODES = {
+    accessDenied: "access_denied",
+    authorizationPending: "authorization_pending",
+    expiredToken: "expired_token",
+    invalidDeviceCode: "invalid_device_code",
+    notFound: "not_found",
+    slowDown: "slow_down",
+    unauthorized: "unauthorized",
+};
 function flagName(parameterName) {
     return parameterName.replace(/_/g, "-");
 }
@@ -214,6 +224,19 @@ export function readJsonBody(flags) {
     }
     return undefined;
 }
+// Read a UTF-8 text file off disk, mapping any failure to a CLIError
+// tagged with the originating flag so the user sees which path failed
+// to open. Used by hand-rolled commands that take a file-input flag
+// (e.g. functions:deploy --file).
+export function readTextFileFlag(path, flagLabel) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw cliError(`Could not read ${flagLabel} ${path}: ${detail}`);
+    }
+}
 export function extractErrorPayload(raw) {
     if (raw &&
         typeof raw === "object" &&
@@ -288,7 +311,7 @@ export function extractErrorCode(payload) {
 // `--api-key` flag; this closes that gap without having to
 // special-case every command.
 const ERROR_CODE_HINTS = {
-    unauthorized: "Hint: pass --api-key explicitly, or set PRIMITIVE_API_KEY in your environment. `primitive whoami` is the fastest way to verify a key is live.",
+    [API_ERROR_CODES.unauthorized]: "Hint: run `primitive login`, pass --api-key explicitly, or set PRIMITIVE_API_KEY in your environment. `primitive whoami` is the fastest way to verify a key is live.",
 };
 // Write a server / SDK error to stderr in the canonical envelope
 // shape, plus an actionable hint when the code is one we know how
@@ -298,10 +321,27 @@ const ERROR_CODE_HINTS = {
 export function writeErrorWithHints(payload) {
     process.stderr.write(`${formatErrorPayload(payload)}\n`);
     const code = extractErrorCode(payload);
-    if (code && ERROR_CODE_HINTS[code]) {
-        process.stderr.write(`${ERROR_CODE_HINTS[code]}\n`);
+    if (code && code in ERROR_CODE_HINTS) {
+        const hint = ERROR_CODE_HINTS[code];
+        process.stderr.write(`${hint}\n`);
     }
 }
+export function removeStaleSavedCredentialOnUnauthorized(params) {
+    if (extractErrorCode(params.payload) !== API_ERROR_CODES.unauthorized ||
+        params.auth.source !== "stored") {
+        return false;
+    }
+    const baseUrlDiffersFromSaved = params.baseUrlOverridden &&
+        params.auth.credentials !== null &&
+        params.auth.baseUrl !== params.auth.credentials.base_url;
+    if (baseUrlDiffersFromSaved) {
+        process.stderr.write("Saved Primitive CLI credentials were rejected by the overridden API base URL. The local credential was not removed; check --base-url / PRIMITIVE_API_URL, or run `primitive logout` to remove it.\n");
+        return false;
+    }
+    deleteCliCredentials(params.configDir);
+    process.stderr.write("Removed saved Primitive CLI credentials because the backing API key is no longer valid. Run `primitive login` to create a new one.\n");
+    return true;
+}
 // Format milliseconds as a short human-readable wall-clock duration.
 // Sub-second uses 2 decimal places (e.g. `0.18s`); seconds use 2
 // decimals up to 60s (`12.34s`); minute-plus uses `Mm SS.SSs`.
@@ -395,7 +435,7 @@ function bodyFieldFlag(field) {
 function buildFlags(operation) {
     const flags = {
         "api-key": Flags.string({
-            description: "Primitive API key (defaults to PRIMITIVE_API_KEY)",
+            description: "Primitive API key (defaults to PRIMITIVE_API_KEY or saved `primitive login` credentials)",
             env: "PRIMITIVE_API_KEY",
         }),
         "base-url": Flags.string({
@@ -503,13 +543,19 @@ export function createOperationCommand(operation) {
             const { flags } = await this.parse(OperationCommand);
             const parsedFlags = flags;
             await runWithTiming(parsedFlags.time === true, async () => {
-                const apiClient = new PrimitiveApiClient({
+                const baseUrlOverridden = typeof parsedFlags["base-url"] === "string";
+                const auth = resolveCliAuth({
                     apiKey: typeof parsedFlags["api-key"] === "string"
                         ? parsedFlags["api-key"]
                         : undefined,
                     baseUrl: typeof parsedFlags["base-url"] === "string"
                         ? parsedFlags["base-url"]
                         : undefined,
+                    configDir: this.config.configDir,
+                });
+                const apiClient = new PrimitiveApiClient({
+                    apiKey: auth.apiKey,
+                    baseUrl: auth.baseUrl,
                 });
                 // Two body sources, merged: explicit JSON via --body /
                 // --body-file (the base) plus per-field flags (the
@@ -564,7 +610,14 @@ export function createOperationCommand(operation) {
                     responseStyle: "fields",
                 });
                 if (result.error) {
-                    writeErrorWithHints(extractErrorPayload(result.error));
+                    const errorPayload = extractErrorPayload(result.error);
+                    writeErrorWithHints(errorPayload);
+                    removeStaleSavedCredentialOnUnauthorized({
+                        auth,
+                        baseUrlOverridden,
+                        configDir: this.config.configDir,
+                        payload: errorPayload,
+                    });
                     process.exitCode = 1;
                     return;
                 }

package/dist/oclif/auth.js

@@ -0,0 +1,168 @@
+import { randomUUID } from "node:crypto";
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { DEFAULT_BASE_URL } from "../api/index.js";
+const CREDENTIALS_FILE = "credentials.json";
+const CREDENTIALS_LOCK_DIR = "credentials.lock";
+const CREDENTIALS_LOCK_STALE_MS = 30 * 60 * 1000;
+const MALFORMED_CREDENTIALS_HINT = "Run `primitive logout` and then `primitive login`.";
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function requireString(value, key) {
+    const raw = value[key];
+    if (typeof raw !== "string" || raw.trim().length === 0) {
+        throw new Error(`Stored Primitive CLI credentials are malformed: ${key} must be a non-empty string. ${MALFORMED_CREDENTIALS_HINT}`);
+    }
+    return raw;
+}
+function parseCredentials(raw) {
+    if (!isRecord(raw)) {
+        throw new Error(`Stored Primitive CLI credentials are malformed: expected a JSON object. ${MALFORMED_CREDENTIALS_HINT}`);
+    }
+    const orgName = raw.org_name;
+    if (orgName !== null && typeof orgName !== "string") {
+        throw new Error(`Stored Primitive CLI credentials are malformed: org_name must be a string or null. ${MALFORMED_CREDENTIALS_HINT}`);
+    }
+    return {
+        api_key: requireString(raw, "api_key"),
+        key_id: requireString(raw, "key_id"),
+        key_prefix: requireString(raw, "key_prefix"),
+        org_id: requireString(raw, "org_id"),
+        org_name: orgName,
+        base_url: requireString(raw, "base_url"),
+        created_at: requireString(raw, "created_at"),
+    };
+}
+export function credentialsPath(configDir) {
+    return join(configDir, CREDENTIALS_FILE);
+}
+export function normalizeBaseUrl(baseUrl) {
+    const trimmed = baseUrl?.trim();
+    if (!trimmed)
+        return DEFAULT_BASE_URL;
+    return trimmed.replace(/\/+$/, "");
+}
+export function loadCliCredentials(configDir) {
+    const path = credentialsPath(configDir);
+    let contents;
+    try {
+        contents = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (error &&
+            typeof error === "object" &&
+            error.code === "ENOENT") {
+            return null;
+        }
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`Could not read Primitive CLI credentials: ${detail}`);
+    }
+    try {
+        return parseCredentials(JSON.parse(contents));
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            throw new Error("Stored Primitive CLI credentials are not valid JSON. Run `primitive logout` and then `primitive login`.");
+        }
+        throw error;
+    }
+}
+export function saveCliCredentials(configDir, credentials) {
+    mkdirSync(configDir, { mode: 0o700, recursive: true });
+    const path = credentialsPath(configDir);
+    const tempPath = join(configDir, `${CREDENTIALS_FILE}.${process.pid}.${randomUUID()}.tmp`);
+    try {
+        writeFileSync(tempPath, `${JSON.stringify(credentials, null, 2)}\n`, {
+            mode: 0o600,
+        });
+        chmodSync(tempPath, 0o600);
+        renameSync(tempPath, path);
+        chmodSync(path, 0o600);
+    }
+    catch (error) {
+        rmSync(tempPath, { force: true });
+        throw error;
+    }
+}
+export function deleteCliCredentials(configDir) {
+    rmSync(credentialsPath(configDir), { force: true });
+}
+function errorCode(error) {
+    return error && typeof error === "object"
+        ? error.code
+        : undefined;
+}
+function removeStaleCliCredentialsLock(lockPath, staleMs, now) {
+    try {
+        const stats = statSync(lockPath);
+        if (now() - stats.mtimeMs < staleMs)
+            return false;
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT")
+            return true;
+        throw error;
+    }
+    rmSync(lockPath, { force: true, recursive: true });
+    return true;
+}
+export function acquireCliCredentialsLock(configDir, options = {}) {
+    mkdirSync(configDir, { mode: 0o700, recursive: true });
+    const lockPath = join(configDir, CREDENTIALS_LOCK_DIR);
+    const now = options.now ?? Date.now;
+    const staleMs = options.staleMs ?? CREDENTIALS_LOCK_STALE_MS;
+    let acquired = false;
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            mkdirSync(lockPath, { mode: 0o700 });
+            acquired = true;
+            break;
+        }
+        catch (error) {
+            if (errorCode(error) !== "EEXIST")
+                throw error;
+            if (removeStaleCliCredentialsLock(lockPath, staleMs, now))
+                continue;
+            throw new Error("Another Primitive CLI credential operation is already in progress. Wait for it to finish, then retry.");
+        }
+    }
+    if (!acquired) {
+        throw new Error("Another Primitive CLI credential operation is already in progress. Wait for it to finish, then retry.");
+    }
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        rmSync(lockPath, { force: true, recursive: true });
+    };
+}
+export function resolveCliAuth(params) {
+    const apiKey = params.apiKey?.trim();
+    if (apiKey) {
+        return {
+            apiKey,
+            baseUrl: normalizeBaseUrl(params.baseUrl),
+            credentials: null,
+            source: "flag-or-env",
+        };
+    }
+    const credentials = loadCliCredentials(params.configDir);
+    if (credentials) {
+        return {
+            apiKey: credentials.api_key,
+            baseUrl: params.baseUrl
+                ? normalizeBaseUrl(params.baseUrl)
+                : credentials.base_url,
+            credentials,
+            source: "stored",
+        };
+    }
+    return {
+        apiKey: undefined,
+        baseUrl: normalizeBaseUrl(params.baseUrl),
+        credentials: null,
+        source: "none",
+    };
+}

package/dist/oclif/commands/emails-latest.js

@@ -1,7 +1,8 @@
 import { Command, Flags } from "@oclif/core";
 import { listEmails } from "../../api/generated/sdk.gen.js";
 import { PrimitiveApiClient } from "../../api/index.js";
-import { extractErrorPayload, runWithTiming, TIME_FLAG_DESCRIPTION, writeErrorWithHints, } from "../api-command.js";
+import { extractErrorPayload, removeStaleSavedCredentialOnUnauthorized, runWithTiming, TIME_FLAG_DESCRIPTION, writeErrorWithHints, } from "../api-command.js";
+import { resolveCliAuth } from "../auth.js";
 // `primitive emails:latest` is the agent-grade shortcut for "show me
 // the most recent inbound emails as something I can read at a glance."
 // `emails:list-emails` returns the full JSON envelope which is great
@@ -94,7 +95,7 @@ class EmailsLatestCommand extends Command {
     ];
     static flags = {
         "api-key": Flags.string({
-            description: "Primitive API key (defaults to PRIMITIVE_API_KEY)",
+            description: "Primitive API key (defaults to PRIMITIVE_API_KEY or saved `primitive login` credentials)",
             env: "PRIMITIVE_API_KEY",
         }),
         "base-url": Flags.string({
@@ -120,9 +121,15 @@ class EmailsLatestCommand extends Command {
     async run() {
         const { flags } = await this.parse(EmailsLatestCommand);
         await runWithTiming(flags.time, async () => {
-            const apiClient = new PrimitiveApiClient({
+            const baseUrlOverridden = flags["base-url"] !== undefined;
+            const auth = resolveCliAuth({
                 apiKey: flags["api-key"],
                 baseUrl: flags["base-url"],
+                configDir: this.config.configDir,
+            });
+            const apiClient = new PrimitiveApiClient({
+                apiKey: auth.apiKey,
+                baseUrl: auth.baseUrl,
             });
             const result = await listEmails({
                 client: apiClient.client,
@@ -130,7 +137,14 @@ class EmailsLatestCommand extends Command {
                 responseStyle: "fields",
             });
             if (result.error) {
-                writeErrorWithHints(extractErrorPayload(result.error));
+                const errorPayload = extractErrorPayload(result.error);
+                writeErrorWithHints(errorPayload);
+                removeStaleSavedCredentialOnUnauthorized({
+                    auth,
+                    baseUrlOverridden,
+                    configDir: this.config.configDir,
+                    payload: errorPayload,
+                });
                 process.exitCode = 1;
                 return;
             }

package/dist/oclif/commands/functions-deploy.js

@@ -0,0 +1,108 @@
+import { Command, Flags } from "@oclif/core";
+import { createFunction } from "../../api/generated/sdk.gen.js";
+import { PrimitiveApiClient } from "../../api/index.js";
+import { extractErrorPayload, readTextFileFlag, removeStaleSavedCredentialOnUnauthorized, runWithTiming, TIME_FLAG_DESCRIPTION, writeErrorWithHints, } from "../api-command.js";
+import { resolveCliAuth } from "../auth.js";
+// `primitive functions:deploy` is the agent-grade shortcut for
+// `functions:create-function`. The underlying operation takes `code`
+// as a string in the JSON body, which is awkward at the CLI for
+// multi-line bundles: agents would otherwise have to shell-escape an
+// entire ESM file or write a temp body.json. This command reads the
+// bundle straight off disk via --file, so the natural workflow is:
+//
+//     esbuild handler.ts --bundle --format=esm --outfile=bundle.js
+//     primitive functions:deploy --name myfn --file bundle.js
+//
+// Source maps follow the same shape via --source-map-file. They are
+// stored only on the runtime side (not in our database) so dropping
+// them later in the pipeline is fine; the CLI just hands them through.
+//
+// For full control (raw body, --raw-body JSON, etc.) the underlying
+// `functions:create-function` operation stays available.
+class FunctionsDeployCommand extends Command {
+    static description = `Deploy a new function from a bundled handler file. Agent-grade shortcut for functions:create-function.
+
+  Reads the bundle off disk (--file) instead of forcing the caller to
+  serialize the source into a JSON body. Use the underlying operation
+  \`functions:create-function\` if you need the full flag surface
+  (raw-body JSON, etc.).`;
+    static summary = "Deploy a new function from a bundled handler file";
+    static examples = [
+        "<%= config.bin %> functions:deploy --name forwarder --file ./bundle.js",
+        "<%= config.bin %> functions:deploy --name forwarder --file ./bundle.js --source-map-file ./bundle.js.map",
+    ];
+    static flags = {
+        "api-key": Flags.string({
+            description: "Primitive API key (defaults to PRIMITIVE_API_KEY or saved `primitive login` credentials)",
+            env: "PRIMITIVE_API_KEY",
+        }),
+        "base-url": Flags.string({
+            description: "API base URL (defaults to PRIMITIVE_API_URL or production)",
+            env: "PRIMITIVE_API_URL",
+        }),
+        name: Flags.string({
+            description: "Slug-style name. Lowercase letters, digits, hyphens, underscores. 1-64 chars. Must be unique within the org.",
+            required: true,
+        }),
+        file: Flags.string({
+            description: "Path to the bundled ESM handler file (single self-contained module). Loaded as the `code` body field.",
+            required: true,
+        }),
+        "source-map-file": Flags.string({
+            description: "Optional path to a source map for the bundle. Stored only on the runtime side and used to symbolicate stack traces.",
+        }),
+        time: Flags.boolean({
+            description: TIME_FLAG_DESCRIPTION,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(FunctionsDeployCommand);
+        await runWithTiming(flags.time, async () => {
+            // Reads are inside the timed block so --time captures disk I/O
+            // alongside the API call. A pathological filesystem (NFS, slow
+            // FUSE mount) showing up here is exactly the kind of latency
+            // surprise --time is meant to surface.
+            const code = readTextFileFlag(flags.file, "--file");
+            const sourceMap = flags["source-map-file"]
+                ? readTextFileFlag(flags["source-map-file"], "--source-map-file")
+                : undefined;
+            const baseUrlOverridden = flags["base-url"] !== undefined;
+            const auth = resolveCliAuth({
+                apiKey: flags["api-key"],
+                baseUrl: flags["base-url"],
+                configDir: this.config.configDir,
+            });
+            const apiClient = new PrimitiveApiClient({
+                apiKey: auth.apiKey,
+                baseUrl: auth.baseUrl,
+            });
+            const authFailureContext = {
+                auth,
+                baseUrlOverridden,
+                configDir: this.config.configDir,
+            };
+            const result = await createFunction({
+                body: {
+                    name: flags.name,
+                    code,
+                    ...(sourceMap !== undefined ? { sourceMap } : {}),
+                },
+                client: apiClient.client,
+                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 FunctionsDeployCommand;

package/dist/oclif/commands/functions-redeploy.js

@@ -0,0 +1,97 @@
+import { Command, Flags } from "@oclif/core";
+import { updateFunction } from "../../api/generated/sdk.gen.js";
+import { PrimitiveApiClient } from "../../api/index.js";
+import { extractErrorPayload, readTextFileFlag, removeStaleSavedCredentialOnUnauthorized, runWithTiming, TIME_FLAG_DESCRIPTION, writeErrorWithHints, } from "../api-command.js";
+import { resolveCliAuth } from "../auth.js";
+// `primitive functions:redeploy` is the agent-grade shortcut for
+// `functions:update-function`. Same file-reading ergonomic as
+// functions:deploy but for an existing function. Use this to push a
+// new bundle, OR to refresh secret bindings: passing the
+// previously-deployed bundle (or any equivalent file) re-runs the
+// deploy and refreshes env from the secrets table, which is how
+// secret writes go live.
+class FunctionsRedeployCommand extends Command {
+    static description = `Update or redeploy a function from a bundled handler file. Agent-grade shortcut for functions:update-function.
+
+  Use to push a new bundle OR to refresh secret bindings into the
+  running handler. The same file is fine for both: the deploy reads
+  the bindings table fresh on every call, so passing the existing
+  bundle picks up any secret writes since the last deploy.`;
+    static summary = "Redeploy a function from a bundled handler file";
+    static examples = [
+        "<%= config.bin %> functions:redeploy --id <fn-id> --file ./bundle.js",
+        "<%= config.bin %> functions:redeploy --id <fn-id> --file ./bundle.js --source-map-file ./bundle.js.map",
+    ];
+    static flags = {
+        "api-key": Flags.string({
+            description: "Primitive API key (defaults to PRIMITIVE_API_KEY or saved `primitive login` credentials)",
+            env: "PRIMITIVE_API_KEY",
+        }),
+        "base-url": Flags.string({
+            description: "API base URL (defaults to PRIMITIVE_API_URL or production)",
+            env: "PRIMITIVE_API_URL",
+        }),
+        id: Flags.string({
+            description: "Function id (UUID). The function must already exist.",
+            required: true,
+        }),
+        file: Flags.string({
+            description: "Path to the bundled ESM handler file. Loaded as the `code` body field.",
+            required: true,
+        }),
+        "source-map-file": Flags.string({
+            description: "Optional path to a source map for the bundle. Used to symbolicate stack traces in the function's logs.",
+        }),
+        time: Flags.boolean({
+            description: TIME_FLAG_DESCRIPTION,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(FunctionsRedeployCommand);
+        await runWithTiming(flags.time, async () => {
+            // Reads inside the timed block: --time captures disk I/O too,
+            // which is the latency the flag is meant to surface.
+            const code = readTextFileFlag(flags.file, "--file");
+            const sourceMap = flags["source-map-file"]
+                ? readTextFileFlag(flags["source-map-file"], "--source-map-file")
+                : undefined;
+            const baseUrlOverridden = flags["base-url"] !== undefined;
+            const auth = resolveCliAuth({
+                apiKey: flags["api-key"],
+                baseUrl: flags["base-url"],
+                configDir: this.config.configDir,
+            });
+            const apiClient = new PrimitiveApiClient({
+                apiKey: auth.apiKey,
+                baseUrl: auth.baseUrl,
+            });
+            const authFailureContext = {
+                auth,
+                baseUrlOverridden,
+                configDir: this.config.configDir,
+            };
+            const result = await updateFunction({
+                path: { id: flags.id },
+                body: {
+                    code,
+                    ...(sourceMap !== undefined ? { sourceMap } : {}),
+                },
+                client: apiClient.client,
+                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 FunctionsRedeployCommand;