@primitivedotdev/cli 0.24.0 → 0.25.1

package/dist/oclif/api-command.js

@@ -313,6 +313,20 @@ export function extractErrorCode(payload) {
 const ERROR_CODE_HINTS = {
     [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.",
 };
+// Network-layer hints keyed by Node's `cause.code` on a fetch failure.
+// Separate from ERROR_CODE_HINTS because these aren't API-server error
+// codes — they're the values Node sets on the underlying system call
+// that failed before the request ever hit a server. The fix is almost
+// always proxy / DNS / firewall on the caller's side, and the bare
+// envelope (which just says `ENETUNREACH`) tells the user nothing they
+// can act on. AGX walkthroughs in restrictive container environments
+// hit this enough that the hint earns the extra lookup.
+const NETWORK_ERROR_HINTS = {
+    ENETUNREACH: "Hint: the network is unreachable. If you're behind a proxy and set HTTP(S)_PROXY, re-run with NODE_USE_ENV_PROXY=1 (Node 22+ ignores those env vars by default). `primitive doctor` reports the local environment in one shot.",
+    ECONNREFUSED: "Hint: the server refused the connection. Check that your firewall allows egress to *.primitive.dev, that your PRIMITIVE_API_BASE_URL_* overrides (if any) point at a reachable host, and re-run with NODE_USE_ENV_PROXY=1 if you're behind a proxy. `primitive doctor` reports the local environment in one shot.",
+    ETIMEDOUT: "Hint: the connection timed out. Check egress rules and proxy configuration; if you're behind a proxy, re-run with NODE_USE_ENV_PROXY=1 and HTTPS_PROXY set. `primitive doctor` reports the local environment in one shot.",
+    EAI_AGAIN: "Hint: DNS lookup failed. Check /etc/resolv.conf inside containers, and try `curl -v https://www.primitive.dev/api/v1/account` to confirm the host resolves. `primitive doctor` reports the local environment in one shot.",
+};
 // Write a server / SDK error to stderr in the canonical envelope
 // shape, plus an actionable hint when the code is one we know how
 // to advise on. Replaces the bare
@@ -321,9 +335,15 @@ const ERROR_CODE_HINTS = {
 export function writeErrorWithHints(payload) {
     process.stderr.write(`${formatErrorPayload(payload)}\n`);
     const code = extractErrorCode(payload);
-    if (code && code in ERROR_CODE_HINTS) {
+    if (!code)
+        return;
+    if (code in ERROR_CODE_HINTS) {
         const hint = ERROR_CODE_HINTS[code];
         process.stderr.write(`${hint}\n`);
+        return;
+    }
+    if (code in NETWORK_ERROR_HINTS) {
+        process.stderr.write(`${NETWORK_ERROR_HINTS[code]}\n`);
     }
 }
 export function removeStaleSavedCredentialOnUnauthorized(params) {

package/dist/oclif/commands/doctor.js

@@ -0,0 +1,338 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { Command, Flags } from "@oclif/core";
+import { getAccount, listDomains, PrimitiveApiClient, } from "@primitivedotdev/sdk/api";
+import { resolveCliAuth } from "../auth.js";
+// `primitive doctor` is a one-command health check the AGX walkthrough
+// kept asking for. Before this command, a user with a misconfigured
+// environment had to triangulate across whoami, list-domains, and raw
+// network probes to figure out which piece was off. The checklist
+// below covers the four things that fail in practice: stale Node, a
+// proxy env we don't pick up, a missing/wrong API key, and an org
+// with no verified domain.
+//
+// Designed as an interactive checklist on stderr (so a piped invocation
+// keeps the structured JSON on stdout). Each check prints its label,
+// runs, and reports OK/WARN/FAIL with a one-line hint when not OK. The
+// command exits 1 if any FAIL check fires; WARN doesn't fail the run.
+const MIN_NODE_MAJOR = 22;
+function renderRow({ label, outcome }) {
+    const tag = outcome.status === "ok"
+        ? "[OK]  "
+        : outcome.status === "warn"
+            ? "[WARN]"
+            : "[FAIL]";
+    return `${tag} ${label}: ${outcome.message}`;
+}
+function checkNode() {
+    const version = process.version; // e.g. "v22.10.2"
+    const majorStr = version.replace(/^v/, "").split(".")[0];
+    const major = majorStr ? Number(majorStr) : Number.NaN;
+    if (!Number.isFinite(major)) {
+        return {
+            status: "warn",
+            message: `unrecognized version string ${version}`,
+            hint: "Ensure node --version reports a semver-shaped value.",
+        };
+    }
+    if (major < MIN_NODE_MAJOR) {
+        return {
+            status: "fail",
+            message: `${version} is below the minimum supported major (${MIN_NODE_MAJOR})`,
+            hint: `Install Node.js ${MIN_NODE_MAJOR} or newer. The CLI relies on Web Fetch APIs that are stable from ${MIN_NODE_MAJOR} on.`,
+        };
+    }
+    return { status: "ok", message: version };
+}
+function checkProxy() {
+    // Surface the four env vars Node's fetch consults when
+    // NODE_USE_ENV_PROXY=1 is set. Don't claim they're broken if absent;
+    // many environments don't need them. Surface NODE_USE_ENV_PROXY
+    // itself because Node 22+ ignores HTTP_PROXY etc. without it: a
+    // surprisingly common gotcha that turns the CLI into ENETUNREACH
+    // from inside containers and corporate networks.
+    const vars = [
+        "NODE_USE_ENV_PROXY",
+        "HTTPS_PROXY",
+        "HTTP_PROXY",
+        "NO_PROXY",
+    ];
+    const present = vars
+        .map((name) => {
+        const value = process.env[name];
+        return value && value.length > 0 ? `${name}=${value}` : null;
+    })
+        .filter((entry) => entry !== null);
+    if (present.length === 0) {
+        return { status: "ok", message: "no proxy env vars set" };
+    }
+    // Identify which specific proxy host var(s) are set so the warning
+    // names what the shell actually has, not a hardcoded string. Order
+    // is reporting-only; if both are set, both surface in the message.
+    const proxyHostVars = ["HTTPS_PROXY", "HTTP_PROXY"].filter((name) => (process.env[name] ?? "").length > 0);
+    const proxyEnabled = process.env.NODE_USE_ENV_PROXY === "1";
+    if (proxyHostVars.length > 0 && !proxyEnabled) {
+        return {
+            status: "warn",
+            message: `${present.join(", ")} (${proxyHostVars.join(" / ")} set, NODE_USE_ENV_PROXY not)`,
+            hint: "Node 22+ ignores HTTP(S)_PROXY by default. Re-run with NODE_USE_ENV_PROXY=1 if API calls fail with ENETUNREACH or ECONNREFUSED.",
+        };
+    }
+    return { status: "ok", message: present.join(", ") };
+}
+function checkApiKey(opts) {
+    if (opts.apiKey?.startsWith("prim_")) {
+        return { status: "ok", message: "provided via flag/env (prim_ prefix)" };
+    }
+    if (opts.apiKey) {
+        return {
+            status: "warn",
+            message: "provided but does not start with prim_",
+            hint: "Verify the key is a Primitive API key, not a value from another service.",
+        };
+    }
+    const credsPath = join(opts.configDir, "credentials.json");
+    if (existsSync(credsPath)) {
+        let parsed = null;
+        let parseError = null;
+        try {
+            parsed = JSON.parse(readFileSync(credsPath, "utf8"));
+        }
+        catch (error) {
+            parseError = error instanceof Error ? error.message : String(error);
+        }
+        if (parsed?.api_key) {
+            return { status: "ok", message: `loaded from ${credsPath}` };
+        }
+        if (parsed) {
+            // File parsed but had no usable api_key. Different cause than a
+            // malformed file; surface the distinction so the user knows
+            // whether to re-run login or to inspect the file by hand.
+            return {
+                status: "fail",
+                message: `${credsPath} exists but contains no api_key`,
+                hint: "Run `primitive logout` to clear it, then `primitive login` to recreate.",
+            };
+        }
+        return {
+            status: "fail",
+            message: `${credsPath} exists but is unreadable or malformed${parseError ? ` (${parseError})` : ""}`,
+            hint: "Run `primitive logout` to clear it, then `primitive login` to recreate.",
+        };
+    }
+    return {
+        status: "fail",
+        message: "no API key found",
+        hint: "Run `primitive login`, pass --api-key explicitly, or export PRIMITIVE_API_KEY=prim_...",
+    };
+}
+async function checkAccount(opts) {
+    try {
+        const client = new PrimitiveApiClient({
+            apiKey: opts.apiKey,
+            apiBaseUrl1: opts.apiBaseUrl1,
+            apiBaseUrl2: opts.apiBaseUrl2,
+        });
+        const result = await getAccount({
+            client: client.client,
+            responseStyle: "fields",
+        });
+        // Capture once to avoid TS over-narrowing across the truthy +
+        // typeof checks; result.error can resolve to never on the third
+        // access when the generated union types collapse.
+        const apiError = result.error;
+        if (apiError) {
+            const errorBody = typeof apiError === "object" && apiError !== null
+                ? JSON.stringify(apiError).slice(0, 300)
+                : String(apiError).slice(0, 300);
+            return {
+                outcome: {
+                    status: "fail",
+                    message: `API rejected the key (${errorBody})`,
+                    hint: "Run `primitive whoami` for the full error envelope. If the key was rotated, regenerate it in the dashboard.",
+                },
+                account: null,
+            };
+        }
+        const envelope = result.data;
+        const account = envelope?.data ?? null;
+        if (!account) {
+            return {
+                outcome: {
+                    status: "fail",
+                    message: "/account returned an empty body",
+                },
+                account: null,
+            };
+        }
+        return {
+            outcome: {
+                status: "ok",
+                message: `${account.email} (plan: ${account.plan}, id: ${account.id})`,
+            },
+            account,
+        };
+    }
+    catch (error) {
+        const code = error instanceof Error &&
+            error.cause &&
+            typeof error.cause === "object" &&
+            typeof error.cause.code === "string"
+            ? error.cause.code
+            : undefined;
+        const message = error instanceof Error ? error.message : String(error);
+        const hint = code === "ENETUNREACH" ||
+            code === "ECONNREFUSED" ||
+            code === "ETIMEDOUT" ||
+            code === "EAI_AGAIN"
+            ? "Network unreachable. If you're behind a proxy, re-run with NODE_USE_ENV_PROXY=1 and HTTPS_PROXY set. If you're in a container, check that egress to *.primitive.dev is allowed."
+            : 'Inspect the error above. `curl https://www.primitive.dev/api/v1/account -H "Authorization: Bearer $PRIMITIVE_API_KEY"` is the fastest way to bisect CLI vs network.';
+        return {
+            outcome: {
+                status: "fail",
+                message: code ? `${message} (${code})` : message,
+                hint,
+            },
+            account: null,
+        };
+    }
+}
+async function checkDomains(opts) {
+    try {
+        const client = new PrimitiveApiClient({
+            apiKey: opts.apiKey,
+            apiBaseUrl1: opts.apiBaseUrl1,
+            apiBaseUrl2: opts.apiBaseUrl2,
+        });
+        const result = await listDomains({
+            client: client.client,
+            responseStyle: "fields",
+        });
+        if (result.error) {
+            return {
+                status: "warn",
+                message: "could not list domains",
+                hint: "Run `primitive domains:list-domains` for the full error envelope.",
+            };
+        }
+        const envelope = result.data;
+        const rows = envelope?.data ?? [];
+        const active = rows.filter((row) => row.is_active === true);
+        if (active.length === 0 && rows.length === 0) {
+            return {
+                status: "warn",
+                message: "no domains on this account yet",
+                hint: "A managed `*.primitive.email` subdomain is auto-issued on signup. If this is empty, complete onboarding or check the dashboard.",
+            };
+        }
+        if (active.length === 0) {
+            return {
+                status: "warn",
+                message: `${rows.length} domain(s), none active`,
+                hint: "Run `primitive domains:verify-domain --id <id>` for any domain you intend to send / receive on.",
+            };
+        }
+        return {
+            status: "ok",
+            message: `${active.length} active domain(s): ${active.map((row) => row.domain).join(", ")}`,
+        };
+    }
+    catch (error) {
+        return {
+            status: "warn",
+            message: `listDomains threw: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+class DoctorCommand extends Command {
+    static description = `Run a one-shot environment health check: Node version, proxy env, API key resolution, /account reachability, and verified-domain status. Fails fast on anything that would block other commands and prints actionable hints for each warning or failure.`;
+    static summary = "Check the local environment and live API for common problems";
+    static examples = [
+        "<%= config.bin %> doctor",
+        "<%= config.bin %> doctor --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,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(DoctorCommand);
+        const rows = [];
+        rows.push({ label: "Node version", outcome: checkNode() });
+        rows.push({ label: "Proxy env", outcome: checkProxy() });
+        const apiKeyCheck = checkApiKey({
+            apiKey: flags["api-key"],
+            configDir: this.config.configDir,
+        });
+        rows.push({ label: "API key", outcome: apiKeyCheck });
+        // Only run the live checks if we have a key to authenticate with.
+        // Reporting the network-failure case without a key would just
+        // confuse the user; the missing-key row above already covers it.
+        if (apiKeyCheck.status !== "fail") {
+            const auth = resolveCliAuth({
+                apiKey: flags["api-key"],
+                apiBaseUrl1: flags["api-base-url-1"],
+                apiBaseUrl2: flags["api-base-url-2"],
+                configDir: this.config.configDir,
+            });
+            // resolveCliAuth's apiKey is typed as string | undefined; we
+            // narrowed the failure case via apiKeyCheck above, so the
+            // undefined branch shouldn't fire in practice. Skip the live
+            // checks defensively rather than passing "" to the API.
+            if (auth.apiKey !== undefined) {
+                const accountCheck = await checkAccount({
+                    apiKey: auth.apiKey,
+                    apiBaseUrl1: auth.apiBaseUrl1,
+                    apiBaseUrl2: auth.apiBaseUrl2,
+                });
+                rows.push({ label: "API auth", outcome: accountCheck.outcome });
+                if (accountCheck.outcome.status === "ok") {
+                    const domainsOutcome = await checkDomains({
+                        apiKey: auth.apiKey,
+                        apiBaseUrl1: auth.apiBaseUrl1,
+                        apiBaseUrl2: auth.apiBaseUrl2,
+                    });
+                    rows.push({ label: "Domains", outcome: domainsOutcome });
+                }
+            }
+        }
+        for (const row of rows) {
+            process.stderr.write(`${renderRow(row)}\n`);
+            if ("hint" in row.outcome && row.outcome.hint) {
+                process.stderr.write(`       hint: ${row.outcome.hint}\n`);
+            }
+        }
+        // Structured stdout for piping. Keep stderr human-readable;
+        // stdout JSON is what `primitive doctor | jq` consumers parse.
+        const summary = {
+            ok: rows.every((row) => row.outcome.status === "ok"),
+            checks: rows.map(({ label, outcome }) => ({
+                label,
+                status: outcome.status,
+                message: outcome.message,
+                ...("hint" in outcome && outcome.hint ? { hint: outcome.hint } : {}),
+            })),
+        };
+        this.log(JSON.stringify(summary, null, 2));
+        if (rows.some((row) => row.outcome.status === "fail")) {
+            process.exitCode = 1;
+        }
+    }
+}
+export default DoctorCommand;
+// Exported for unit testing. The pure helpers (formatters and the
+// proxy / node-version checks) get isolated coverage so the oclif
+// run() lifecycle doesn't have to be stood up for every case.
+export { checkApiKey, checkNode, checkProxy, renderRow };

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

@@ -18,7 +18,18 @@ import { Args, Command, Errors, Flags } from "@oclif/core";
 // the CLI's own @primitivedotdev/sdk dep range in cli-node/package.json
 // so scaffolded projects use the same SDK version the CLI was built
 // and tested against.
-const SDK_VERSION_RANGE = "^0.23.0";
+const SDK_VERSION_RANGE = "^0.25.0";
+// The CLI version range that ships in the scaffolded devDependencies.
+// Pinned separately from SDK_VERSION_RANGE because @primitivedotdev/cli
+// and @primitivedotdev/sdk are independent packages on independent
+// release cadences. Coupling them silently breaks `npm install` in
+// every scaffolded project the day we bump one without publishing the
+// other. Must include this CLI's own version: a `primitive
+// functions:init` run from CLI v1.2.3 should scaffold a project that
+// resolves at least v1.2.3, so the user does not silently downgrade
+// the bin under themselves. The lockstep test in functions-init.test.ts
+// enforces that invariant.
+const CLI_VERSION_RANGE = "^0.25.0";
 // esbuild version range. Pinned to the latest stable major used
 // elsewhere in the Primitive codebase for bundling Workers-style
 // handlers. Caret range so patch fixes flow in automatically.
@@ -40,24 +51,58 @@ export function renderHandler() {
     return `// env.PRIMITIVE_API_KEY is auto-injected by the Primitive Functions runtime.
 import { createPrimitiveClient } from "@primitivedotdev/sdk/api";
 
+interface EmailReceivedEvent {
+  event: string;
+  email: {
+    headers: { from?: string; subject?: string };
+  };
+}
+
 export default {
   async fetch(
     req: Request,
     env: { PRIMITIVE_API_KEY: string },
   ): Promise<Response> {
-    const event = (await req.json()) as {
-      email: { headers: { from?: string; subject?: string } };
-    };
-    const client = createPrimitiveClient({ apiKey: env.PRIMITIVE_API_KEY });
+    try {
+      const event = (await req.json()) as EmailReceivedEvent;
 
-    const reply = await client.send({
-      from: "you@your-domain.primitive.email",
-      to: event.email.headers.from ?? "you@your-domain.primitive.email",
-      subject: \`Re: \${event.email.headers.subject ?? ""}\`,
-      bodyText: "Got your message.",
-    });
+      // Only "email.received" exists today. Future event types will
+      // arrive with a different discriminator; return 2xx so the
+      // delivery loop does not burn its retry budget on payloads you
+      // intentionally skipped.
+      if (event.event !== "email.received") {
+        return Response.json({ ok: true, skipped: event.event });
+      }
 
-    return Response.json({ ok: true, reply });
+      const client = createPrimitiveClient({ apiKey: env.PRIMITIVE_API_KEY });
+
+      // Recipient gate
+      // https://www.primitive.dev/docs/sending#who-you-can-send-to
+      // New accounts can send to *.primitive.email addresses,
+      // verified domains, addresses that have authenticated to you,
+      // and other org-member signup emails. Sends to arbitrary
+      // external addresses return 403 recipient_not_allowed with a
+      // structured gates[] array until the recipient has authenticated
+      // to you or support has enabled the gate.
+      const reply = await client.send({
+        from: "you@your-domain.primitive.email",
+        to: event.email.headers.from ?? "you@your-domain.primitive.email",
+        subject: \`Re: \${event.email.headers.subject ?? ""}\`,
+        bodyText: "Got your message.",
+      });
+
+      return Response.json({ ok: true, reply });
+    } catch (err) {
+      // Return 2xx so the webhook delivery loop does not retry a bug
+      // it cannot fix. The function-invocation row still records the
+      // error body for debugging. Flip to a 5xx status if you want
+      // transient failures retried (e.g. a flaky external API you call).
+      console.error("handler error:", err);
+      return Response.json(
+        { ok: false, error: err instanceof Error ? err.message : String(err) },
+        { status: 200 },
+      );
+    }
   },
 };
 `;
@@ -77,6 +122,15 @@ export function renderPackageJson(name) {
             "@primitivedotdev/sdk": SDK_VERSION_RANGE,
         },
         devDependencies: {
+            // @primitivedotdev/cli ships the primitive bin. Including it as
+            // a devDep here means `node_modules/.bin/primitive` resolves to
+            // the real CLI inside the scaffolded project; otherwise the
+            // bin falls through to @primitivedotdev/sdk's deprecated CLI
+            // alias and every `npm run deploy` invocation prints the
+            // "CLI moved" stderr banner. Pinned via CLI_VERSION_RANGE, a
+            // dedicated constant so the version is decoupled from the SDK
+            // range and bumps are explicit on both ends.
+            "@primitivedotdev/cli": CLI_VERSION_RANGE,
             esbuild: ESBUILD_VERSION_RANGE,
             typescript: "^5.7.2",
         },

package/dist/oclif/index.js

@@ -1,6 +1,7 @@
 import { Args, Command, Errors } from "@oclif/core";
 import { operationManifest, } from "@primitivedotdev/sdk/openapi";
 import { createOperationCommand } from "./api-command.js";
+import DoctorCommand from "./commands/doctor.js";
 import EmailsLatestCommand from "./commands/emails-latest.js";
 import EmailsWaitCommand from "./commands/emails-wait.js";
 import EmailsWatchCommand from "./commands/emails-watch.js";
@@ -133,6 +134,13 @@ export const COMMANDS = {
     // wanting this before risking a real call against a possibly-
     // bad key.
     whoami: WhoamiCommand,
+    // `doctor` is the environment health check. Node version, proxy
+    // env, API key resolution, /account reachability, verified-domain
+    // status — every check that whoami implicitly assumes is fine.
+    // AGX walkthroughs that hit ENETUNREACH from inside containers
+    // had no single command to bisect "is the CLI / network / key /
+    // server broken"; doctor is that command.
+    doctor: DoctorCommand,
     // `emails:latest` is the inbox-triage shortcut: the most recent N
     // inbound emails as a compact text table. emails:list-emails stays
     // available for the full JSON envelope + cursor pagination.

package/oclif.manifest.json

@@ -308,6 +308,52 @@
       "summary": "Print the authenticated account (credentials smoke test)",
       "enableJsonFlag": false
     },
+    "doctor": {
+      "aliases": [],
+      "args": {},
+      "description": "Run a one-shot environment health check: Node version, proxy env, API key resolution, /account reachability, and verified-domain status. Fails fast on anything that would block other commands and prints actionable hints for each warning or failure.",
+      "examples": [
+        "<%= config.bin %> doctor",
+        "<%= config.bin %> doctor --api-key prim_..."
+      ],
+      "flags": {
+        "api-key": {
+          "description": "Primitive API key (defaults to PRIMITIVE_API_KEY or saved `primitive login` credentials)",
+          "env": "PRIMITIVE_API_KEY",
+          "name": "api-key",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "api-base-url-1": {
+          "description": "Override the primary API base URL. Internal testing only; not documented to customers.",
+          "env": "PRIMITIVE_API_BASE_URL_1",
+          "hidden": true,
+          "name": "api-base-url-1",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "api-base-url-2": {
+          "description": "Override the attachments-supporting send host base URL. Internal testing only; not documented to customers.",
+          "env": "PRIMITIVE_API_BASE_URL_2",
+          "hidden": true,
+          "name": "api-base-url-2",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "doctor",
+      "pluginAlias": "@primitivedotdev/cli",
+      "pluginName": "@primitivedotdev/cli",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Check the local environment and live API for common problems",
+      "enableJsonFlag": false
+    },
     "emails:latest": {
       "aliases": [],
       "args": {},
@@ -3565,7 +3611,7 @@
     "functions:test-function": {
       "aliases": [],
       "args": {},
-      "description": "Sends a real test email from a Primitive-controlled sender to a\nsynthetic local-part on one of the org's verified inbound\ndomains. The function fires through the normal MX delivery\npath, so reply / send-mail calls from inside the handler\nagainst the inbound's `email.id` work the same as in\nproduction. Returns immediately after the send is queued; the\ninvocation appears on the function's invocations list within a\nfew seconds.\n\nRequires that the function is currently `deployed`. Returns 422\nif the function is in `pending` or `failed` state, or if the\norg has no verified inbound domain to receive the test mail.\n",
+      "description": "Sends a real test email from a Primitive-controlled sender to a\nlocal-part on one of the org's verified inbound domains. By\ndefault the recipient is a synthetic\n`__primitive_function_test+<random>@<domain>` address that\nevery handler's catch-all routing receives identically; pass\n`local_part` to override and exercise routing logic that\nbranches on a specific recipient (the common pattern when one\nfunction handles multiple inboxes like `summarize@` and\n`action@`). The function fires through the normal MX delivery\npath, so reply / send-mail calls from inside the handler\nagainst the inbound's `email.id` work the same as in\nproduction. Returns immediately after the send is queued; the\ninvocation appears on the function's invocations list within a\nfew seconds.\n\nRequires that the function is currently `deployed`. Returns 422\nif the function is in `pending` or `failed` state, or if the\norg has no verified inbound domain to receive the test mail.\nReturns 400 if `local_part` is set to a value that does not\nmatch the local-part character set.\n",
       "flags": {
         "api-key": {
           "description": "Primitive API key (defaults to PRIMITIVE_API_KEY or saved `primitive login` credentials)",
@@ -3606,6 +3652,27 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "raw-body": {
+          "description": "Full request body as raw JSON. Escape hatch for nested or complex fields (e.g. arrays); prefer per-field flags (e.g. --to, --from, --body-text) when available.",
+          "name": "raw-body",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "body-file": {
+          "description": "Path to a JSON file used as the request body. Same role as --raw-body for callers passing a saved payload.",
+          "name": "body-file",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "local-part": {
+          "description": "Override the synthetic local-part. When set, the test email is sent to `<local_part>@<picked-domain>` instead of the default `__primitive_function_test+<random>@<picked-domain>`. Must start with an alphanumeric and contain only letters, digits, dots, plus signs, hyphens, or underscores; 1-64 characters total.",
+          "name": "local-part",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
@@ -4283,5 +4350,5 @@
       "enableJsonFlag": false
     }
   },
-  "version": "0.24.0"
+  "version": "0.25.1"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitivedotdev/cli",
-  "version": "0.24.0",
+  "version": "0.25.1",
   "description": "Official Primitive CLI: deploy Primitive Functions, send and inspect mail, manage endpoints, all from the terminal. Wraps the @primitivedotdev/sdk runtime client with one-shot commands.",
   "type": "module",
   "sideEffects": false,
@@ -92,7 +92,7 @@
     "@oclif/core": "^4.10.5",
     "@oclif/plugin-autocomplete": "^3.2.45",
     "@oclif/plugin-help": "^6.2.44",
-    "@primitivedotdev/sdk": "^0.23.0"
+    "@primitivedotdev/sdk": "^0.25.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.10",