@primitivedotdev/cli 0.25.0 → 0.25.2

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

@@ -1,35 +1,147 @@
 import { Command, Flags } from "@oclif/core";
-import { createFunction, PrimitiveApiClient } from "@primitivedotdev/sdk/api";
+import { createFunction, PrimitiveApiClient, setFunctionSecret, updateFunction, } from "@primitivedotdev/sdk/api";
 import { extractErrorPayload, readTextFileFlag, removeStaleSavedCredentialOnUnauthorized, runWithTiming, TIME_FLAG_DESCRIPTION, writeErrorWithHints, } from "../api-command.js";
 import { resolveCliAuth } from "../auth.js";
 import { emitRawSendMailFetchWarning } from "../lint/raw-send-mail-fetch.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.
+import { parseSecretFlags, SECRET_FLAG_SECURITY_NOTE, } from "../secret-flags.js";
+// Pure-ish orchestration of create + (optional secrets + redeploy).
+// Mirrors runSetSecret in functions-set-secret.ts so the failure
+// stages map directly onto stderr hints in run() below. Pulled out
+// as a named export so the unit test can drive every branch with a
+// fake DeployApiSurface, without spinning up a real client or the
+// oclif command lifecycle.
+export async function runDeployWithSecrets(api, params) {
+    const createResult = await api.createFunction({
+        code: params.code,
+        name: params.name,
+        ...(params.sourceMap !== undefined ? { sourceMap: params.sourceMap } : {}),
+    });
+    if (createResult.error) {
+        return {
+            kind: "error",
+            payload: extractErrorPayload(createResult.error),
+            stage: "create",
+        };
+    }
+    const created = createResult.data?.data;
+    if (!created) {
+        return {
+            kind: "error",
+            payload: {
+                code: "client_error",
+                message: "Create function returned no data",
+            },
+            stage: "create",
+        };
+    }
+    // Fast path: no secrets means no extra round-trips. The naked
+    // create result is exactly what the pre-secrets-flag command
+    // returned, so this branch is byte-identical to the previous
+    // behavior.
+    if (params.secrets.length === 0) {
+        return { kind: "ok", result: { created } };
+    }
+    const writtenSecrets = [];
+    const succeededKeys = [];
+    for (let i = 0; i < params.secrets.length; i++) {
+        const pair = params.secrets[i];
+        // Pre-compute the keys that come AFTER the current pair so a
+        // set-secret failure can surface every key that was never
+        // attempted, not just the one that failed. Without this, a user
+        // following the recovery hint verbatim would re-run set-secret
+        // only for the failed key and silently leave the trailing keys
+        // un-written.
+        const pendingKeys = params.secrets.slice(i + 1).map((p) => p.key);
+        const setResult = await api.setSecret({
+            id: created.id,
+            key: pair.key,
+            value: pair.value,
+        });
+        if (setResult.error) {
+            return {
+                created,
+                failedKey: pair.key,
+                kind: "error",
+                payload: extractErrorPayload(setResult.error),
+                pendingKeys,
+                stage: "set-secret",
+                succeededKeys,
+            };
+        }
+        const secret = setResult.data?.data;
+        if (!secret) {
+            return {
+                created,
+                failedKey: pair.key,
+                kind: "error",
+                payload: {
+                    code: "client_error",
+                    message: "Secret write returned no data",
+                },
+                pendingKeys,
+                stage: "set-secret",
+                succeededKeys,
+            };
+        }
+        writtenSecrets.push(secret);
+        succeededKeys.push(pair.key);
+    }
+    const updateResult = await api.updateFunction({
+        code: params.code,
+        id: created.id,
+        ...(params.sourceMap !== undefined ? { sourceMap: params.sourceMap } : {}),
+    });
+    if (updateResult.error) {
+        return {
+            created,
+            kind: "error",
+            payload: extractErrorPayload(updateResult.error),
+            stage: "redeploy",
+            succeededKeys,
+        };
+    }
+    const redeployed = updateResult.data?.data;
+    if (!redeployed) {
+        return {
+            created,
+            kind: "error",
+            payload: {
+                code: "client_error",
+                message: "Redeploy returned no data",
+            },
+            stage: "redeploy",
+            succeededKeys,
+        };
+    }
+    return {
+        kind: "ok",
+        result: { created, redeploy: redeployed, secrets: writtenSecrets },
+    };
+}
 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.).`;
+  (raw-body JSON, etc.).
+
+  Pass --secret KEY=VALUE (repeatable) to seed secret bindings in the
+  same command. Keys must match \`^[A-Z_][A-Z0-9_]*$\` (uppercase
+  letters, digits, underscores; first character is a letter or
+  underscore). With one or more --secret flags the deploy fans out to
+  multiple API calls: create-function, set-secret per pair, then a
+  final update-function with the same bundle so the running handler
+  picks up the bindings. If a secret write fails after the create
+  step the function exists with whatever secrets succeeded and the
+  redeploy has NOT fired; re-run \`primitive functions:set-secret\`
+  for the missing keys, then \`primitive functions:redeploy\` to
+  push them live.`;
     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",
