@primitivedotdev/cli 0.25.1 → 0.26.0

package/bin/run.js

@@ -1,5 +1,11 @@
 #!/usr/bin/env node
 
 import { execute } from "@oclif/core";
+import { applyProxyAutoDetect } from "../dist/oclif/proxy-auto-detect.js";
+
+// Auto-set NODE_USE_ENV_PROXY=1 when HTTP(S)_PROXY is in the env.
+// Must run before any network init (e.g. before oclif loads commands
+// that touch fetch). See proxy-auto-detect.ts for the full rationale.
+applyProxyAutoDetect();
 
 await execute({ dir: import.meta.url });

package/dist/oclif/api-command.js

@@ -2,6 +2,7 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { Command, Errors, Flags } from "@oclif/core";
 import { operations, PrimitiveApiClient } from "@primitivedotdev/sdk/api";
 import { deleteCliCredentials, resolveCliAuth, } from "./auth.js";
+import { maybeWriteFunctionEndpointRedirect, } from "./endpoints-test-redirect.js";
 export const API_ERROR_CODES = {
     accessDenied: "access_denied",
     authorizationPending: "authorization_pending",
@@ -722,6 +723,29 @@ export function createOperationCommand(operation) {
                         configDir: this.config.configDir,
                         payload: errorPayload,
                     });
+                    // Function-endpoint redirect. POST /endpoints/{id}/test on a
+                    // function-kind endpoint returns `not_found` even though the
+                    // same id IS visible in `endpoints:list-endpoints`. The hook
+                    // looks the id up via listEndpoints; if it matches a
+                    // function-kind row, it prints a redirect to
+                    // `functions:test-function` (with the function id) so the
+                    // caller does not have to translate the id themselves.
+                    // No-op for any other operation, any other error code, or
+                    // when the lookup misses or fails.
+                    const listClient = apiClient.client;
+                    const listEndpointsFn = () => operations.listEndpoints({
+                        client: listClient,
+                        responseStyle: "fields",
+                    });
+                    await maybeWriteFunctionEndpointRedirect({
+                        sdkName: operation.sdkName,
+                        errorCode: extractErrorCode(errorPayload),
+                        endpointId: typeof parsedFlags.id === "string" ? parsedFlags.id : undefined,
+                        listEndpoints: listEndpointsFn,
+                        writeStderr: (chunk) => {
+                            process.stderr.write(chunk);
+                        },
+                    });
                     process.exitCode = 1;
                     return;
                 }

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

@@ -29,7 +29,7 @@ const SDK_VERSION_RANGE = "^0.25.0";
 // 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";
+const CLI_VERSION_RANGE = "^0.26.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.
@@ -51,13 +51,60 @@ 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 isLoop
+// guard below compares incoming mail against this value (in addition
+// to the *.primitive.email suffix) so the handler does not reply to
+// its own outbound traffic when REPLY_FROM is on a non-managed
+// domain.
+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 };
   };
 }
 
+// Loop protection. A deployed Function receives catch-all inbound for
+// the managed *.primitive.email subdomain, which includes bounces and
+// auto-replies generated by its own outbound traffic. Without this
+// guard the handler can respond to its own bounces and create a
+// fan-out loop.
+//
+// The default check returns true when From is on any *.primitive.email
+// address (covers the managed subdomain catch-all, the simple
+// self-reply case, and bounces from mailer-daemon@*.primitive.email)
+// or when From contains REPLY_FROM as a case-insensitive substring.
+// Substring matching is deliberate so display-name forms like
+// "Support <support@example.com>" match a bare-address REPLY_FROM,
+// but it also accepts false positives where REPLY_FROM is a suffix
+// of another address (e.g. REPLY_FROM="info@x.com" matches
+// "mr.info@x.com"). For strict equality, parse the address out of the
+// header and exact-match against REPLY_FROM.
+//
+// Extend this helper if you need stricter detection. Common additions:
+//   - Match the org's signup / account-owner email (not auto-injected
+//     into env today; either bake it into a SIGNUP_EMAIL const or read
+//     it from a secret you set via \`primitive functions:set-secret\`).
+//   - Honor RFC 3834 auto-response headers: skip when
+//     \`event.email.headers["auto-submitted"]\` is anything other than
+//     "no", or when a \`List-Unsubscribe\` / \`Precedence: bulk\` header
+//     is present.
+//   - Track Message-ID / In-Reply-To chains to break ping-pong loops
+//     between two cooperating handlers on different domains.
+export function isLoop(event: EmailReceivedEvent): boolean {
+  // event.email.headers.from is the raw RFC 2822 header value, so it
+  // may be a bare address ("alice@example.com") or a display-name form
+  // ("Alice <alice@example.com>"). Lowercase substring checks match
+  // both shapes without needing to parse the bracketed address.
+  const from = event.email.headers.from?.toLowerCase() ?? "";
+  if (!from) return false;
+  if (from.includes(".primitive.email")) return true;
+  if (from.includes(REPLY_FROM.toLowerCase())) return true;
+  return false;
+}
+
 export default {
   async fetch(
     req: Request,
@@ -74,6 +121,14 @@ export default {
         return Response.json({ ok: true, skipped: event.event });
       }
 
+      // Loop protection runs immediately after the event-type check
+      // (the gateway has already HMAC-verified the request before it
+      // reaches this handler). See isLoop above for what's covered and
+      // how to extend it.
+      if (isLoop(event)) {
+        return Response.json({ ok: true, skipped: "loop" });
+      }
+
       const client = createPrimitiveClient({ apiKey: env.PRIMITIVE_API_KEY });
 
       // Recipient gate
@@ -84,9 +139,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.",
       });

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/endpoints-test-redirect.js

