@primitivedotdev/cli 0.35.1 → 0.36.0

package/dist/{cli-config-DREZ2BxT.js → cli-config-D7wN_PBc.js}

@@ -1090,6 +1090,24 @@ function acquireCliCredentialsLock(configDir, options = {}) {
 		});
 	};
 }
+/**
+* Detect the PRIMITIVE_KEY vs PRIMITIVE_API_KEY rename trap.
+*
+* AGX feedback: users on older docs (or coming from other tools) set
+* `PRIMITIVE_KEY` and then cannot figure out why the CLI reports no
+* API key. The CLI reads `PRIMITIVE_API_KEY` only. Returns a stderr
+* hint when `PRIMITIVE_KEY` is set but `PRIMITIVE_API_KEY` is not,
+* otherwise null. Exported as a helper so both `doctor` and the
+* general auth-resolution path surface the same guidance from the
+* first command the user runs, instead of forcing them to discover
+* the rename via `doctor` after the fact.
+*/
+function detectPrimitiveKeyEnvMisname(env = process.env) {
+	const primitiveKey = env.PRIMITIVE_KEY;
+	const primitiveApiKey = env.PRIMITIVE_API_KEY;
+	if ((primitiveKey?.length ?? 0) > 0 && (primitiveApiKey?.length ?? 0) === 0) return "PRIMITIVE_KEY is set but the CLI reads PRIMITIVE_API_KEY. Rename your env var, or re-run with PRIMITIVE_API_KEY=$PRIMITIVE_KEY.";
+	return null;
+}
 function resolveCliAuth(params) {
 	const apiKey = params.apiKey?.trim();
 	const apiBaseUrl = normalizeApiBaseUrl(params.apiBaseUrl);
@@ -1293,4 +1311,4 @@ function redactCliEnvironment(environment) {
 	};
 }
 //#endregion
-export { createConfig as A, chatStatePath as C, saveActiveChatState as D, loadChatConversationByLocalId as E, PrimitiveApiClient as O, saveCliCredentials as S, loadActiveChatState as T, deleteCliCredentials as _, normalizeCliEnvironmentName as a, normalizeApiBaseUrl as b, resolveConfigEnvironment as c, validateCliHeaderName as d, validateCliHeaderValue as f, credentialsPath as g, credentialsLockPath as h, loadCliConfig as i, createClient as k, saveCliConfig as l, cliAccessTokenExpiresAt as m, deleteCliConfig as n, redactCliEnvironment as o, acquireCliCredentialsLock as p, emptyCliConfig as r, removeCliEnvironment as s, DEFAULT_ENVIRONMENT as t, upsertCliEnvironment as u, deleteCliCredentialsLock as v, deleteChatState as w, resolveCliAuth as x, loadCliCredentials as y };
+export { createClient as A, saveCliCredentials as C, loadChatConversationByLocalId as D, loadActiveChatState as E, saveActiveChatState as O, resolveCliAuth as S, deleteChatState as T, deleteCliCredentials as _, normalizeCliEnvironmentName as a, loadCliCredentials as b, resolveConfigEnvironment as c, validateCliHeaderName as d, validateCliHeaderValue as f, credentialsPath as g, credentialsLockPath as h, loadCliConfig as i, createConfig as j, PrimitiveApiClient as k, saveCliConfig as l, cliAccessTokenExpiresAt as m, deleteCliConfig as n, redactCliEnvironment as o, acquireCliCredentialsLock as p, emptyCliConfig as r, removeCliEnvironment as s, DEFAULT_ENVIRONMENT as t, upsertCliEnvironment as u, deleteCliCredentialsLock as v, chatStatePath as w, normalizeApiBaseUrl as x, detectPrimitiveKeyEnvMisname as y };

package/dist/oclif/index.js

@@ -1,4 +1,4 @@
-import { A as createConfig, C as chatStatePath, D as saveActiveChatState, E as loadChatConversationByLocalId, O as PrimitiveApiClient, S as saveCliCredentials, T as loadActiveChatState, _ as deleteCliCredentials, a as normalizeCliEnvironmentName, b as normalizeApiBaseUrl, c as resolveConfigEnvironment, d as validateCliHeaderName, f as validateCliHeaderValue, g as credentialsPath, h as credentialsLockPath, i as loadCliConfig, k as createClient, l as saveCliConfig, m as cliAccessTokenExpiresAt, n as deleteCliConfig, o as redactCliEnvironment, p as acquireCliCredentialsLock, r as emptyCliConfig, s as removeCliEnvironment, u as upsertCliEnvironment, v as deleteCliCredentialsLock, w as deleteChatState, x as resolveCliAuth, y as loadCliCredentials } from "../cli-config-DREZ2BxT.js";
+import { A as createClient, C as saveCliCredentials, D as loadChatConversationByLocalId, E as loadActiveChatState, O as saveActiveChatState, S as resolveCliAuth, T as deleteChatState, _ as deleteCliCredentials, a as normalizeCliEnvironmentName, b as loadCliCredentials, c as resolveConfigEnvironment, d as validateCliHeaderName, f as validateCliHeaderValue, g as credentialsPath, h as credentialsLockPath, i as loadCliConfig, j as createConfig, k as PrimitiveApiClient, l as saveCliConfig, m as cliAccessTokenExpiresAt, n as deleteCliConfig, o as redactCliEnvironment, p as acquireCliCredentialsLock, r as emptyCliConfig, s as removeCliEnvironment, u as upsertCliEnvironment, v as deleteCliCredentialsLock, w as chatStatePath, x as normalizeApiBaseUrl, y as detectPrimitiveKeyEnvMisname } from "../cli-config-D7wN_PBc.js";
 import { Args, Command, Errors, Flags, ux } from "@oclif/core";
 import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