+        "<%= config.bin %> functions:deploy --name forwarder --file ./bundle.js --secret OPENAI_KEY=sk-... --secret OWNER_EMAIL=me@example.com",
     ];
     static flags = {
         "api-key": Flags.string({
@@ -57,6 +169,10 @@ class FunctionsDeployCommand extends Command {
         "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.",
         }),
+        secret: Flags.string({
+            description: `Secret KEY=VALUE to seed on the deployed function. Repeatable. KEY must match \`^[A-Z_][A-Z0-9_]*$\`; VALUE may contain \`=\` (only the first \`=\` is treated as a delimiter). Each KEY may only appear once per command. Passing one or more --secret flags fans out the deploy to create-function, set-secret per pair, then a final redeploy so the running handler picks up the bindings. ${SECRET_FLAG_SECURITY_NOTE}`,
+            multiple: true,
+        }),
         time: Flags.boolean({
             description: TIME_FLAG_DESCRIPTION,
         }),
@@ -64,6 +180,17 @@ class FunctionsDeployCommand extends Command {
     async run() {
         const { flags } = await this.parse(FunctionsDeployCommand);
         await runWithTiming(flags.time, async () => {
+            // Validate --secret pairs BEFORE any disk read or API call so
+            // a malformed input fails fast with a clear error and zero
+            // side effects. The fast path (no --secret flags) skips this
+            // entirely.
+            const rawSecrets = flags.secret ?? [];
+            const parsedSecrets = parseSecretFlags(rawSecrets);
+            if (parsedSecrets.kind === "error") {
+                process.stderr.write(`${parsedSecrets.message}\n`);
+                process.exitCode = 1;
+                return;
+            }
             // 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
@@ -96,27 +223,79 @@ class FunctionsDeployCommand extends Command {
                 baseUrlOverridden,
                 configDir: this.config.configDir,
             };
-            const result = await createFunction({
-                body: {
-                    name: flags.name,
-                    code,
-                    ...(sourceMap !== undefined ? { sourceMap } : {}),
-                },
-                client: apiClient.client,
-                responseStyle: "fields",
+            // Adapter: thin wrappers around the generated SDK calls,
+            // routed through host 1 (apiClient.client). The function
+            // CRUD and secrets endpoints are not on host 2.
+            const apiSurface = {
+                createFunction: (p) => createFunction({
+                    body: {
+                        code: p.code,
+                        name: p.name,
+                        ...(p.sourceMap !== undefined ? { sourceMap: p.sourceMap } : {}),
+                    },
+                    client: apiClient.client,
+                    responseStyle: "fields",
+                }),
+                setSecret: (p) => setFunctionSecret({
+                    body: { value: p.value },
+                    client: apiClient.client,
+                    path: { id: p.id, key: p.key },
+                    responseStyle: "fields",
+                }),
+                updateFunction: (p) => updateFunction({
+                    body: {
+                        code: p.code,
+                        ...(p.sourceMap !== undefined ? { sourceMap: p.sourceMap } : {}),
+                    },
+                    client: apiClient.client,
+                    path: { id: p.id },
+                    responseStyle: "fields",
+                }),
+            };
+            const outcome = await runDeployWithSecrets(apiSurface, {
+                code,
+                name: flags.name,
+                secrets: parsedSecrets.secrets,
+                ...(sourceMap !== undefined ? { sourceMap } : {}),
             });
-            if (result.error) {
-                const errorPayload = extractErrorPayload(result.error);
-                writeErrorWithHints(errorPayload);
+            if (outcome.kind === "error") {
+                // Stage-specific framing on stderr so callers can tell
+                // whether the function was created before a downstream
+                // failure left it without secrets or without the
+                // redeploy. The JSON envelope still goes through
+                // writeErrorWithHints so any actionable hint (e.g.
+                // unauthorized) is surfaced.
+                if (outcome.stage === "set-secret") {
+                    const succeeded = outcome.succeededKeys.length > 0
+                        ? outcome.succeededKeys.join(", ")
+                        : "(none)";
+                    const pending = outcome.pendingKeys.length > 0
+                        ? outcome.pendingKeys.join(", ")
+                        : "(none)";
+                    const allMissing = [outcome.failedKey, ...outcome.pendingKeys].join(", ");
+                    process.stderr.write(`Function ${outcome.created.name} (${outcome.created.id}) was created, but writing secret ${outcome.failedKey} failed; succeeded keys so far: ${succeeded}; keys not yet attempted: ${pending}. The redeploy is NOT yet live. Re-run \`primitive functions:set-secret\` for each of [${allMissing}], then \`primitive functions:redeploy --id ${outcome.created.id} --file <bundle>\` to push them live.\n`);
+                }
+                else if (outcome.stage === "redeploy") {
+                    const succeeded = outcome.succeededKeys.length > 0
+                        ? outcome.succeededKeys.join(", ")
+                        : "(none)";
+                    process.stderr.write(`Function ${outcome.created.name} (${outcome.created.id}) was created and secrets [${succeeded}] were written, but the final redeploy failed; the new bindings are NOT yet live. Re-run \`primitive functions:redeploy --id ${outcome.created.id} --file <bundle>\` once the cause is fixed.\n`);
+                }
+                writeErrorWithHints(outcome.payload);
                 removeStaleSavedCredentialOnUnauthorized({
                     ...authFailureContext,
-                    payload: errorPayload,
+                    payload: outcome.payload,
                 });
                 process.exitCode = 1;
                 return;
             }
-            const envelope = result.data;
-            this.log(JSON.stringify(envelope?.data ?? null, null, 2));
+            // On the happy path, prefer the redeployed FunctionDetail
+            // (when secrets fired) over the bare CreateFunctionResult,
+            // since the redeploy is the state the user actually
+            // deployed. When no secrets were passed, fall back to the
+            // create payload for byte-identical pre-flag behavior.
+            const payload = outcome.result.redeploy ?? outcome.result.created;
+            this.log(JSON.stringify(payload, null, 2));
         });
     }
 }

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,10 +51,16 @@ export function renderHandler() {
     return `// env.PRIMITIVE_API_KEY is auto-injected by the Primitive Functions runtime.
 import { createPrimitiveClient } from "@primitivedotdev/sdk/api";
 
+// TODO: replace with your verified sender address. Must be a domain
+// you own or your managed *.primitive.email subdomain. The
+// self-reply guard below compares incoming mail against this value
+// to avoid the handler replying to its own outbound traffic.
+const REPLY_FROM = "you@your-domain.primitive.email";
+
 interface EmailReceivedEvent {
   event: string;
   email: {
-    headers: { from?: string; subject?: string };
+    headers: { from?: string; to?: string; subject?: string };
   };
 }
 
@@ -63,6 +80,20 @@ export default {
         return Response.json({ ok: true, skipped: event.event });
       }
 
+      // Self-reply guard: do not act on mail that this function itself
+      // sent. Without this, an outbound reply that gets forwarded back
+      // into the inbox would trigger another reply, and so on.
+      //
+      // event.email.headers.from is the raw RFC 2822 header value, so
+      // it may be either a bare address ("alice@example.com") or a
+      // display-name form ("Alice <alice@example.com>"). A substring
+      // check matches both. Tighten this predicate (e.g. parse the
+      // bracketed address) if you legitimately want to act on mail
+      // from your own domain.
+      if (event.email.headers.from?.includes(REPLY_FROM)) {
+        return Response.json({ ok: true, skipped: "self-reply" });
+      }
+
       const client = createPrimitiveClient({ apiKey: env.PRIMITIVE_API_KEY });
 
       // Recipient gate
@@ -73,9 +104,14 @@ export default {
       // 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.
+
+      // Recipient routing: a single function can handle multiple inbound
+      // addresses by branching on event.email.headers.to. For example,
+      // route "support@" to a ticketing flow and "sales@" to a lead
+      // capture flow before calling client.send.
       const reply = await client.send({
-        from: "you@your-domain.primitive.email",
-        to: event.email.headers.from ?? "you@your-domain.primitive.email",
+        from: REPLY_FROM,
+        to: event.email.headers.from ?? REPLY_FROM,
         subject: \`Re: \${event.email.headers.subject ?? ""}\`,
         bodyText: "Got your message.",
       });
@@ -111,6 +147,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/commands/functions-redeploy.js

@@ -1,26 +1,108 @@
 import { Command, Flags } from "@oclif/core";
-import { PrimitiveApiClient, updateFunction } from "@primitivedotdev/sdk/api";
+import { PrimitiveApiClient, setFunctionSecret, updateFunction, } from "@primitivedotdev/sdk/api";
 import { extractErrorPayload, readTextFileFlag, removeStaleSavedCredentialOnUnauthorized, runWithTiming, TIME_FLAG_DESCRIPTION, writeErrorWithHints, } from "../api-command.js";
 import { resolveCliAuth } from "../auth.js";
 import { emitRawSendMailFetchWarning } from "../lint/raw-send-mail-fetch.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.
+import { parseSecretFlags, SECRET_FLAG_SECURITY_NOTE, } from "../secret-flags.js";
+// Pure-ish orchestration of (optional secrets +) update-function.
+// Writes every secret first, then re-deploys with the new bundle so
+// a single updateFunction call refreshes every binding the user
+// wrote. Pulled out as a named export so the unit test can drive
+// every branch with a fake RedeployApiSurface, without spinning up
+// a real client or the oclif command lifecycle.
+export async function runRedeployWithSecrets(api, params) {
+    const writtenSecrets = [];
+    const succeededKeys = [];
+    for (let i = 0; i < params.secrets.length; i++) {
+        const pair = params.secrets[i];
+        // Pre-compute the keys that come AFTER the current pair so a
+        // set-secret failure can surface every key that was never
+        // attempted, not just the one that failed.
+        const pendingKeys = params.secrets.slice(i + 1).map((p) => p.key);
+        const setResult = await api.setSecret({
+            id: params.id,
+            key: pair.key,
+            value: pair.value,
+        });
+        if (setResult.error) {
+            return {
+                failedKey: pair.key,
+                kind: "error",
+                payload: extractErrorPayload(setResult.error),
+                pendingKeys,
+                stage: "set-secret",
+                succeededKeys,
+            };
+        }
+        const secret = setResult.data?.data;
+        if (!secret) {
+            return {
+                failedKey: pair.key,
+                kind: "error",
+                payload: {
+                    code: "client_error",
+                    message: "Secret write returned no data",
+                },
+                pendingKeys,
+                stage: "set-secret",
+                succeededKeys,
+            };
+        }
+        writtenSecrets.push(secret);
+        succeededKeys.push(pair.key);
+    }
+    const updateResult = await api.updateFunction({
+        code: params.code,
+        id: params.id,
+        ...(params.sourceMap !== undefined ? { sourceMap: params.sourceMap } : {}),
+    });
+    if (updateResult.error) {
+        return {
+            kind: "error",
+            payload: extractErrorPayload(updateResult.error),
+            stage: "redeploy",
+            succeededKeys,
+        };
+    }
+    const redeployed = updateResult.data?.data;
+    if (!redeployed) {
+        return {
+            kind: "error",
+            payload: {
+                code: "client_error",
+                message: "Redeploy returned no data",
+            },
+            stage: "redeploy",
+            succeededKeys,
+        };
+    }
+    return {
+        kind: "ok",
+        result: {
+            redeploy: redeployed,
+            ...(writtenSecrets.length > 0 ? { secrets: writtenSecrets } : {}),
+        },
+    };
+}
 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.`;
+  bundle picks up any secret writes since the last deploy.
+
+  Pass --secret KEY=VALUE (repeatable) to write secrets BEFORE the
+  redeploy fires; one update-function call then refreshes every new
+  binding. Keys must match \`^[A-Z_][A-Z0-9_]*$\` (uppercase letters,
+  digits, underscores; first character is a letter or underscore).
+  With one or more --secret flags the redeploy fans out to multiple
+  API calls (set-secret per pair, then update-function).`;
     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",
+        "<%= config.bin %> functions:redeploy --id <fn-id> --file ./bundle.js --secret OPENAI_KEY=sk-... --secret OWNER_EMAIL=me@example.com",
     ];
     static flags = {
         "api-key": Flags.string({
@@ -48,6 +130,10 @@ class FunctionsRedeployCommand extends Command {
         "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.",
         }),
+        secret: Flags.string({
+            description: `Secret KEY=VALUE to write on the function before the redeploy fires. Repeatable. KEY must match \`^[A-Z_][A-Z0-9_]*$\`; VALUE may contain \`=\` (only the first \`=\` is treated as a delimiter). Each KEY may only appear once per command. Passing one or more --secret flags fans out to set-secret per pair then a single update-function call so the new bindings land in the same redeploy. ${SECRET_FLAG_SECURITY_NOTE}`,
+            multiple: true,
+        }),
         time: Flags.boolean({
             description: TIME_FLAG_DESCRIPTION,
         }),
@@ -55,6 +141,17 @@ class FunctionsRedeployCommand extends Command {
     async run() {
         const { flags } = await this.parse(FunctionsRedeployCommand);
         await runWithTiming(flags.time, async () => {
+            // Validate --secret pairs BEFORE any disk read or API call so
+            // a malformed input fails fast with a clear error and zero
+            // side effects. The fast path (no --secret flags) skips the
+            // secret-write loop entirely.
+            const rawSecrets = flags.secret ?? [];
+            const parsedSecrets = parseSecretFlags(rawSecrets);
+            if (parsedSecrets.kind === "error") {
+                process.stderr.write(`${parsedSecrets.message}\n`);
+                process.exitCode = 1;
+                return;
+            }
             // 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");
@@ -85,27 +182,58 @@ class FunctionsRedeployCommand extends Command {
                 baseUrlOverridden,
                 configDir: this.config.configDir,
             };
-            const result = await updateFunction({
-                path: { id: flags.id },
-                body: {
-                    code,
-                    ...(sourceMap !== undefined ? { sourceMap } : {}),
-                },
-                client: apiClient.client,
-                responseStyle: "fields",
+            // Adapter: thin wrappers around the generated SDK calls,
+            // routed through host 1 (apiClient.client). The function
+            // CRUD and secrets endpoints are not on host 2.
+            const apiSurface = {
+                setSecret: (p) => setFunctionSecret({
+                    body: { value: p.value },
+                    client: apiClient.client,
+                    path: { id: p.id, key: p.key },
+                    responseStyle: "fields",
+                }),
+                updateFunction: (p) => updateFunction({
+                    body: {
+                        code: p.code,
+                        ...(p.sourceMap !== undefined ? { sourceMap: p.sourceMap } : {}),
+                    },
+                    client: apiClient.client,
+                    path: { id: p.id },
+                    responseStyle: "fields",
+                }),
+            };
+            const outcome = await runRedeployWithSecrets(apiSurface, {
+                code,
+                id: flags.id,
+                secrets: parsedSecrets.secrets,
+                ...(sourceMap !== undefined ? { sourceMap } : {}),
             });
-            if (result.error) {
-                const errorPayload = extractErrorPayload(result.error);
-                writeErrorWithHints(errorPayload);
+            if (outcome.kind === "error") {
+                if (outcome.stage === "set-secret") {
+                    const succeeded = outcome.succeededKeys.length > 0
+                        ? outcome.succeededKeys.join(", ")
+                        : "(none)";
+                    const pending = outcome.pendingKeys.length > 0
+                        ? outcome.pendingKeys.join(", ")
+                        : "(none)";
+                    const allMissing = [outcome.failedKey, ...outcome.pendingKeys].join(", ");
+                    process.stderr.write(`Writing secret ${outcome.failedKey} failed before the redeploy; succeeded keys so far: ${succeeded}; keys not yet attempted: ${pending}. The new bundle has NOT been deployed. Re-run \`primitive functions:set-secret\` for each of [${allMissing}], then \`primitive functions:redeploy --id ${flags.id} --file <bundle>\` to push them live.\n`);
+                }
+                else if (outcome.stage === "redeploy") {
+                    const succeeded = outcome.succeededKeys.length > 0
+                        ? outcome.succeededKeys.join(", ")
+                        : "(none)";
+                    process.stderr.write(`Secrets [${succeeded}] were written, but the redeploy step failed; the new bindings are NOT yet live. Re-run \`primitive functions:redeploy --id ${flags.id} --file <bundle>\` once the cause is fixed.\n`);
+                }
+                writeErrorWithHints(outcome.payload);
                 removeStaleSavedCredentialOnUnauthorized({
                     ...authFailureContext,
-                    payload: errorPayload,
+                    payload: outcome.payload,
                 });
                 process.exitCode = 1;
                 return;
             }
-            const envelope = result.data;
-            this.log(JSON.stringify(envelope?.data ?? null, null, 2));
+            this.log(JSON.stringify(outcome.result.redeploy, null, 2));
         });
     }
 }

package/dist/oclif/secret-flags.js

@@ -0,0 +1,59 @@
+// Shared parsing for the `--secret KEY=VALUE` flag used by both
+// functions:deploy and functions:redeploy. Lives in its own module so
+// neither command implicitly depends on the other's file path.
+// Server-side constraint on secret keys. Mirrored client-side so
+// malformed input is rejected before any side-effecting API call.
+export const SECRET_KEY_RE = /^[A-Z_][A-Z0-9_]*$/;
+// Split each `--secret KEY=VALUE` on the FIRST `=`. KEY must match
+// `^[A-Z_][A-Z0-9_]*$`; VALUE may contain `=` (only the first one
+// is treated as a delimiter). Duplicate KEYs are rejected: silently
+// accepting two pairs with the same key would fan out to two
+// setFunctionSecret writes where only the second wins, which is
+// almost always a typo and never the intent.
+export function parseSecretFlags(raw) {
+    const secrets = [];
+    const seenKeys = new Set();
+    for (const entry of raw) {
+        const eq = entry.indexOf("=");
+        if (eq === -1) {
+            return {
+                kind: "error",
+                message: `--secret expects KEY=VALUE (got ${JSON.stringify(entry)}). Example: --secret API_TOKEN=abc123`,
+            };
+        }
+        const key = entry.slice(0, eq);
+        const value = entry.slice(eq + 1);
+        if (key.length === 0) {
+            return {
+                kind: "error",
+                message: `--secret is missing a KEY before '=' (got ${JSON.stringify(entry)}). Example: --secret API_TOKEN=abc123`,
+            };
+        }
+        if (!SECRET_KEY_RE.test(key)) {
+            return {
+                kind: "error",
+                message: `--secret KEY ${JSON.stringify(key)} does not match ${SECRET_KEY_RE.source} (uppercase letters, digits, underscores; first character is a letter or underscore).`,
+            };
+        }
+        if (seenKeys.has(key)) {
+            return {
+                kind: "error",
+                message: `--secret KEY ${JSON.stringify(key)} was passed more than once. Each key may only appear once per command.`,
+            };
+        }
+        seenKeys.add(key);
+        secrets.push({ key, value });
+    }
+    return { kind: "ok", secrets };
+}
+// Shared flag-description copy so both functions:deploy and
+// functions:redeploy advertise the same security caveat and KEY
+// constraints. The shell-history note is the load-bearing piece:
+// CLI flag values land in ~/.bash_history, `ps aux`, and
+// /proc/[pid]/cmdline, so callers handling sensitive values
+// should set them via a shell variable (ideally read via `read -s`
+// or piped from a secrets manager) and reference the variable on
+// the command line. The variable still appears in `ps`-visible
+// argv, but at least the literal value does not get archived in
+// the user's shell history.
+export const SECRET_FLAG_SECURITY_NOTE = 'Note: values passed on the command line are visible in shell history (e.g. ~/.bash_history) and to other users via `ps aux` / /proc/[pid]/cmdline. For sensitive values prefer `--secret KEY="$VAR"` where `$VAR` is set out-of-band (read -s, a secrets manager, etc.).';

package/oclif.manifest.json

@@ -791,10 +791,11 @@
     "functions:deploy": {
       "aliases": [],
       "args": {},
-      "description": "Deploy a new function from a bundled handler file. Agent-grade shortcut for functions:create-function.\n\n  Reads the bundle off disk (--file) instead of forcing the caller to\n  serialize the source into a JSON body. Use the underlying operation\n  `functions:create-function` if you need the full flag surface\n  (raw-body JSON, etc.).",
+      "description": "Deploy a new function from a bundled handler file. Agent-grade shortcut for functions:create-function.\n\n  Reads the bundle off disk (--file) instead of forcing the caller to\n  serialize the source into a JSON body. Use the underlying operation\n  `functions:create-function` if you need the full flag surface\n  (raw-body JSON, etc.).\n\n  Pass --secret KEY=VALUE (repeatable) to seed secret bindings in the\n  same command. Keys must match `^[A-Z_][A-Z0-9_]*$` (uppercase\n  letters, digits, underscores; first character is a letter or\n  underscore). With one or more --secret flags the deploy fans out to\n  multiple API calls: create-function, set-secret per pair, then a\n  final update-function with the same bundle so the running handler\n  picks up the bindings. If a secret write fails after the create\n  step the function exists with whatever secrets succeeded and the\n  redeploy has NOT fired; re-run `primitive functions:set-secret`\n  for the missing keys, then `primitive functions:redeploy` to\n  push them live.",
       "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"
+        "<%= config.bin %> functions:deploy --name forwarder --file ./bundle.js --source-map-file ./bundle.js.map",
+        "<%= config.bin %> functions:deploy --name forwarder --file ./bundle.js --secret OPENAI_KEY=sk-... --secret OWNER_EMAIL=me@example.com"
       ],
       "flags": {
         "api-key": {
@@ -846,6 +847,13 @@
           "multiple": false,
           "type": "option"
         },
+        "secret": {
+          "description": "Secret KEY=VALUE to seed on the deployed function. Repeatable. KEY must match `^[A-Z_][A-Z0-9_]*$`; VALUE may contain `=` (only the first `=` is treated as a delimiter). Each KEY may only appear once per command. Passing one or more --secret flags fans out the deploy to create-function, set-secret per pair, then a final redeploy so the running handler picks up the bindings. Note: values passed on the command line are visible in shell history (e.g. ~/.bash_history) and to other users via `ps aux` / /proc/[pid]/cmdline. For sensitive values prefer `--secret KEY=\"$VAR\"` where `$VAR` is set out-of-band (read -s, a secrets manager, etc.).",
+          "name": "secret",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "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",
@@ -866,10 +874,11 @@
     "functions:redeploy": {
       "aliases": [],
       "args": {},
-      "description": "Update or redeploy a function from a bundled handler file. Agent-grade shortcut for functions:update-function.\n\n  Use to push a new bundle OR to refresh secret bindings into the\n  running handler. The same file is fine for both: the deploy reads\n  the bindings table fresh on every call, so passing the existing\n  bundle picks up any secret writes since the last deploy.",
+      "description": "Update or redeploy a function from a bundled handler file. Agent-grade shortcut for functions:update-function.\n\n  Use to push a new bundle OR to refresh secret bindings into the\n  running handler. The same file is fine for both: the deploy reads\n  the bindings table fresh on every call, so passing the existing\n  bundle picks up any secret writes since the last deploy.\n\n  Pass --secret KEY=VALUE (repeatable) to write secrets BEFORE the\n  redeploy fires; one update-function call then refreshes every new\n  binding. Keys must match `^[A-Z_][A-Z0-9_]*$` (uppercase letters,\n  digits, underscores; first character is a letter or underscore).\n  With one or more --secret flags the redeploy fans out to multiple\n  API calls (set-secret per pair, then update-function).",
       "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"
+        "<%= config.bin %> functions:redeploy --id <fn-id> --file ./bundle.js --source-map-file ./bundle.js.map",
+        "<%= config.bin %> functions:redeploy --id <fn-id> --file ./bundle.js --secret OPENAI_KEY=sk-... --secret OWNER_EMAIL=me@example.com"
       ],
       "flags": {
         "api-key": {
@@ -921,6 +930,13 @@
           "multiple": false,
           "type": "option"
         },
+        "secret": {
+          "description": "Secret KEY=VALUE to write on the function before the redeploy fires. Repeatable. KEY must match `^[A-Z_][A-Z0-9_]*$`; VALUE may contain `=` (only the first `=` is treated as a delimiter). Each KEY may only appear once per command. Passing one or more --secret flags fans out to set-secret per pair then a single update-function call so the new bindings land in the same redeploy. Note: values passed on the command line are visible in shell history (e.g. ~/.bash_history) and to other users via `ps aux` / /proc/[pid]/cmdline. For sensitive values prefer `--secret KEY=\"$VAR\"` where `$VAR` is set out-of-band (read -s, a secrets manager, etc.).",
+          "name": "secret",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "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",
@@ -3611,7 +3627,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)",
@@ -3652,6 +3668,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,
@@ -4329,5 +4366,5 @@
       "enableJsonFlag": false
     }
   },
-  "version": "0.25.0"
+  "version": "0.25.2"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitivedotdev/cli",
-  "version": "0.25.0",
+  "version": "0.25.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,
@@ -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",