@@ -0,0 +1,94 @@
+// `endpoints:test-endpoint` calls POST /endpoints/{id}/test. The server
+// implementation only resolves http-kind endpoints by url and returns
+// `not_found` for function-kind endpoints (where url is null). The same
+// function-endpoint id IS returned by `endpoints:list-endpoints`, so a
+// caller naturally tries it against test-endpoint and is greeted with
+// "Endpoint not found." Confusing.
+//
+// This helper closes the loop on the CLI side. After test-endpoint
+// returns `not_found`, the dispatcher in `api-command.ts` calls
+// `detectFunctionEndpoint` to see whether the id actually belongs to a
+// function-kind endpoint owned by the caller. If yes, we replace the
+// generic envelope with a redirect to `functions:test-function`,
+// surfacing both the endpoint id and the function id so the caller
+// does not have to look the function id up themselves.
+//
+// `kind` and `function_id` are not currently declared on the OpenAPI
+// `Endpoint` schema (so they are absent from the generated TS types),
+// but they are present in the JSON the server returns. We read them
+// off a loose Record<string, unknown> rather than relying on the
+// generated type, then sanity-check both fields before treating an
+// endpoint as a function endpoint.
+// Returns a `FunctionEndpointMatch` if and only if `endpointId` matches
+// an endpoint in the caller's `listEndpoints` response whose `kind` is
+// `function` and whose `function_id` is a non-empty string. Any other
+// outcome (no match, http-kind match, list call failure, missing
+// fields) returns `null` so the dispatcher falls back to surfacing the
+// original error envelope unchanged.
+export async function detectFunctionEndpoint(endpointId, listEndpoints) {
+    let response;
+    try {
+        response = await listEndpoints();
+    }
+    catch {
+        return null;
+    }
+    if (response.error)
+        return null;
+    const rows = response.data?.data;
+    if (!Array.isArray(rows))
+        return null;
+    // Relies on `listEndpoints` returning every endpoint in a single response.
+    // True today: the operation has `query?: never` in the generated types and
+    // the server returns all rows. If pagination is ever added, an endpoint on
+    // a later page would silently miss the redirect and reduce this to the
+    // original "Endpoint not found" UX. Update this call (filter-by-id or
+    // exhaust-pages) at the same time pagination lands on listEndpoints.
+    for (const row of rows) {
+        if (!row || typeof row !== "object")
+            continue;
+        if (row.id !== endpointId)
+            continue;
+        if (row.kind !== "function")
+            return null;
+        const functionId = row.function_id;
+        if (typeof functionId !== "string" || functionId.length === 0)
+            return null;
+        return { endpointId, functionId };
+    }
+    return null;
+}
+// Stderr copy printed when the dispatcher detects the
+// `endpoints:test-endpoint` `not_found` was really a function-kind
+// endpoint. Surfaces both ids so the caller does not have to run
+// `endpoints:list-endpoints` again to find the function_id. Returned
+// as a string rather than written here so the call site controls the
+// stream (stderr, in practice) and the tests can assert on the value.
+export function formatFunctionEndpointRedirect(match) {
+    return [
+        "This is a function endpoint. Function endpoints are tested differently. Run:",
+        "",
+        `    primitive functions:test-function --id ${match.functionId}`,
+        "",
+        `(pass the function id, not the endpoint id. endpoint_id=${match.endpointId} function_id=${match.functionId})`,
+    ].join("\n");
+}
+// Post-error hook: if the operation that just failed is
+// `endpoints:test-endpoint`, the failure is a `not_found`, and the
+// caller's id matches a function-kind endpoint they own, print a
+// redirect to `functions:test-function`. Returns the resolved match
+// so the caller (and the test) can assert the branch taken without
+// scraping stderr.
+export async function maybeWriteFunctionEndpointRedirect(inputs) {
+    if (inputs.sdkName !== "testEndpoint")
+        return null;
+    if (inputs.errorCode !== "not_found")
+        return null;
+    if (!inputs.endpointId)
+        return null;
+    const match = await detectFunctionEndpoint(inputs.endpointId, inputs.listEndpoints);
+    if (!match)
+        return null;
+    inputs.writeStderr(`${formatFunctionEndpointRedirect(match)}\n`);
+    return match;
+}