@@ -44,8 +44,10 @@ var sdk_gen_exports = /* @__PURE__ */ __exportAll({
 	getConversation: () => getConversation,
 	getEmail: () => getEmail,
 	getFunction: () => getFunction,
+	getFunctionRouting: () => getFunctionRouting,
 	getFunctionTestRunTrace: () => getFunctionTestRunTrace,
 	getInboxStatus: () => getInboxStatus,
+	getOrgRoutingTopology: () => getOrgRoutingTopology,
 	getSendPermissions: () => getSendPermissions,
 	getSentEmail: () => getSentEmail,
 	getStorageStats: () => getStorageStats,
@@ -70,12 +72,14 @@ var sdk_gen_exports = /* @__PURE__ */ __exportAll({
 	searchEmails: () => searchEmails,
 	semanticSearch: () => semanticSearch,
 	sendEmail: () => sendEmail,
+	setFunctionRoute: () => setFunctionRoute,
 	setFunctionSecret: () => setFunctionSecret,
 	startAgentSignup: () => startAgentSignup,
 	startCliLogin: () => startCliLogin,
 	startCliSignup: () => startCliSignup,
 	testEndpoint: () => testEndpoint,
 	testFunction: () => testFunction,
+	unsetFunctionRoute: () => unsetFunctionRoute,
 	updateAccount: () => updateAccount,
 	updateDomain: () => updateDomain,
 	updateEndpoint: () => updateEndpoint,
@@ -1102,11 +1106,13 @@ const listFunctions = (options) => (options?.client ?? client).get({
 * attempt, and sent to the runtime so stack traces can resolve to
 * original source files.
 *
-* **Auto-wiring.** On successful deploy, Primitive automatically
-* creates a webhook endpoint that delivers inbound mail to the
-* function. There is nothing to configure on the Endpoints API
-* for this to work; the internal runtime URL is not returned by
-* the API and is not a customer-facing integration surface.
+* **Routing.** On successful deploy, the function code is live
+* in the runtime, but inbound mail will not reach it until at
+* least one route is bound. Routes are managed from the Primitive
+* dashboard. A `deploy_status` of `deployed` means the script is
+* installed, not that the function is receiving mail. The
+* internal runtime URL is not returned by the API and is not a
+* customer-facing integration surface.
 *
 * **Secrets.** New functions ship with the managed secrets
 * (`PRIMITIVE_WEBHOOK_SECRET`, `PRIMITIVE_API_KEY`,
@@ -1131,7 +1137,7 @@ const createFunction = (options) => (options.client ?? client).post({
 * Delete a function
 *
 * Soft-deletes the function row, removes the script from the edge
-* runtime, and deactivates the auto-wired webhook endpoint so no
+* runtime, and deactivates any route bound to this function so no
 * further inbound mail is delivered. Past deploy history,
 * invocations, and logs are retained.
 *
@@ -1248,6 +1254,80 @@ const getFunctionTestRunTrace = (options) => (options.client ?? client).get({
 	...options
 });
 /**
+* Get the org's function routing topology
+*
+* Returns a single snapshot of how inbound mail is routed across
+* this org's active domains and functions: which active domain has
+* which function bound, the org's fallback function (if any), and
+* every deployed function with no route bound. Use this to answer
+* "which of my functions actually receive mail?" diagnostically.
+*
+*/
+const getOrgRoutingTopology = (options) => (options?.client ?? client).get({
+	security: [{
+		scheme: "bearer",
+		type: "http"
+	}],
+	url: "/functions/routing-topology",
+	...options
+});
+/**
+* Get a function's current route binding
+*
+* Returns the endpoint binding for the function, or null when no
+* route is currently bound. The binding identifies whether the
+* function receives mail for a specific domain (scoped) or for any
+* active domain that has no scoped binding (fallback).
+*
+*/
+const getFunctionRouting = (options) => (options.client ?? client).get({
+	security: [{
+		scheme: "bearer",
+		type: "http"
+	}],
+	url: "/functions/{id}/routing",
+	...options
+});
+/**
+* Unbind any route from a function
+*
+* Deactivates every active endpoint bound to this function. The
+* function stays deployed but stops receiving inbound mail. Safe
+* to call when no route is currently bound (no-op).
+*
+*/
+const unsetFunctionRoute = (options) => (options.client ?? client).delete({
+	security: [{
+		scheme: "bearer",
+		type: "http"
+	}],
+	url: "/functions/{id}/route",
+	...options
+});
+/**
+* Bind a route to a function
+*
+* Binds inbound mail to this function. The route target is either
+* a specific verified domain (scoped) or the org's fallback (any
+* active domain with no scoped binding). If another function is
+* already bound at the target, returns a `conflict` envelope
+* describing the holder; re-issue with `takeover: true` to
+* deactivate that prior binding and install this one.
+*
+*/
+const setFunctionRoute = (options) => (options.client ?? client).put({
+	security: [{
+		scheme: "bearer",
+		type: "http"
+	}],
+	url: "/functions/{id}/route",
+	...options,
+	headers: {
+		...options.body !== void 0 && { "Content-Type": "application/json" },
+		...options.headers
+	}
+});
+/**
 * List a function's secrets
 *
 * Returns metadata for every secret bound to the function, with
@@ -3029,7 +3109,7 @@ const openapiDocument = {
 			"post": {
 				"operationId": "createFunction",
 				"summary": "Deploy a function",
-				"description": "Creates and deploys a new function. The handler must be a single\nESM module whose default export is an object with an async\n`fetch(request, env)` method (Workers-style). Primitive signs\neach delivery and forwards the `Primitive-Signature` header to\nthe handler. Verify the raw request body with\n`PRIMITIVE_WEBHOOK_SECRET` before parsing JSON; after verification\nthe request body parses to an `email.received` event (see\n`EmailReceivedEvent` and the Webhook payload section for the full\nschema). Code is bundled before being uploaded; ship a single\nself-contained file rather than relying on external imports.\n\n**Code limits.** `code` is capped at 1 MiB UTF-8. `sourceMap`\n(optional) is capped at 5 MiB UTF-8, stored with each deployment\nattempt, and sent to the runtime so stack traces can resolve to\noriginal source files.\n\n**Auto-wiring.** On successful deploy, Primitive automatically\ncreates a webhook endpoint that delivers inbound mail to the\nfunction. There is nothing to configure on the Endpoints API\nfor this to work; the internal runtime URL is not returned by\nthe API and is not a customer-facing integration surface.\n\n**Secrets.** New functions ship with the managed secrets\n(`PRIMITIVE_WEBHOOK_SECRET`, `PRIMITIVE_API_KEY`,\n`PRIMITIVE_API_BASE_URL`) already bound. Add user-set secrets via\n`POST /functions/{id}/secrets`; secret writes only land in the\nrunning handler on the next redeploy.\n",
+				"description": "Creates and deploys a new function. The handler must be a single\nESM module whose default export is an object with an async\n`fetch(request, env)` method (Workers-style). Primitive signs\neach delivery and forwards the `Primitive-Signature` header to\nthe handler. Verify the raw request body with\n`PRIMITIVE_WEBHOOK_SECRET` before parsing JSON; after verification\nthe request body parses to an `email.received` event (see\n`EmailReceivedEvent` and the Webhook payload section for the full\nschema). Code is bundled before being uploaded; ship a single\nself-contained file rather than relying on external imports.\n\n**Code limits.** `code` is capped at 1 MiB UTF-8. `sourceMap`\n(optional) is capped at 5 MiB UTF-8, stored with each deployment\nattempt, and sent to the runtime so stack traces can resolve to\noriginal source files.\n\n**Routing.** On successful deploy, the function code is live\nin the runtime, but inbound mail will not reach it until at\nleast one route is bound. Routes are managed from the Primitive\ndashboard. A `deploy_status` of `deployed` means the script is\ninstalled, not that the function is receiving mail. The\ninternal runtime URL is not returned by the API and is not a\ncustomer-facing integration surface.\n\n**Secrets.** New functions ship with the managed secrets\n(`PRIMITIVE_WEBHOOK_SECRET`, `PRIMITIVE_API_KEY`,\n`PRIMITIVE_API_BASE_URL`) already bound. Add user-set secrets via\n`POST /functions/{id}/secrets`; secret writes only land in the\nrunning handler on the next redeploy.\n",
 				"tags": ["Functions"],
 				"requestBody": {
 					"required": true,
@@ -3108,7 +3188,7 @@ const openapiDocument = {
 			"delete": {
 				"operationId": "deleteFunction",
 				"summary": "Delete a function",
-				"description": "Soft-deletes the function row, removes the script from the edge\nruntime, and deactivates the auto-wired webhook endpoint so no\nfurther inbound mail is delivered. Past deploy history,\ninvocations, and logs are retained.\n\nReturns 502 if the runtime delete fails partway; the function\nrow stays in place and the call is safe to retry until it\nsucceeds.\n",
+				"description": "Soft-deletes the function row, removes the script from the edge\nruntime, and deactivates any route bound to this function so no\nfurther inbound mail is delivered. Past deploy history,\ninvocations, and logs are retained.\n\nReturns 502 if the runtime delete fails partway; the function\nrow stays in place and the call is safe to retry until it\nsucceeds.\n",
 				"tags": ["Functions"],
 				"responses": {
 					"200": { "$ref": "#/components/responses/Deleted" },
@@ -3193,6 +3273,92 @@ const openapiDocument = {
 				}
 			}
 		},
+		"/functions/routing-topology": { "get": {
+			"operationId": "getOrgRoutingTopology",
+			"summary": "Get the org's function routing topology",
+			"description": "Returns a single snapshot of how inbound mail is routed across\nthis org's active domains and functions: which active domain has\nwhich function bound, the org's fallback function (if any), and\nevery deployed function with no route bound. Use this to answer\n\"which of my functions actually receive mail?\" diagnostically.\n",
+			"tags": ["Functions"],
+			"responses": {
+				"200": {
+					"description": "Routing topology",
+					"content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, {
+						"type": "object",
+						"properties": { "data": { "$ref": "#/components/schemas/RoutingTopology" } }
+					}] } } }
+				},
+				"401": { "$ref": "#/components/responses/Unauthorized" },
+				"403": { "$ref": "#/components/responses/Forbidden" }
+			}
+		} },
+		"/functions/{id}/routing": {
+			"parameters": [{ "$ref": "#/components/parameters/ResourceId" }],
+			"get": {
+				"operationId": "getFunctionRouting",
+				"summary": "Get a function's current route binding",
+				"description": "Returns the endpoint binding for the function, or null when no\nroute is currently bound. The binding identifies whether the\nfunction receives mail for a specific domain (scoped) or for any\nactive domain that has no scoped binding (fallback).\n",
+				"tags": ["Functions"],
+				"responses": {
+					"200": {
+						"description": "Function routing",
+						"content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, {
+							"type": "object",
+							"properties": { "data": { "oneOf": [{ "$ref": "#/components/schemas/FunctionRouting" }, { "type": "null" }] } }
+						}] } } }
+					},
+					"401": { "$ref": "#/components/responses/Unauthorized" },
+					"404": { "$ref": "#/components/responses/NotFound" }
+				}
+			}
+		},
+		"/functions/{id}/route": {
+			"parameters": [{ "$ref": "#/components/parameters/ResourceId" }],
+			"put": {
+				"operationId": "setFunctionRoute",
+				"summary": "Bind a route to a function",
+				"description": "Binds inbound mail to this function. The route target is either\na specific verified domain (scoped) or the org's fallback (any\nactive domain with no scoped binding). If another function is\nalready bound at the target, returns a `conflict` envelope\ndescribing the holder; re-issue with `takeover: true` to\ndeactivate that prior binding and install this one.\n",
+				"tags": ["Functions"],
+				"requestBody": {
+					"required": true,
+					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/FunctionRouteBody" } } }
+				},
+				"responses": {
+					"200": {
+						"description": "Route bound, or conflict requiring takeover",
+						"content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, {
+							"type": "object",
+							"properties": { "data": { "$ref": "#/components/schemas/FunctionRouteResult" } }
+						}] } } }
+					},
+					"400": { "$ref": "#/components/responses/ValidationError" },
+					"401": { "$ref": "#/components/responses/Unauthorized" },
+					"404": { "$ref": "#/components/responses/NotFound" }
+				}
+			},
+			"delete": {
+				"operationId": "unsetFunctionRoute",
+				"summary": "Unbind any route from a function",
+				"description": "Deactivates every active endpoint bound to this function. The\nfunction stays deployed but stops receiving inbound mail. Safe\nto call when no route is currently bound (no-op).\n",
+				"tags": ["Functions"],
+				"responses": {
+					"200": {
+						"description": "Route unbound",
+						"content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, {
+							"type": "object",
+							"properties": { "data": {
+								"type": "object",
+								"properties": { "unrouted": {
+									"type": "boolean",
+									"enum": [true]
+								} },
+								"required": ["unrouted"]
+							} }
+						}] } } }
+					},
+					"401": { "$ref": "#/components/responses/Unauthorized" },
+					"404": { "$ref": "#/components/responses/NotFound" }
+				}
+			}
+		},
 		"/functions/{id}/secrets": {
 			"parameters": [{ "$ref": "#/components/parameters/ResourceId" }],
 			"get": {
@@ -6718,6 +6884,178 @@ const openapiDocument = {
 					"trace_url"
 				]
 			},
+			"FunctionRouting": {
+				"type": "object",
+				"description": "A single route binding for a function. `domain` is null when the\nbinding is the org's fallback (any active domain without a scoped\nbinding); otherwise it carries the scoped domain. `rules` is\nreserved for future routing predicates.\n",
+				"properties": {
+					"endpoint_id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"enabled": { "type": "boolean" },
+					"domain": {
+						"type": ["object", "null"],
+						"properties": {
+							"id": {
+								"type": "string",
+								"format": "uuid"
+							},
+							"name": { "type": ["string", "null"] }
+						},
+						"required": ["id"]
+					},
+					"rules": {
+						"type": "object",
+						"description": "Future routing predicates. Currently empty."
+					},
+					"delivery_count": { "type": "integer" },
+					"success_count": { "type": "integer" },
+					"failure_count": { "type": "integer" },
+					"consecutive_fails": { "type": "integer" },
+					"last_delivery_at": {
+						"type": ["string", "null"],
+						"format": "date-time"
+					},
+					"last_success_at": {
+						"type": ["string", "null"],
+						"format": "date-time"
+					},
+					"last_failure_at": {
+						"type": ["string", "null"],
+						"format": "date-time"
+					}
+				},
+				"required": [
+					"endpoint_id",
+					"enabled",
+					"domain",
+					"rules"
+				]
+			},
+			"RoutingTopology": {
+				"type": "object",
+				"description": "Org-wide map of function routing: which domain points at which\nfunction, the org's fallback binding (if any), and every\ndeployed function with no route currently bound.\n",
+				"properties": {
+					"domains": {
+						"type": "array",
+						"items": {
+							"type": "object",
+							"properties": {
+								"domain_id": {
+									"type": "string",
+									"format": "uuid"
+								},
+								"domain": { "type": "string" },
+								"routed_function": {
+									"type": ["object", "null"],
+									"properties": {
+										"id": {
+											"type": "string",
+											"format": "uuid"
+										},
+										"name": { "type": "string" }
+									},
+									"required": ["id", "name"]
+								},
+								"endpoint_enabled": { "type": ["boolean", "null"] }
+							},
+							"required": [
+								"domain_id",
+								"domain",
+								"routed_function",
+								"endpoint_enabled"
+							]
+						}
+					},
+					"fallback_function": {
+						"type": ["object", "null"],
+						"properties": {
+							"id": {
+								"type": "string",
+								"format": "uuid"
+							},
+							"name": { "type": "string" }
+						},
+						"required": ["id", "name"]
+					},
+					"fallback_enabled": { "type": ["boolean", "null"] },
+					"unrouted_functions": {
+						"type": "array",
+						"items": {
+							"type": "object",
+							"properties": {
+								"id": {
+									"type": "string",
+									"format": "uuid"
+								},
+								"name": { "type": "string" }
+							},
+							"required": ["id", "name"]
+						}
+					}
+				},
+				"required": [
+					"domains",
+					"fallback_function",
+					"fallback_enabled",
+					"unrouted_functions"
+				]
+			},
+			"FunctionRouteBody": {
+				"type": "object",
+				"description": "Target for a route binding. Either a specific verified domain\n(scoped) or the org-wide fallback. Pass `takeover: true` to\ndeactivate any conflicting binding before installing this one.\n",
+				"properties": {
+					"target": { "oneOf": [{
+						"type": "object",
+						"properties": {
+							"kind": {
+								"type": "string",
+								"enum": ["domain"]
+							},
+							"domainId": {
+								"type": "string",
+								"format": "uuid"
+							}
+						},
+						"required": ["kind", "domainId"]
+					}, {
+						"type": "object",
+						"properties": { "kind": {
+							"type": "string",
+							"enum": ["fallback"]
+						} },
+						"required": ["kind"]
+					}] },
+					"takeover": {
+						"type": "boolean",
+						"description": "When true, deactivate any conflicting binding before installing this one."
+					}
+				},
+				"required": ["target"]
+			},
+			"FunctionRouteResult": {
+				"type": "object",
+				"description": "On success, carries the new `routing`. On conflict, carries\n`conflict` describing the binding holder so the caller can\nre-issue with `takeover: true`.\n",
+				"properties": {
+					"routing": { "oneOf": [{ "$ref": "#/components/schemas/FunctionRouting" }, { "type": "null" }] },
+					"conflict": {
+						"type": "object",
+						"properties": {
+							"kind": {
+								"type": "string",
+								"enum": ["http", "function"]
+							},
+							"functionId": {
+								"type": ["string", "null"],
+								"format": "uuid"
+							},
+							"functionName": { "type": ["string", "null"] },
+							"url": { "type": ["string", "null"] }
+						},
+						"required": ["kind"]
+					}
+				}
+			},
 			"FunctionTestRunState": {
 				"type": "string",
 				"description": "High-level state for a function test run trace:\n  - `send_failed`: the initial test email send failed.\n  - `waiting_for_send`: the test run was created but no send result has been recorded yet.\n  - `waiting_for_inbound`: the test send was queued and the matching inbound email has not arrived yet.\n  - `waiting_for_function`: the inbound email arrived and webhook/function processing is still in flight.\n  - `completed`: the function webhook completed successfully.\n  - `failed`: webhook delivery exhausted retries.\n",
@@ -10433,7 +10771,7 @@ const operationManifest = [
 		"binaryResponse": false,
 		"bodyRequired": true,
 		"command": "create-function",
-		"description": "Creates and deploys a new function. The handler must be a single\nESM module whose default export is an object with an async\n`fetch(request, env)` method (Workers-style). Primitive signs\neach delivery and forwards the `Primitive-Signature` header to\nthe handler. Verify the raw request body with\n`PRIMITIVE_WEBHOOK_SECRET` before parsing JSON; after verification\nthe request body parses to an `email.received` event (see\n`EmailReceivedEvent` and the Webhook payload section for the full\nschema). Code is bundled before being uploaded; ship a single\nself-contained file rather than relying on external imports.\n\n**Code limits.** `code` is capped at 1 MiB UTF-8. `sourceMap`\n(optional) is capped at 5 MiB UTF-8, stored with each deployment\nattempt, and sent to the runtime so stack traces can resolve to\noriginal source files.\n\n**Auto-wiring.** On successful deploy, Primitive automatically\ncreates a webhook endpoint that delivers inbound mail to the\nfunction. There is nothing to configure on the Endpoints API\nfor this to work; the internal runtime URL is not returned by\nthe API and is not a customer-facing integration surface.\n\n**Secrets.** New functions ship with the managed secrets\n(`PRIMITIVE_WEBHOOK_SECRET`, `PRIMITIVE_API_KEY`,\n`PRIMITIVE_API_BASE_URL`) already bound. Add user-set secrets via\n`POST /functions/{id}/secrets`; secret writes only land in the\nrunning handler on the next redeploy.\n",
+		"description": "Creates and deploys a new function. The handler must be a single\nESM module whose default export is an object with an async\n`fetch(request, env)` method (Workers-style). Primitive signs\neach delivery and forwards the `Primitive-Signature` header to\nthe handler. Verify the raw request body with\n`PRIMITIVE_WEBHOOK_SECRET` before parsing JSON; after verification\nthe request body parses to an `email.received` event (see\n`EmailReceivedEvent` and the Webhook payload section for the full\nschema). Code is bundled before being uploaded; ship a single\nself-contained file rather than relying on external imports.\n\n**Code limits.** `code` is capped at 1 MiB UTF-8. `sourceMap`\n(optional) is capped at 5 MiB UTF-8, stored with each deployment\nattempt, and sent to the runtime so stack traces can resolve to\noriginal source files.\n\n**Routing.** On successful deploy, the function code is live\nin the runtime, but inbound mail will not reach it until at\nleast one route is bound. Routes are managed from the Primitive\ndashboard. A `deploy_status` of `deployed` means the script is\ninstalled, not that the function is receiving mail. The\ninternal runtime URL is not returned by the API and is not a\ncustomer-facing integration surface.\n\n**Secrets.** New functions ship with the managed secrets\n(`PRIMITIVE_WEBHOOK_SECRET`, `PRIMITIVE_API_KEY`,\n`PRIMITIVE_API_BASE_URL`) already bound. Add user-set secrets via\n`POST /functions/{id}/secrets`; secret writes only land in the\nrunning handler on the next redeploy.\n",
 		"hasJsonBody": true,
 		"method": "POST",
 		"operationId": "createFunction",
@@ -10569,7 +10907,7 @@ const operationManifest = [
 		"binaryResponse": false,
 		"bodyRequired": false,
 		"command": "delete-function",
-		"description": "Soft-deletes the function row, removes the script from the edge\nruntime, and deactivates the auto-wired webhook endpoint so no\nfurther inbound mail is delivered. Past deploy history,\ninvocations, and logs are retained.\n\nReturns 502 if the runtime delete fails partway; the function\nrow stays in place and the call is safe to retry until it\nsucceeds.\n",
+		"description": "Soft-deletes the function row, removes the script from the edge\nruntime, and deactivates any route bound to this function so no\nfurther inbound mail is delivered. Past deploy history,\ninvocations, and logs are retained.\n\nReturns 502 if the runtime delete fails partway; the function\nrow stays in place and the call is safe to retry until it\nsucceeds.\n",
 		"hasJsonBody": false,
 		"method": "DELETE",
 		"operationId": "deleteFunction",
@@ -10693,62 +11031,133 @@ const operationManifest = [
 	{
 		"binaryResponse": false,
 		"bodyRequired": false,
-		"command": "get-function-test-run-trace",
-		"description": "Returns the current end-to-end trace for a function test run.\nThe trace is intentionally partial while the test is still in\nflight: callers can poll this endpoint and watch it fill in\nfrom send -> inbound -> webhook deliveries -> outbound\nrequests, logs, and replies.\n",
+		"command": "get-function-routing",
+		"description": "Returns the endpoint binding for the function, or null when no\nroute is currently bound. The binding identifies whether the\nfunction receives mail for a specific domain (scoped) or for any\nactive domain that has no scoped binding (fallback).\n",
 		"hasJsonBody": false,
 		"method": "GET",
-		"operationId": "getFunctionTestRunTrace",
-		"path": "/functions/{id}/test-runs/{run_id}/trace",
+		"operationId": "getFunctionRouting",
+		"path": "/functions/{id}/routing",
 		"pathParams": [{
 			"description": "Resource UUID",
 			"enum": null,
 			"name": "id",
 			"required": true,
 			"type": "string"
-		}, {
-			"description": "Function test run id returned by POST /functions/{id}/test.",
-			"enum": null,
-			"name": "run_id",
-			"required": true,
-			"type": "string"
 		}],
 		"queryParams": [],
 		"requestSchema": null,
-		"responseSchema": {
+		"responseSchema": { "oneOf": [{
 			"type": "object",
-			"description": "End-to-end trace for a `POST /functions/{id}/test` run. The\nshape is stable, but many nested sections are null or empty\nuntil the corresponding phase has happened.\n",
+			"description": "A single route binding for a function. `domain` is null when the\nbinding is the org's fallback (any active domain without a scoped\nbinding); otherwise it carries the scoped domain. `rules` is\nreserved for future routing predicates.\n",
 			"properties": {
-				"state": {
+				"endpoint_id": {
 					"type": "string",
-					"description": "High-level state for a function test run trace:\n  - `send_failed`: the initial test email send failed.\n  - `waiting_for_send`: the test run was created but no send result has been recorded yet.\n  - `waiting_for_inbound`: the test send was queued and the matching inbound email has not arrived yet.\n  - `waiting_for_function`: the inbound email arrived and webhook/function processing is still in flight.\n  - `completed`: the function webhook completed successfully.\n  - `failed`: webhook delivery exhausted retries.\n",
-					"enum": [
-						"send_failed",
-						"waiting_for_send",
-						"waiting_for_inbound",
-						"waiting_for_function",
-						"completed",
-						"failed"
-					]
+					"format": "uuid"
 				},
-				"test_run": {
-					"type": "object",
+				"enabled": { "type": "boolean" },
+				"domain": {
+					"type": ["object", "null"],
 					"properties": {
 						"id": {
 							"type": "string",
 							"format": "uuid"
 						},
-						"function_id": {
-							"type": "string",
-							"format": "uuid"
-						},
-						"inbound_domain": { "type": "string" },
-						"to": { "type": "string" },
-						"from": { "type": "string" },
-						"subject": { "type": "string" },
-						"poll_since": {
-							"type": "string",
-							"format": "date-time"
-						},
+						"name": { "type": ["string", "null"] }
+					},
+					"required": ["id"]
+				},
+				"rules": {
+					"type": "object",
+					"description": "Future routing predicates. Currently empty."
+				},
+				"delivery_count": { "type": "integer" },
+				"success_count": { "type": "integer" },
+				"failure_count": { "type": "integer" },
+				"consecutive_fails": { "type": "integer" },
+				"last_delivery_at": {
+					"type": ["string", "null"],
+					"format": "date-time"
+				},
+				"last_success_at": {
+					"type": ["string", "null"],
+					"format": "date-time"
+				},
+				"last_failure_at": {
+					"type": ["string", "null"],
+					"format": "date-time"
+				}
+			},
+			"required": [
+				"endpoint_id",
+				"enabled",
+				"domain",
+				"rules"
+			]
+		}, { "type": "null" }] },
+		"sdkName": "getFunctionRouting",
+		"summary": "Get a function's current route binding",
+		"tag": "Functions",
+		"tagCommand": "functions"
+	},
+	{
+		"binaryResponse": false,
+		"bodyRequired": false,
+		"command": "get-function-test-run-trace",
+		"description": "Returns the current end-to-end trace for a function test run.\nThe trace is intentionally partial while the test is still in\nflight: callers can poll this endpoint and watch it fill in\nfrom send -> inbound -> webhook deliveries -> outbound\nrequests, logs, and replies.\n",
+		"hasJsonBody": false,
+		"method": "GET",
+		"operationId": "getFunctionTestRunTrace",
+		"path": "/functions/{id}/test-runs/{run_id}/trace",
+		"pathParams": [{
+			"description": "Resource UUID",
+			"enum": null,
+			"name": "id",
+			"required": true,
+			"type": "string"
+		}, {
+			"description": "Function test run id returned by POST /functions/{id}/test.",
+			"enum": null,
+			"name": "run_id",
+			"required": true,
+			"type": "string"
+		}],
+		"queryParams": [],
+		"requestSchema": null,
+		"responseSchema": {
+			"type": "object",
+			"description": "End-to-end trace for a `POST /functions/{id}/test` run. The\nshape is stable, but many nested sections are null or empty\nuntil the corresponding phase has happened.\n",
+			"properties": {
+				"state": {
+					"type": "string",
+					"description": "High-level state for a function test run trace:\n  - `send_failed`: the initial test email send failed.\n  - `waiting_for_send`: the test run was created but no send result has been recorded yet.\n  - `waiting_for_inbound`: the test send was queued and the matching inbound email has not arrived yet.\n  - `waiting_for_function`: the inbound email arrived and webhook/function processing is still in flight.\n  - `completed`: the function webhook completed successfully.\n  - `failed`: webhook delivery exhausted retries.\n",
+					"enum": [
+						"send_failed",
+						"waiting_for_send",
+						"waiting_for_inbound",
+						"waiting_for_function",
+						"completed",
+						"failed"
+					]
+				},
+				"test_run": {
+					"type": "object",
+					"properties": {
+						"id": {
+							"type": "string",
+							"format": "uuid"
+						},
+						"function_id": {
+							"type": "string",
+							"format": "uuid"
+						},
+						"inbound_domain": { "type": "string" },
+						"to": { "type": "string" },
+						"from": { "type": "string" },
+						"subject": { "type": "string" },
+						"poll_since": {
+							"type": "string",
+							"format": "date-time"
+						},
 						"created_at": {
 							"type": "string",
 							"format": "date-time"
@@ -11123,6 +11532,92 @@ const operationManifest = [
 		"tag": "Functions",
 		"tagCommand": "functions"
 	},
+	{
+		"binaryResponse": false,
+		"bodyRequired": false,
+		"command": "get-org-routing-topology",
+		"description": "Returns a single snapshot of how inbound mail is routed across\nthis org's active domains and functions: which active domain has\nwhich function bound, the org's fallback function (if any), and\nevery deployed function with no route bound. Use this to answer\n\"which of my functions actually receive mail?\" diagnostically.\n",
+		"hasJsonBody": false,
+		"method": "GET",
+		"operationId": "getOrgRoutingTopology",
+		"path": "/functions/routing-topology",
+		"pathParams": [],
+		"queryParams": [],
+		"requestSchema": null,
+		"responseSchema": {
+			"type": "object",
+			"description": "Org-wide map of function routing: which domain points at which\nfunction, the org's fallback binding (if any), and every\ndeployed function with no route currently bound.\n",
+			"properties": {
+				"domains": {
+					"type": "array",
+					"items": {
+						"type": "object",
+						"properties": {
+							"domain_id": {
+								"type": "string",
+								"format": "uuid"
+							},
+							"domain": { "type": "string" },
+							"routed_function": {
+								"type": ["object", "null"],
+								"properties": {
+									"id": {
+										"type": "string",
+										"format": "uuid"
+									},
+									"name": { "type": "string" }
+								},
+								"required": ["id", "name"]
+							},
+							"endpoint_enabled": { "type": ["boolean", "null"] }
+						},
+						"required": [
+							"domain_id",
+							"domain",
+							"routed_function",
+							"endpoint_enabled"
+						]
+					}
+				},
+				"fallback_function": {
+					"type": ["object", "null"],
+					"properties": {
+						"id": {
+							"type": "string",
+							"format": "uuid"
+						},
+						"name": { "type": "string" }
+					},
+					"required": ["id", "name"]
+				},
+				"fallback_enabled": { "type": ["boolean", "null"] },
+				"unrouted_functions": {
+					"type": "array",
+					"items": {
+						"type": "object",
+						"properties": {
+							"id": {
+								"type": "string",
+								"format": "uuid"
+							},
+							"name": { "type": "string" }
+						},
+						"required": ["id", "name"]
+					}
+				}
+			},
+			"required": [
+				"domains",
+				"fallback_function",
+				"fallback_enabled",
+				"unrouted_functions"
+			]
+		},
+		"sdkName": "getOrgRoutingTopology",
+		"summary": "Get the org's function routing topology",
+		"tag": "Functions",
+		"tagCommand": "functions"
+	},
 	{
 		"binaryResponse": false,
 		"bodyRequired": false,
@@ -11342,6 +11837,130 @@ const operationManifest = [
 		"tag": "Functions",
 		"tagCommand": "functions"
 	},
+	{
+		"binaryResponse": false,
+		"bodyRequired": true,
+		"command": "set-function-route",
+		"description": "Binds inbound mail to this function. The route target is either\na specific verified domain (scoped) or the org's fallback (any\nactive domain with no scoped binding). If another function is\nalready bound at the target, returns a `conflict` envelope\ndescribing the holder; re-issue with `takeover: true` to\ndeactivate that prior binding and install this one.\n",
+		"hasJsonBody": true,
+		"method": "PUT",
+		"operationId": "setFunctionRoute",
+		"path": "/functions/{id}/route",
+		"pathParams": [{
+			"description": "Resource UUID",
+			"enum": null,
+			"name": "id",
+			"required": true,
+			"type": "string"
+		}],
+		"queryParams": [],
+		"requestSchema": {
+			"type": "object",
+			"description": "Target for a route binding. Either a specific verified domain\n(scoped) or the org-wide fallback. Pass `takeover: true` to\ndeactivate any conflicting binding before installing this one.\n",
+			"properties": {
+				"target": { "oneOf": [{
+					"type": "object",
+					"properties": {
+						"kind": {
+							"type": "string",
+							"enum": ["domain"]
+						},
+						"domainId": {
+							"type": "string",
+							"format": "uuid"
+						}
+					},
+					"required": ["kind", "domainId"]
+				}, {
+					"type": "object",
+					"properties": { "kind": {
+						"type": "string",
+						"enum": ["fallback"]
+					} },
+					"required": ["kind"]
+				}] },
+				"takeover": {
+					"type": "boolean",
+					"description": "When true, deactivate any conflicting binding before installing this one."
+				}
+			},
+			"required": ["target"]
+		},
+		"responseSchema": {
+			"type": "object",
+			"description": "On success, carries the new `routing`. On conflict, carries\n`conflict` describing the binding holder so the caller can\nre-issue with `takeover: true`.\n",
+			"properties": {
+				"routing": { "oneOf": [{
+					"type": "object",
+					"description": "A single route binding for a function. `domain` is null when the\nbinding is the org's fallback (any active domain without a scoped\nbinding); otherwise it carries the scoped domain. `rules` is\nreserved for future routing predicates.\n",
+					"properties": {
+						"endpoint_id": {
+							"type": "string",
+							"format": "uuid"
+						},
+						"enabled": { "type": "boolean" },
+						"domain": {
+							"type": ["object", "null"],
+							"properties": {
+								"id": {
+									"type": "string",
+									"format": "uuid"
+								},
+								"name": { "type": ["string", "null"] }
+							},
+							"required": ["id"]
+						},
+						"rules": {
+							"type": "object",
+							"description": "Future routing predicates. Currently empty."
+						},
+						"delivery_count": { "type": "integer" },
+						"success_count": { "type": "integer" },
+						"failure_count": { "type": "integer" },
+						"consecutive_fails": { "type": "integer" },
+						"last_delivery_at": {
+							"type": ["string", "null"],
+							"format": "date-time"
+						},
+						"last_success_at": {
+							"type": ["string", "null"],
+							"format": "date-time"
+						},
+						"last_failure_at": {
+							"type": ["string", "null"],
+							"format": "date-time"
+						}
+					},
+					"required": [
+						"endpoint_id",
+						"enabled",
+						"domain",
+						"rules"
+					]
+				}, { "type": "null" }] },
+				"conflict": {
+					"type": "object",
+					"properties": {
+						"kind": {
+							"type": "string",
+							"enum": ["http", "function"]
+						},
+						"functionId": {
+							"type": ["string", "null"],
+							"format": "uuid"
+						},
+						"functionName": { "type": ["string", "null"] },
+						"url": { "type": ["string", "null"] }
+					},
+					"required": ["kind"]
+				}
+			}
+		},
+		"sdkName": "setFunctionRoute",
+		"summary": "Bind a route to a function",
+		"tag": "Functions",
+		"tagCommand": "functions"
+	},
 	{
 		"binaryResponse": false,
 		"bodyRequired": true,
@@ -11495,6 +12114,37 @@ const operationManifest = [
 		"tag": "Functions",
 		"tagCommand": "functions"
 	},
+	{
+		"binaryResponse": false,
+		"bodyRequired": false,
+		"command": "unset-function-route",
+		"description": "Deactivates every active endpoint bound to this function. The\nfunction stays deployed but stops receiving inbound mail. Safe\nto call when no route is currently bound (no-op).\n",
+		"hasJsonBody": false,
+		"method": "DELETE",
+		"operationId": "unsetFunctionRoute",
+		"path": "/functions/{id}/route",
+		"pathParams": [{
+			"description": "Resource UUID",
+			"enum": null,
+			"name": "id",
+			"required": true,
+			"type": "string"
+		}],
+		"queryParams": [],
+		"requestSchema": null,
+		"responseSchema": {
+			"type": "object",
+			"properties": { "unrouted": {
+				"type": "boolean",
+				"enum": [true]
+			} },
+			"required": ["unrouted"]
+		},
+		"sdkName": "unsetFunctionRoute",
+		"summary": "Unbind any route from a function",
+		"tag": "Functions",
+		"tagCommand": "functions"
+	},
 	{
 		"binaryResponse": false,
 		"bodyRequired": true,
@@ -13415,6 +14065,10 @@ async function createAuthenticatedCliApiClient(params) {
 		apiBaseUrl: requestConfig.apiBaseUrl,
 		configDir: params.configDir
 	});
+	if (auth.apiKey === void 0) {
+		const hint = detectPrimitiveKeyEnvMisname(params.env ?? process.env);
+		if (hint) process.stderr.write(`${hint}\n`);
+	}
 	if (auth.source === "stored" && auth.credentials) {
 		const refreshed = await refreshStoredCliCredentials({
 			apiBaseUrl: auth.apiBaseUrl,
@@ -15374,9 +16028,7 @@ function checkApiKey(opts) {
 		message: "provided but does not start with prim_",
 		hint: "Verify the key is a Primitive API key, not a value from another service."
 	};
-	const primitiveKey = env.PRIMITIVE_KEY;
-	const primitiveApiKey = env.PRIMITIVE_API_KEY;
-	if ((primitiveKey?.length ?? 0) > 0 && (primitiveApiKey?.length ?? 0) === 0) return {
+	if (detectPrimitiveKeyEnvMisname(env)) return {
 		status: "fail",
 		message: "PRIMITIVE_KEY is set but the CLI reads PRIMITIVE_API_KEY",
 		hint: "Rename your env var, or re-run with PRIMITIVE_API_KEY=$PRIMITIVE_KEY."
@@ -16603,6 +17255,18 @@ const SECRET_SOURCE_FLAGS_DESCRIPTION = "Safe sources: --secret-from-env KEY rea
 const SINGLE_SECRET_VALUE_SOURCE_DESCRIPTION = "Instead of --value, use --value-from-env ENV_VAR, --value-file PATH, --value-from-env-file FILE[:KEY], or --stdin to avoid putting the secret value in shell history or process argv. If KEY is omitted from --value-from-env-file, the command's --key is used.";
 //#endregion
 //#region src/oclif/commands/functions-deploy.ts
+async function writeRouteStatusHint(apiClient, functionId) {
+	try {
+		const result = await getFunctionRouting({
+			client: apiClient.client,
+			path: { id: functionId },
+			responseStyle: "fields"
+		});
+		if (result.error) return;
+		if (result.data?.data) process.stderr.write("Route bound. Function will receive inbound mail.\n");
+		else process.stderr.write(`Deployed but no route is bound. Inbound mail will not reach this function until you bind one: primitive functions route-set --id ${functionId} --domain <domain-id>  (or --fallback)\n`);
+	} catch {}
+}
 async function runDeployWithSecrets(api, params) {
 	const createResult = await api.createFunction({
 		code: params.code,
@@ -16902,10 +17566,11 @@ var FunctionsDeployCommand = class FunctionsDeployCommand extends Command {
 					const detail = waitResult.function.deploy_error ? `: ${waitResult.function.deploy_error}` : ".";
 					process.stderr.write(`Function ${payload.id} deploy failed${detail}\n`);
 					process.exitCode = 1;
-				}
+				} else await writeRouteStatusHint(apiClient, payload.id);
 				return;
 			}
 			this.log(JSON.stringify(payload, null, 2));
+			await writeRouteStatusHint(apiClient, payload.id);
 		});
 	}
 	async runSourceMode(flags, sourceDir) {
@@ -16997,10 +17662,11 @@ var FunctionsDeployCommand = class FunctionsDeployCommand extends Command {
 				const detail = waitResult.function.deploy_error ? `: ${waitResult.function.deploy_error}` : ".";
 				process.stderr.write(`Function ${payload.id} deploy failed${detail}\n`);
 				process.exitCode = 1;
-			}
+			} else await writeRouteStatusHint(apiClient, payload.id);
 			return;
 		}
 		this.log(JSON.stringify(payload, null, 2));
+		await writeRouteStatusHint(apiClient, payload.id);
 	}
 };
 //#endregion
@@ -17011,8 +17677,8 @@ const PRIMITIVE_TEAM_AUTHOR = {
 	name: "Primitive Team",
 	url: "https://primitive.dev"
 };
-const SDK_VERSION_RANGE = "^0.35.1";
-const CLI_VERSION_RANGE = "^0.35.1";
+const SDK_VERSION_RANGE = "^0.36.0";
+const CLI_VERSION_RANGE = "^0.36.0";
 const ESBUILD_VERSION_RANGE = "^0.27.0";
 function renderHandler() {
 	return `// env.PRIMITIVE_API_KEY, env.PRIMITIVE_WEBHOOK_SECRET, and
@@ -17319,6 +17985,23 @@ After the first deploy, copy the returned function id into your shell:
 export PRIMITIVE_FUNCTION_ID=<fn-id>
 \`\`\`
 
+## Bind a route
+
+A deployed Function does not receive inbound mail until a route is
+bound to it. Without this step, the Function is installed in the
+runtime but unreachable, and \`functions test\` will refuse to send
+(returns 422 \`no_endpoint\`).
+
+\`\`\`
+primitive functions route-set --id "$PRIMITIVE_FUNCTION_ID" --domain <domain-id>
+\`\`\`
+
+Use \`--fallback\` instead of \`--domain\` to bind the Function as the
+org-wide fallback for any active domain that has no scoped binding.
+Run \`primitive functions route-get --id "$PRIMITIVE_FUNCTION_ID"\` to
+inspect the current binding, or \`primitive functions routing-topology\`
+for the org-wide view of which domain points at which Function.
+
 ## Prove it works
 
 \`\`\`
@@ -17929,6 +18612,239 @@ var FunctionsRedeployCommand = class FunctionsRedeployCommand extends Command {
 	}
 };
 //#endregion
+//#region src/oclif/commands/functions-route-get.ts
+var FunctionsRouteGetCommand = class FunctionsRouteGetCommand extends Command {
+	static description = `Show the current route binding for a function. Returns the binding (domain or fallback, with delivery counters) or null when no route is bound.`;
+	static summary = "Show a function's current route binding";
+	static examples = ["<%= config.bin %> functions route-get --id <fn-id>"];
+	static flags = {
+		"api-key": Flags.string({
+			description: "Primitive API key override (defaults to PRIMITIVE_API_KEY or saved OAuth login credentials)",
+			env: "PRIMITIVE_API_KEY"
+		}),
+		"api-base-url": Flags.string({
+			description: API_BASE_URL_FLAG_DESCRIPTION,
+			env: "PRIMITIVE_API_BASE_URL",
+			hidden: true
+		}),
+		id: Flags.string({
+			description: "Function id (UUID) whose route binding to show.",
+			required: true
+		}),
+		time: Flags.boolean({ description: TIME_FLAG_DESCRIPTION })
+	};
+	async run() {
+		const { flags } = await this.parse(FunctionsRouteGetCommand);
+		const { apiClient, auth, baseUrlOverridden } = await createAuthenticatedCliApiClient({
+			apiKey: flags["api-key"],
+			apiBaseUrl: flags["api-base-url"],
+			configDir: this.config.configDir
+		});
+		await runWithTiming(flags.time, async () => {
+			const result = await getFunctionRouting({
+				client: apiClient.client,
+				path: { id: flags.id },
+				responseStyle: "fields"
+			});
+			if (result.error) {
+				const payload = extractErrorPayload(result.error);
+				writeErrorWithHints(payload);
+				surfaceUnauthorizedHint({
+					auth,
+					baseUrlOverridden,
+					configDir: this.config.configDir,
+					payload
+				});
+				process.exitCode = 1;
+				return;
+			}
+			this.log(JSON.stringify(result.data.data, null, 2));
+		});
+	}
+};
+//#endregion
+//#region src/oclif/commands/functions-route-set.ts
+var FunctionsRouteSetCommand = class FunctionsRouteSetCommand extends Command {
+	static description = `Bind inbound mail to a function by setting its route target.
+
+  Exactly one of --domain or --fallback is required. --domain scopes the
+  binding to a single verified inbound domain. --fallback binds the
+  function to any active domain that has no scoped binding of its own.
+
+  If another function is already bound at the target, the API returns a
+  conflict envelope rather than overwriting; re-run with --takeover to
+  deactivate the prior binding before installing this one.`;
+	static summary = "Bind inbound mail to a function";
+	static examples = [
+		"<%= config.bin %> functions route-set --id <fn-id> --domain <domain-id>",
+		"<%= config.bin %> functions route-set --id <fn-id> --fallback",
+		"<%= config.bin %> functions route-set --id <fn-id> --domain <domain-id> --takeover"
+	];
+	static flags = {
+		"api-key": Flags.string({
+			description: "Primitive API key override (defaults to PRIMITIVE_API_KEY or saved OAuth login credentials)",
+			env: "PRIMITIVE_API_KEY"
+		}),
+		"api-base-url": Flags.string({
+			description: API_BASE_URL_FLAG_DESCRIPTION,
+			env: "PRIMITIVE_API_BASE_URL",
+			hidden: true
+		}),
+		id: Flags.string({
+			description: "Function id (UUID) to bind a route to.",
+			required: true
+		}),
+		domain: Flags.string({
+			description: "Verified inbound domain id (UUID) to scope this function to. Mutually exclusive with --fallback.",
+			exclusive: ["fallback"]
+		}),
+		fallback: Flags.boolean({
+			description: "Bind this function as the org fallback (any active domain without a scoped binding). Mutually exclusive with --domain.",
+			exclusive: ["domain"]
+		}),
+		takeover: Flags.boolean({ description: "Deactivate any conflicting binding before installing this one. Without this flag, the API returns a `conflict` envelope when another function is already bound at the target." }),
+		time: Flags.boolean({ description: TIME_FLAG_DESCRIPTION })
+	};
+	async run() {
+		const { flags } = await this.parse(FunctionsRouteSetCommand);
+		if (!flags.domain && !flags.fallback) {
+			process.stderr.write("Provide exactly one of --domain (scoped binding) or --fallback (org fallback).\n");
+			process.exitCode = 1;
+			return;
+		}
+		const { apiClient, auth, baseUrlOverridden } = await createAuthenticatedCliApiClient({
+			apiKey: flags["api-key"],
+			apiBaseUrl: flags["api-base-url"],
+			configDir: this.config.configDir
+		});
+		await runWithTiming(flags.time, async () => {
+			const target = flags.domain ? {
+				kind: "domain",
+				domainId: flags.domain
+			} : { kind: "fallback" };
+			const result = await setFunctionRoute({
+				client: apiClient.client,
+				path: { id: flags.id },
+				body: {
+					target,
+					...flags.takeover ? { takeover: true } : {}
+				},
+				responseStyle: "fields"
+			});
+			if (result.error) {
+				const payload = extractErrorPayload(result.error);
+				writeErrorWithHints(payload);
+				surfaceUnauthorizedHint({
+					auth,
+					baseUrlOverridden,
+					configDir: this.config.configDir,
+					payload
+				});
+				process.exitCode = 1;
+				return;
+			}
+			this.log(JSON.stringify(result.data.data, null, 2));
+		});
+	}
+};
+//#endregion
+//#region src/oclif/commands/functions-route-unset.ts
+var FunctionsRouteUnsetCommand = class FunctionsRouteUnsetCommand extends Command {
+	static description = `Unbind every active route from a function. The function stays deployed but stops receiving inbound mail. Safe to call when no route is currently bound.`;
+	static summary = "Unbind any route from a function";
+	static examples = ["<%= config.bin %> functions route-unset --id <fn-id>"];
+	static flags = {
+		"api-key": Flags.string({
+			description: "Primitive API key override (defaults to PRIMITIVE_API_KEY or saved OAuth login credentials)",
+			env: "PRIMITIVE_API_KEY"
+		}),
+		"api-base-url": Flags.string({
+			description: API_BASE_URL_FLAG_DESCRIPTION,
+			env: "PRIMITIVE_API_BASE_URL",
+			hidden: true
+		}),
+		id: Flags.string({
+			description: "Function id (UUID) whose routes should be unbound.",
+			required: true
+		}),
+		time: Flags.boolean({ description: TIME_FLAG_DESCRIPTION })
+	};
+	async run() {
+		const { flags } = await this.parse(FunctionsRouteUnsetCommand);
+		const { apiClient, auth, baseUrlOverridden } = await createAuthenticatedCliApiClient({
+			apiKey: flags["api-key"],
+			apiBaseUrl: flags["api-base-url"],
+			configDir: this.config.configDir
+		});
+		await runWithTiming(flags.time, async () => {
+			const result = await unsetFunctionRoute({
+				client: apiClient.client,
+				path: { id: flags.id },
+				responseStyle: "fields"
+			});
+			if (result.error) {
+				const payload = extractErrorPayload(result.error);
+				writeErrorWithHints(payload);
+				surfaceUnauthorizedHint({
+					auth,
+					baseUrlOverridden,
+					configDir: this.config.configDir,
+					payload
+				});
+				process.exitCode = 1;
+				return;
+			}
+			this.log(JSON.stringify(result.data.data, null, 2));
+		});
+	}
+};
+//#endregion
+//#region src/oclif/commands/functions-routing-topology.ts
+var FunctionsRoutingTopologyCommand = class FunctionsRoutingTopologyCommand extends Command {
+	static description = `Show the org-wide function routing topology. Lists every active domain with its bound function (if any), the org fallback function (if any), and every deployed function with no route currently bound.`;
+	static summary = "Show the org-wide function routing topology";
+	static examples = ["<%= config.bin %> functions routing-topology"];
+	static flags = {
+		"api-key": Flags.string({
+			description: "Primitive API key override (defaults to PRIMITIVE_API_KEY or saved OAuth login credentials)",
+			env: "PRIMITIVE_API_KEY"
+		}),
+		"api-base-url": Flags.string({
+			description: API_BASE_URL_FLAG_DESCRIPTION,
+			env: "PRIMITIVE_API_BASE_URL",
+			hidden: true
+		}),
+		time: Flags.boolean({ description: TIME_FLAG_DESCRIPTION })
+	};
+	async run() {
+		const { flags } = await this.parse(FunctionsRoutingTopologyCommand);
+		const { apiClient, auth, baseUrlOverridden } = await createAuthenticatedCliApiClient({
+			apiKey: flags["api-key"],
+			apiBaseUrl: flags["api-base-url"],
+			configDir: this.config.configDir
+		});
+		await runWithTiming(flags.time, async () => {
+			const result = await getOrgRoutingTopology({
+				client: apiClient.client,
+				responseStyle: "fields"
+			});
+			if (result.error) {
+				const payload = extractErrorPayload(result.error);
+				writeErrorWithHints(payload);
+				surfaceUnauthorizedHint({
+					auth,
+					baseUrlOverridden,
+					configDir: this.config.configDir,
+					payload
+				});
+				process.exitCode = 1;
+				return;
+			}
+			this.log(JSON.stringify(result.data.data, null, 2));
+		});
+	}
+};
+//#endregion
 //#region src/oclif/commands/functions-set-secret.ts
 async function runSetSecret(api, params) {
 	const setResult = await api.setSecret({
@@ -18106,6 +19022,7 @@ var FunctionsSetSecretCommand = class FunctionsSetSecretCommand extends Command
 				return;
 			}
 			this.log(JSON.stringify(outcome.result, null, 2));
+			if (outcome.result.redeploy === void 0) process.stderr.write(`Secret ${flags.key} saved. Not live until redeploy. Re-run with --redeploy, or run \`primitive functions redeploy --id ${flags.id} --file <bundle.js>\`.\n`);
 		});
 	}
 };
@@ -18230,7 +19147,7 @@ async function maybeWriteEndpointNoiseWarning(params) {
 	} catch {}
 }
 var FunctionsTestFunctionCommand = class FunctionsTestFunctionCommand extends Command {
-	static description = "Send a real test email through MX to trigger this function. With --wait, blocks until the function has processed the inbound; with --show-sends, also prints any outbound sends the function emitted in response.";
+	static description = "Send a real test email through MX to trigger this function. The function must have an active route bound (see `functions route-set`); without one the API returns a 422 immediately so no doomed test send is queued. With --wait, blocks until the function has processed the inbound; with --show-sends, also prints any outbound sends the function emitted in response.";
 	static summary = "Trigger a test invocation; with --wait, watch it land";
 	static examples = [
 		"<%= config.bin %> functions test --id <fn-id>",
@@ -18336,13 +19253,35 @@ var FunctionsTestFunctionCommand = class FunctionsTestFunctionCommand extends Co
 					return;
 				}
 				const fetched = result.data.data;
+				if (fetched.inbound_email && Array.isArray(fetched.deliveries) && fetched.deliveries.length === 0 && Date.now() - startedAt > 15e3) {
+					writeFunctionTestProgress(`Inbound email arrived but no route matched. Bind one with: primitive functions route-set --id ${flags.id} --domain <domain-id> (or --fallback), then retry.`);
+					process.exitCode = 1;
+					return;
+				}
 				if (TERMINAL_TEST_TRACE_STATES.has(fetched.state)) {
 					trace = fetched;
 					break;
 				}
 				await sleep$1(pollIntervalMs);
 			}
-			if (!trace) this.error(`Timed out after ${flags.timeout}s waiting for function test run ${invocation.test_run_id} to complete. Browse ${invocation.watch_url} for the live view, or inspect ${invocation.trace_url}.`, { exit: 2 });
+			if (!trace) {
+				const finalTrace = ((await getFunctionTestRunTrace({
+					client: apiClient.client,
+					path: {
+						id: flags.id,
+						run_id: invocation.test_run_id
+					},
+					responseStyle: "fields"
+				}).catch(() => null))?.data)?.data;
+				const inboundLanded = Boolean(finalTrace?.inbound_email);
+				const deliveryCount = finalTrace?.deliveries?.length ?? 0;
+				const logCount = finalTrace?.logs?.length ?? 0;
+				const replyCount = finalTrace?.replies?.length ?? 0;
+				const webhookStatus = finalTrace?.inbound_email?.webhook_status ?? "n/a";
+				writeFunctionTestProgress(`Timed out after ${flags.timeout}s. Trace summary: inbound_landed=${inboundLanded} deliveries=${deliveryCount} logs=${logCount} replies=${replyCount} webhook_status=${webhookStatus}. Browse ${invocation.watch_url} for the live view, or inspect ${invocation.trace_url}.`);
+				process.exitCode = 2;
+				return;
+			}
 			const outcome = buildFunctionTestOutcome({
 				elapsedSeconds: Math.round((Date.now() - startedAt) / 1e3),
 				functionId: flags.id,
@@ -20944,6 +21883,10 @@ const COMMANDS = {
 	"functions:set-secret": FunctionsSetSecretCommand,
 	"functions:test": FunctionsTestFunctionCommand,
 	"functions:test-function": FunctionsTestFunctionCommand,
+	"functions:route-set": FunctionsRouteSetCommand,
+	"functions:route-unset": FunctionsRouteUnsetCommand,
+	"functions:route-get": FunctionsRouteGetCommand,
+	"functions:routing-topology": FunctionsRoutingTopologyCommand,
 	...Object.fromEntries(Object.entries(CANONICAL_OPERATION_ALIASES).map(([alias, target]) => {
 		const command = generatedCommands[target];
 		if (!command) throw new Error(`Missing generated command target for alias ${alias}`);

package/dist/oclif/root-signup-hint.js

@@ -1,4 +1,4 @@
-import { b as normalizeApiBaseUrl, c as resolveConfigEnvironment, i as loadCliConfig } from "../cli-config-DREZ2BxT.js";
+import { c as resolveConfigEnvironment, i as loadCliConfig, x as normalizeApiBaseUrl } from "../cli-config-D7wN_PBc.js";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";

package/package.json

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