@primitivedotdev/cli 0.26.0 → 0.26.2

package/dist/oclif/commands/doctor.js

@@ -81,6 +81,10 @@ function checkProxy() {
     return { status: "ok", message: present.join(", ") };
 }
 function checkApiKey(opts) {
+    // Take env explicitly so the unit test can inject a clean
+    // environment without mutating process.env across cases. Default to
+    // the live process env for real runs.
+    const env = opts.env ?? process.env;
     if (opts.apiKey?.startsWith("prim_")) {
         return { status: "ok", message: "provided via flag/env (prim_ prefix)" };
     }
@@ -91,6 +95,25 @@ function checkApiKey(opts) {
             hint: "Verify the key is a Primitive API key, not a value from another service.",
         };
     }
+    // PRIMITIVE_KEY rename detection. AGX feedback: users on older docs
+    // (or coming from other tools) set PRIMITIVE_KEY and then can't
+    // figure out why the CLI says "no API key found". The CLI reads
+    // PRIMITIVE_API_KEY only. Surface the rename hint when PRIMITIVE_KEY
+    // is set but PRIMITIVE_API_KEY is not, before falling through to
+    // the credentials.json / no-key checks. The hint runs before the
+    // credentials.json branch on purpose: if both PRIMITIVE_KEY and a
+    // valid credentials file are present, the credentials file wins
+    // silently and the user never sees the rename suggestion, which is
+    // the same trap by another name.
+    const primitiveKey = env.PRIMITIVE_KEY;
+    const primitiveApiKey = env.PRIMITIVE_API_KEY;
+    if ((primitiveKey?.length ?? 0) > 0 && (primitiveApiKey?.length ?? 0) === 0) {
+        return {
+            status: "fail",
+            message: "PRIMITIVE_KEY is set but the CLI reads PRIMITIVE_API_KEY",
+            hint: "Rename your env var, or re-run with PRIMITIVE_API_KEY=$PRIMITIVE_KEY.",
+        };
+    }
     const credsPath = join(opts.configDir, "credentials.json");
     if (existsSync(credsPath)) {
         let parsed = null;

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

@@ -18,7 +18,7 @@ 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.25.0";
+const SDK_VERSION_RANGE = "^0.26.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
@@ -184,11 +184,9 @@ export function renderPackageJson(name) {
         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
+            // the real CLI inside the scaffolded project so `npm run deploy`
+            // works without a global install. 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,

package/dist/oclif/commands/functions-test-function.js

@@ -0,0 +1,238 @@
+import { Command, Flags } from "@oclif/core";
+import { getEmail, PrimitiveApiClient, testFunction, } from "@primitivedotdev/sdk/api";
+import { API_BASE_URL_1_FLAG_DESCRIPTION, API_BASE_URL_2_FLAG_DESCRIPTION, baseUrlOverriddenFromFlags, extractErrorPayload, removeStaleSavedCredentialOnUnauthorized, runWithTiming, TIME_FLAG_DESCRIPTION, writeErrorWithHints, } from "../api-command.js";
+import { resolveCliAuth } from "../auth.js";
+import { DEFAULT_EMAIL_POLL_INTERVAL_SECONDS, fetchEmailSearchPage, sleep, } from "./emails-poll.js";
+// `primitive functions:test-function` is the agent-grade shortcut for
+// triggering a real round-trip and (optionally) waiting for the
+// function to actually run before exiting. The underlying
+// `POST /functions/{id}/test` operation only kicks off a synthetic
+// inbound through MX and returns the queued send id; AGX walkthroughs
+// flagged the missing wait-and-show-sends step as the single biggest
+// time-sink in the verification loop.
+//
+// Shapes:
+//   primitive functions:test-function --id <fn-id>
+//       Fire-and-forget. Returns the TestInvocationResult JSON
+//       (recipient, poll_since, watch_url). Same behavior as the
+//       auto-generated functions:test-function it replaces.
+//
+//   primitive functions:test-function --id <fn-id> --wait
+//       Blocks until the test inbound has arrived AND the function's
+//       webhook has fired (or --timeout elapses). Exits non-zero on
+//       timeout or on exhausted retries.
+//
+//   primitive functions:test-function --id <fn-id> --wait --show-sends
+//       Same as --wait, plus prints the inbound's `replies` array
+//       (every outbound the function emitted while processing the
+//       test inbound), with each send's id, status, recipient,
+//       subject, and queue id.
+//
+// The auto-generated functions:test-function entry is filtered out
+// of the generated-command set in oclif/index.ts so this hand-rolled
+// version owns the id.
+const DEFAULT_WAIT_TIMEOUT_SECONDS = 60;
+// Terminal states from the EmailWebhookStatus enum. `fired` means the
+// function returned 2xx; `exhausted` means all retries are spent and
+// the delivery is permanently failed. `pending` / `in_flight` /
+// `failed` are intermediate (`failed` is a temporary failure that may
+// retry into `fired` or eventually `exhausted`), so we keep polling.
+const TERMINAL_WEBHOOK_STATUSES = new Set(["fired", "exhausted"]);
+class FunctionsTestFunctionCommand extends Command {
+    static description = "Send a real test email through MX to trigger this function. With --wait, blocks until the function has processed the inbound; with --show-sends, also prints any outbound sends the function emitted in response.";
+    static summary = "Trigger a test invocation; with --wait, watch it land";
+    static examples = [
+        "<%= config.bin %> functions:test-function --id <fn-id>",
+        "<%= config.bin %> functions:test-function --id <fn-id> --local-part summarize",
+        "<%= config.bin %> functions:test-function --id <fn-id> --wait --show-sends",
+        "<%= config.bin %> functions:test-function --id <fn-id> --local-part summarize --wait --timeout 120",
+    ];
+    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: API_BASE_URL_1_FLAG_DESCRIPTION,
+            env: "PRIMITIVE_API_BASE_URL_1",
+            hidden: true,
+        }),
+        "api-base-url-2": Flags.string({
+            description: API_BASE_URL_2_FLAG_DESCRIPTION,
+            env: "PRIMITIVE_API_BASE_URL_2",
+            hidden: true,
+        }),
+        id: Flags.string({
+            description: "Function id (UUID).",
+            required: true,
+        }),
+        "local-part": Flags.string({
+            description: "Override the synthetic local-part the test inbound is addressed to. Otherwise the runtime picks `__primitive_function_test+<random>`.",
+        }),
+        wait: Flags.boolean({
+            description: "Block until the function has processed the test inbound (webhook status is `fired` or `exhausted`) or --timeout elapses. Exits non-zero on timeout or on exhausted retries.",
+        }),
+        "show-sends": Flags.boolean({
+            description: "When the wait resolves, also print the outbound emails the function emitted while processing the test inbound (id, status, to, subject). Implies --wait.",
+        }),
+        timeout: Flags.integer({
+            default: DEFAULT_WAIT_TIMEOUT_SECONDS,
+            description: "Seconds to wait before exiting non-zero when --wait is set; 0 waits forever.",
+            min: 0,
+        }),
+        "poll-interval": Flags.integer({
+            default: DEFAULT_EMAIL_POLL_INTERVAL_SECONDS,
+            description: "Seconds between polls while waiting.",
+            min: 1,
+        }),
+        time: Flags.boolean({
+            description: TIME_FLAG_DESCRIPTION,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(FunctionsTestFunctionCommand);
+        // --show-sends implies --wait. You can't print what was sent
+        // until the function has actually run.
+        const shouldWait = flags.wait || flags["show-sends"];
+        const shouldShowSends = flags["show-sends"];
+        const baseUrlOverridden = baseUrlOverriddenFromFlags(flags);
+        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,
+        });
+        await runWithTiming(flags.time, async () => {
+            // 1. Trigger the test send.
+            const triggerResult = await testFunction({
+                client: apiClient.client,
+                path: { id: flags.id },
+                body: flags["local-part"]
+                    ? { local_part: flags["local-part"] }
+                    : undefined,
+                responseStyle: "fields",
+            });
+            if (triggerResult.error) {
+                const payload = extractErrorPayload(triggerResult.error);
+                writeErrorWithHints(payload);
+                removeStaleSavedCredentialOnUnauthorized({
+                    auth,
+                    baseUrlOverridden,
+                    configDir: this.config.configDir,
+                    payload,
+                });
+                process.exitCode = 1;
+                return;
+            }
+            const invocation = triggerResult.data
+                .data;
+            if (!shouldWait) {
+                // Fire-and-forget path: print the TestInvocationResult JSON
+                // unchanged. Same shape the auto-generated command emitted.
+                this.log(JSON.stringify(invocation, null, 2));
+                return;
+            }
+            const startedAt = Date.now();
+            const timeoutMs = flags.timeout * 1000;
+            const pollIntervalMs = flags["poll-interval"] * 1000;
+            const isExpired = () => flags.timeout > 0 && Date.now() - startedAt > timeoutMs;
+            // 2. Wait for the test inbound to arrive. The synthetic
+            // recipient is unique per call (random suffix in the local-part
+            // unless --local-part overrides), so `to` + `since` uniquely
+            // identifies the test inbound row.
+            this.log(`Waiting for test inbound to arrive at ${invocation.to}...`);
+            let inboundId;
+            while (!isExpired()) {
+                const page = await fetchEmailSearchPage({
+                    apiClient,
+                    filters: { to: invocation.to },
+                    pageSize: 25,
+                    since: invocation.poll_since,
+                });
+                if (!page.ok) {
+                    const payload = extractErrorPayload(page.error);
+                    writeErrorWithHints(payload);
+                    removeStaleSavedCredentialOnUnauthorized({
+                        auth,
+                        baseUrlOverridden,
+                        configDir: this.config.configDir,
+                        payload,
+                    });
+                    process.exitCode = 1;
+                    return;
+                }
+                const found = page.rows[0];
+                if (found) {
+                    inboundId = found.id;
+                    break;
+                }
+                await sleep(pollIntervalMs);
+            }
+            if (!inboundId) {
+                this.error(`Timed out after ${flags.timeout}s waiting for test inbound ${invocation.to} to land. Browse ${invocation.watch_url} for the live view.`, { exit: 2 });
+            }
+            // 3. Wait for the function (webhook) to actually run. We poll
+            // the email-detail endpoint because it already carries both the
+            // webhook_status terminal state and the `replies` array we'll
+            // print under --show-sends. No second endpoint needed.
+            this.log(`Inbound landed (${inboundId}). Waiting for function to run...`);
+            let detail;
+            while (!isExpired()) {
+                const result = await getEmail({
+                    client: apiClient.client,
+                    path: { id: inboundId },
+                    responseStyle: "fields",
+                });
+                if (result.error) {
+                    const payload = extractErrorPayload(result.error);
+                    writeErrorWithHints(payload);
+                    removeStaleSavedCredentialOnUnauthorized({
+                        auth,
+                        baseUrlOverridden,
+                        configDir: this.config.configDir,
+                        payload,
+                    });
+                    process.exitCode = 1;
+                    return;
+                }
+                const fetched = result.data.data;
+                if (fetched.webhook_status &&
+                    TERMINAL_WEBHOOK_STATUSES.has(fetched.webhook_status)) {
+                    detail = fetched;
+                    break;
+                }
+                await sleep(pollIntervalMs);
+            }
+            if (!detail) {
+                this.error(`Timed out after ${flags.timeout}s waiting for function webhook to fire for inbound ${inboundId}. Browse ${invocation.watch_url} for the live view.`, { exit: 2 });
+            }
+            // 4. Emit the outcome.
+            const elapsedSeconds = Math.round((Date.now() - startedAt) / 1000);
+            const outcome = {
+                function_id: flags.id,
+                inbound_id: inboundId,
+                inbound_to: invocation.to,
+                webhook_status: detail.webhook_status,
+                webhook_attempt_count: detail.webhook_attempt_count,
+                webhook_last_status_code: detail.webhook_last_status_code,
+                webhook_last_error: detail.webhook_last_error,
+                elapsed_seconds: elapsedSeconds,
+            };
+            if (shouldShowSends) {
+                outcome.sent_emails = detail.replies;
+            }
+            this.log(JSON.stringify(outcome, null, 2));
+            // Exit non-zero when the function failed permanently so CI
+            // scripts can gate on the exit code.
+            if (detail.webhook_status === "exhausted") {
+                process.exitCode = 1;
+            }
+        });
+    }
+}
+export default FunctionsTestFunctionCommand;