package/dist/oclif/proxy-auto-detect.js

@@ -0,0 +1,64 @@
+// Auto-detect proxy environment variables at CLI startup so users
+// behind a corporate proxy don't have to prefix every command with
+// `NODE_USE_ENV_PROXY=1`.
+//
+// Node 22+ ignores `HTTP_PROXY` / `HTTPS_PROXY` for the built-in
+// `fetch` / undici client unless `NODE_USE_ENV_PROXY=1` is set. That
+// turns a one-line proxy export into per-command friction: every CLI
+// invocation either inherits the prefix or fails with `ENETUNREACH`.
+//
+// This module is called once from `bin/run.js` before any network
+// initialization. If any of the standard proxy env vars are set AND
+// `NODE_USE_ENV_PROXY` is not already set explicitly, it sets it to
+// `1` for the current process and prints a one-time stderr hint so
+// the user knows what changed.
+//
+// An explicit `NODE_USE_ENV_PROXY` value (including `0`, `""`, etc.)
+// is always respected: if the user has chosen to disable proxy use
+// for this invocation, we don't override that choice.
+const PROXY_ENV_VARS = [
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "http_proxy",
+    "https_proxy",
+];
+// Module-level latch so the hint is printed at most once per process
+// even if `applyProxyAutoDetect` is called more than once (e.g. from
+// tests, or if a future entry point routes through it twice).
+let hintPrinted = false;
+// Test-only: reset the one-shot hint latch so each test case can
+// observe the first-call behavior independently.
+export function _resetHintLatchForTest() {
+    hintPrinted = false;
+}
+function detectProxyVars(env) {
+    return PROXY_ENV_VARS.filter((name) => {
+        const value = env[name];
+        return typeof value === "string" && value.length > 0;
+    });
+}
+export function applyProxyAutoDetect(options = {}) {
+    const env = options.env ?? process.env;
+    const stderr = options.stderr ?? process.stderr;
+    const detectedVars = detectProxyVars(env);
+    if (detectedVars.length === 0) {
+        return { applied: false, detectedVars: [], reason: "no_proxy_env" };
+    }
+    // Respect any explicit `NODE_USE_ENV_PROXY` value, including `0`
+    // or an empty string. The user has made a deliberate choice and
+    // auto-detection must not silently override it.
+    if (Object.hasOwn(env, "NODE_USE_ENV_PROXY")) {
+        return {
+            applied: false,
+            detectedVars,
+            reason: "node_use_env_proxy_already_set",
+        };
+    }
+    env.NODE_USE_ENV_PROXY = "1";
+    if (!hintPrinted) {
+        hintPrinted = true;
+        const names = detectedVars.join("/");
+        stderr.write(`primitive: proxy detected via ${names}, NODE_USE_ENV_PROXY=1 set automatically\n`);
+    }
+    return { applied: true, detectedVars, reason: "applied" };
+}

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",
@@ -4350,5 +4366,5 @@
       "enableJsonFlag": false
     }
   },
-  "version": "0.25.1"
+  "version": "0.26.0"
 }

package/package.json

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