package/dist/oclif/index.js

@@ -9,6 +9,7 @@ import FunctionsDeployCommand from "./commands/functions-deploy.js";
 import FunctionsInitCommand from "./commands/functions-init.js";
 import FunctionsRedeployCommand from "./commands/functions-redeploy.js";
 import FunctionsSetSecretCommand from "./commands/functions-set-secret.js";
+import FunctionsTestFunctionCommand from "./commands/functions-test-function.js";
 import LoginCommand from "./commands/login.js";
 import LogoutCommand from "./commands/logout.js";
 import SendCommand from "./commands/send.js";
@@ -108,7 +109,17 @@ class CompletionCommand extends Command {
 function commandId(operation) {
     return `${operation.tagCommand}:${operation.command}`;
 }
-const generatedCommands = Object.fromEntries(operationManifest.map((operation) => [
+// Operation ids whose surface is owned by a hand-rolled command in
+// COMMANDS below. The auto-generated wrapper is filtered out so the
+// hand-rolled command owns the id without a name collision.
+const OVERRIDDEN_OPERATION_IDS = new Set([
+    // `functions:test-function` is hand-rolled to add --wait, --show-sends,
+    // and --timeout flags on top of the auto-generated POST /functions/{id}/test.
+    "functions:test-function",
+]);
+const generatedCommands = Object.fromEntries(operationManifest
+    .filter((operation) => !OVERRIDDEN_OPERATION_IDS.has(commandId(operation)))
+    .map((operation) => [
     commandId(operation),
     createOperationCommand(operation),
 ]));
@@ -171,5 +182,12 @@ export const COMMANDS = {
     // visible to the running handler requires a separate redeploy,
     // which this shortcut folds in via --redeploy.
     "functions:set-secret": FunctionsSetSecretCommand,
+    // `functions:test-function` is hand-rolled to add --wait, --show-sends,
+    // and --timeout on top of POST /functions/{id}/test. Without those
+    // flags, agents had to manually thread queued-send + emails:wait +
+    // emails:get-email + sending:list-sent-emails to verify a function
+    // ran and see what it emitted; AGX walkthroughs flagged that loop as
+    // the single biggest verification time-sink.
+    "functions:test-function": FunctionsTestFunctionCommand,
     ...generatedCommands,
 };

package/oclif.manifest.json

@@ -1036,6 +1036,103 @@
       "summary": "Write a function secret (optionally redeploying to push it live)",
       "enableJsonFlag": false
     },
+    "functions:test-function": {
+      "aliases": [],
+      "args": {},
+      "description": "Send a real test email through MX to trigger this function. With --wait, blocks until the function has processed the inbound; with --show-sends, also prints any outbound sends the function emitted in response.",
+      "examples": [
+        "<%= config.bin %> functions:test-function --id <fn-id>",
+        "<%= config.bin %> functions:test-function --id <fn-id> --local-part summarize",
+        "<%= config.bin %> functions:test-function --id <fn-id> --wait --show-sends",
+        "<%= config.bin %> functions:test-function --id <fn-id> --local-part summarize --wait --timeout 120"
+      ],
+      "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"
+        },
+        "id": {
+          "description": "Function id (UUID).",
+          "name": "id",
+          "required": true,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "local-part": {
+          "description": "Override the synthetic local-part the test inbound is addressed to. Otherwise the runtime picks `__primitive_function_test+<random>`.",
+          "name": "local-part",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "wait": {
+          "description": "Block until the function has processed the test inbound (webhook status is `fired` or `exhausted`) or --timeout elapses. Exits non-zero on timeout or on exhausted retries.",
+          "name": "wait",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "show-sends": {
+          "description": "When the wait resolves, also print the outbound emails the function emitted while processing the test inbound (id, status, to, subject). Implies --wait.",
+          "name": "show-sends",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "timeout": {
+          "description": "Seconds to wait before exiting non-zero when --wait is set; 0 waits forever.",
+          "name": "timeout",
+          "default": 60,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "poll-interval": {
+          "description": "Seconds between polls while waiting.",
+          "name": "poll-interval",
+          "default": 2,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "time": {
+          "description": "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.",
+          "name": "time",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "functions:test-function",
+      "pluginAlias": "@primitivedotdev/cli",
+      "pluginName": "@primitivedotdev/cli",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Trigger a test invocation; with --wait, watch it land",
+      "enableJsonFlag": false
+    },
     "account:get-account": {
       "aliases": [],
       "args": {},
@@ -3095,7 +3192,7 @@
     "functions:create-function": {
       "aliases": [],
       "args": {},
-      "description": "Creates and deploys a new function. The handler must be a single\nESM module that exports a default async function receiving the\n`email.received` event (see the Webhook payload section for the\nfull schema). Code is bundled before being uploaded; ship a\nsingle self-contained file rather than relying on external\nimports.\n\n**Code limits.** `code` is capped at 1 MiB UTF-8. `sourceMap`\n(optional) is capped at 5 MiB UTF-8 and is stored only on the\nedge runtime side; it is not persisted in Primitive's database.\n\n**Auto-wiring.** On successful deploy, Primitive automatically\ncreates a webhook endpoint that delivers inbound mail to the\nfunction. There is nothing to configure on the Endpoints API\nfor this to work; the gateway URL returned here is for\nreference only and is not directly callable from outside.\n\n**Secrets.** New functions ship with the managed secrets\n(`PRIMITIVE_WEBHOOK_SECRET`, `PRIMITIVE_API_KEY`) already\nbound. Add user-set secrets via\n`POST /functions/{id}/secrets`; secret writes only land in the\nrunning handler on the next redeploy.\n\n\nTip: prefer `primitive functions:deploy --name <name> --file <bundle>` for file-input ergonomics. This raw command exists for callers passing JSON.",
+      "description": "Creates and deploys a new function. The handler must be a single\nESM module whose default export is an object with an async\n`fetch(request, env)` method (Workers-style). The gateway\nHMAC-verifies the POST against the org's webhook secret before\ninvoking the handler; the request body parses to an\n`email.received` event (see `EmailReceivedEvent` and the\nWebhook payload section for the full schema). Code is bundled\nbefore being uploaded; ship a single self-contained file rather\nthan relying on external imports.\n\n**Code limits.** `code` is capped at 1 MiB UTF-8. `sourceMap`\n(optional) is capped at 5 MiB UTF-8 and is stored only on the\nedge runtime side; it is not persisted in Primitive's database.\n\n**Auto-wiring.** On successful deploy, Primitive automatically\ncreates a webhook endpoint that delivers inbound mail to the\nfunction. There is nothing to configure on the Endpoints API\nfor this to work; the gateway URL returned here is for\nreference only and is not directly callable from outside.\n\n**Secrets.** New functions ship with the managed secrets\n(`PRIMITIVE_WEBHOOK_SECRET`, `PRIMITIVE_API_KEY`) already\nbound. Add user-set secrets via\n`POST /functions/{id}/secrets`; secret writes only land in the\nrunning handler on the next redeploy.\n\n\nTip: prefer `primitive functions:deploy --name <name> --file <bundle>` for file-input ergonomics. This raw command exists for callers passing JSON.",
       "flags": {
         "api-key": {
           "description": "Primitive API key (defaults to PRIMITIVE_API_KEY or saved `primitive login` credentials)",
@@ -3435,10 +3532,10 @@
       "summary": "Get a function",
       "enableJsonFlag": false
     },
-    "functions:list-function-secrets": {
+    "functions:list-function-logs": {
       "aliases": [],
       "args": {},
-      "description": "Returns metadata for every secret bound to the function, with\nmanaged entries (provisioned by Primitive) listed first and\nuser-set entries listed alphabetically after. **Values are\nnever returned.** Secret writes are write-only.\n\nManaged entries (e.g. `PRIMITIVE_WEBHOOK_SECRET`,\n`PRIMITIVE_API_KEY`) carry a `description` instead of\n`created_at` / `updated_at`. They cannot be created, updated,\nor deleted via this API.\n",
+      "description": "Returns the most recent `function_logs` rows for the function,\nnewest first. Each row is a single `console.log` / `console.error`\ninvocation captured from the running handler.\n\nPage through history with the opaque `cursor` returned as\n`next_cursor`; pass it back as the `cursor` query param on the\nnext call. `next_cursor` is `null` when there are no further\nrows. The cursor format is an implementation detail and should\nnot be parsed by callers.\n",
       "flags": {
         "api-key": {
           "description": "Primitive API key (defaults to PRIMITIVE_API_KEY or saved `primitive login` credentials)",
@@ -3479,22 +3576,38 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "limit": {
+          "description": "Maximum number of rows to return. Clamped to 1..200; default\n50.\n",
+          "name": "limit",
+          "required": false,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "cursor": {
+          "description": "Opaque pagination cursor from a previous response's\n`next_cursor`. Omit on the first call.\n",
+          "name": "cursor",
+          "required": false,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "functions:list-function-secrets",
+      "id": "functions:list-function-logs",
       "pluginAlias": "@primitivedotdev/cli",
       "pluginName": "@primitivedotdev/cli",
       "pluginType": "core",
       "strict": true,
-      "summary": "List a function's secrets",
+      "summary": "List a function's execution logs",
       "enableJsonFlag": false
     },
-    "functions:list-functions": {
+    "functions:list-function-secrets": {
       "aliases": [],
       "args": {},
-      "description": "Returns every active (non-deleted) function in the org, newest\nfirst. Each entry carries the deploy status and the gateway URL\nthat the platform's webhook delivery loop posts to. To inspect\nthe source code or deploy errors, use `GET /functions/{id}`.\n",
+      "description": "Returns metadata for every secret bound to the function, with\nmanaged entries (provisioned by Primitive) listed first and\nuser-set entries listed alphabetically after. **Values are\nnever returned.** Secret writes are write-only.\n\nManaged entries (e.g. `PRIMITIVE_WEBHOOK_SECRET`,\n`PRIMITIVE_API_KEY`) carry a `description` instead of\n`created_at` / `updated_at`. They cannot be created, updated,\nor deleted via this API.\n",
       "flags": {
         "api-key": {
           "description": "Primitive API key (defaults to PRIMITIVE_API_KEY or saved `primitive login` credentials)",
@@ -3527,22 +3640,30 @@
           "name": "time",
           "allowNo": false,
           "type": "boolean"
+        },
+        "id": {
+          "description": "Resource UUID",
+          "name": "id",
+          "required": true,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "functions:list-functions",
+      "id": "functions:list-function-secrets",
       "pluginAlias": "@primitivedotdev/cli",
       "pluginName": "@primitivedotdev/cli",
       "pluginType": "core",
       "strict": true,
-      "summary": "List functions",
+      "summary": "List a function's secrets",
       "enableJsonFlag": false
     },
-    "functions:set-function-secret": {
+    "functions:list-functions": {
       "aliases": [],
       "args": {},
-      "description": "Path-keyed companion to `POST /functions/{id}/secrets`.\nIdempotent: returns 201 the first time the key is set, 200 on\nsubsequent updates. Same validation rules and same write-only\nguarantees as the POST verb; the new value lands in the running\nhandler on the next deploy.\n\n\nTip: prefer `primitive functions:set-secret --id <id> --key <KEY> --value <value> [--redeploy]` for secret writes that also push the binding live. This raw command exists for callers passing JSON.",
+      "description": "Returns every active (non-deleted) function in the org, newest\nfirst. Each entry carries the deploy status and the gateway URL\nthat the platform's webhook delivery loop posts to. To inspect\nthe source code or deploy errors, use `GET /functions/{id}`.\n",
       "flags": {
         "api-key": {
           "description": "Primitive API key (defaults to PRIMITIVE_API_KEY or saved `primitive login` credentials)",
@@ -3575,59 +3696,22 @@
           "name": "time",
           "allowNo": false,
           "type": "boolean"
-        },
-        "id": {
-          "description": "Resource UUID",
-          "name": "id",
-          "required": true,
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "key": {
-          "description": "Secret key. Must match `^[A-Z_][A-Z0-9_]*$`.",
-          "name": "key",
-          "required": true,
-          "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"
-        },
-        "value": {
-          "description": "value",
-          "name": "value",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "functions:set-function-secret",
+      "id": "functions:list-functions",
       "pluginAlias": "@primitivedotdev/cli",
       "pluginName": "@primitivedotdev/cli",
       "pluginType": "core",
       "strict": true,
-      "summary": "Set a secret by key",
+      "summary": "List functions",
       "enableJsonFlag": false
     },
-    "functions:test-function": {
+    "functions:set-function-secret": {
       "aliases": [],
       "args": {},
-      "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",
+      "description": "Path-keyed companion to `POST /functions/{id}/secrets`.\nIdempotent: returns 201 the first time the key is set, 200 on\nsubsequent updates. Same validation rules and same write-only\nguarantees as the POST verb; the new value lands in the running\nhandler on the next deploy.\n\n\nTip: prefer `primitive functions:set-secret --id <id> --key <KEY> --value <value> [--redeploy]` for secret writes that also push the binding live. This raw command exists for callers passing JSON.",
       "flags": {
         "api-key": {
           "description": "Primitive API key (defaults to PRIMITIVE_API_KEY or saved `primitive login` credentials)",
@@ -3669,6 +3753,14 @@
           "multiple": false,
           "type": "option"
         },
+        "key": {
+          "description": "Secret key. Must match `^[A-Z_][A-Z0-9_]*$`.",
+          "name": "key",
+          "required": true,
+          "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",
@@ -3683,9 +3775,9 @@
           "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",
+        "value": {
+          "description": "value",
+          "name": "value",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
@@ -3693,12 +3785,12 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "functions:test-function",
+      "id": "functions:set-function-secret",
       "pluginAlias": "@primitivedotdev/cli",
       "pluginName": "@primitivedotdev/cli",
       "pluginType": "core",
       "strict": true,
-      "summary": "Send a test invocation",
+      "summary": "Set a secret by key",
       "enableJsonFlag": false
     },
     "functions:update-function": {
@@ -4366,5 +4458,5 @@
       "enableJsonFlag": false
     }
   },
-  "version": "0.26.0"
+  "version": "0.26.2"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitivedotdev/cli",
-  "version": "0.26.0",
+  "version": "0.26.2",
   "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,
@@ -35,7 +35,7 @@
         "description": "Claim, verify, and manage email domains"
       },
       "emails": {
-        "description": "List, inspect, and manage received emails. Use `primitive emails:latest` for a one-line-per-email summary of recent inbound mail."
+        "description": "List, inspect, and wait for received emails. `primitive emails:latest` lists the most recent inbound, `primitive emails:wait` blocks until matching inbound arrives (filter with --to/--from/--subject/--q; bounded by --timeout and --number; ideal for agents and CI), and `primitive emails:watch` streams new matches indefinitely for long-running terminals."
       },
       "sending": {
         "description": "Send outbound emails. For replies to inbound mail, use `sending:reply-to-email --id <inbound-id>` (threading and Re: subject derived server-side); for fresh sends, use `sending:send-email` or the `primitive send` shortcut."
@@ -92,7 +92,7 @@
     "@oclif/core": "^4.10.5",
     "@oclif/plugin-autocomplete": "^3.2.45",
     "@oclif/plugin-help": "^6.2.44",
-    "@primitivedotdev/sdk": "^0.25.0"
+    "@primitivedotdev/sdk": "^0.26.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.10",