@primitivedotdev/cli 0.31.4 → 0.31.5

package/dist/oclif/index.js

@@ -651,6 +651,7 @@ var sdk_gen_exports = /* @__PURE__ */ __exportAll({
 	getEmail: () => getEmail,
 	getFunction: () => getFunction,
 	getFunctionTestRunTrace: () => getFunctionTestRunTrace,
+	getInboxStatus: () => getInboxStatus,
 	getSendPermissions: () => getSendPermissions,
 	getSentEmail: () => getSentEmail,
 	getStorageStats: () => getStorageStats,
@@ -1033,6 +1034,28 @@ const downloadDomainZoneFile = (options) => (options.client ?? client).get({
 	...options
 });
 /**
+* Get inbound inbox readiness
+*
+* Returns one consolidated view of inbound domain readiness,
+* webhook/function processing routes, deployed Functions, and
+* recent inbound email activity.
+*
+* Agents should call this before guiding a user through inbound
+* setup. It answers the practical questions "can I receive mail",
+* "will anything process that mail", and "what should I do next"
+* without forcing clients to stitch together domains, endpoints,
+* functions, and emails manually.
+*
+*/
+const getInboxStatus = (options) => (options?.client ?? client).get({
+	security: [{
+		scheme: "bearer",
+		type: "http"
+	}],
+	url: "/inbox/status",
+	...options
+});
+/**
 * List inbound emails
 *
 * Returns a paginated list of INBOUND emails received at your
@@ -1894,6 +1917,10 @@ const openapiDocument = {
 			"name": "Domains",
 			"description": "Claim, verify, and manage email domains"
 		},
+		{
+			"name": "Inbox",
+			"description": "Check inbound email setup and processing readiness"
+		},
 		{
 			"name": "Emails",
 			"description": "List, inspect, and manage received emails"
@@ -2500,6 +2527,23 @@ const openapiDocument = {
 				}
 			}
 		},
+		"/inbox/status": { "get": {
+			"operationId": "getInboxStatus",
+			"summary": "Get inbound inbox readiness",
+			"description": "Returns one consolidated view of inbound domain readiness,\nwebhook/function processing routes, deployed Functions, and\nrecent inbound email activity.\n\nAgents should call this before guiding a user through inbound\nsetup. It answers the practical questions \"can I receive mail\",\n\"will anything process that mail\", and \"what should I do next\"\nwithout forcing clients to stitch together domains, endpoints,\nfunctions, and emails manually.\n",
+			"tags": ["Inbox"],
+			"responses": {
+				"200": {
+					"description": "Consolidated inbox readiness status",
+					"content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, {
+						"type": "object",
+						"properties": { "data": { "$ref": "#/components/schemas/InboxStatus" } }
+					}] } } }
+				},
+				"401": { "$ref": "#/components/responses/Unauthorized" },
+				"429": { "$ref": "#/components/responses/RateLimited" }
+			}
+		} },
 		"/emails": { "get": {
 			"operationId": "listEmails",
 			"summary": "List inbound emails",
@@ -4788,6 +4832,181 @@ const openapiDocument = {
 				} },
 				"required": ["secret"]
 			},
+			"InboxStatus": {
+				"type": "object",
+				"additionalProperties": false,
+				"properties": {
+					"ready": {
+						"type": "boolean",
+						"description": "True when at least one active inbound domain has an enabled processing route."
+					},
+					"receiving_ready": {
+						"type": "boolean",
+						"description": "True when at least one active verified or managed domain can receive mail."
+					},
+					"processing_ready": {
+						"type": "boolean",
+						"description": "True when at least one receiving-ready domain has an enabled webhook or function route."
+					},
+					"summary": {
+						"type": "string",
+						"description": "Short human-readable status summary."
+					},
+					"next_actions": {
+						"type": "array",
+						"items": { "$ref": "#/components/schemas/InboxStatusNextAction" }
+					},
+					"domains": {
+						"type": "array",
+						"items": { "$ref": "#/components/schemas/InboxStatusDomain" }
+					},
+					"endpoints": { "$ref": "#/components/schemas/InboxStatusEndpointSummary" },
+					"functions": { "$ref": "#/components/schemas/InboxStatusFunctionSummary" },
+					"recent_emails": { "$ref": "#/components/schemas/InboxStatusRecentEmailSummary" }
+				},
+				"required": [
+					"ready",
+					"receiving_ready",
+					"processing_ready",
+					"summary",
+					"next_actions",
+					"domains",
+					"endpoints",
+					"functions",
+					"recent_emails"
+				]
+			},
+			"InboxStatusNextAction": {
+				"type": "object",
+				"additionalProperties": false,
+				"properties": {
+					"kind": {
+						"type": "string",
+						"enum": [
+							"add_domain",
+							"verify_domain",
+							"configure_processing",
+							"send_test_email",
+							"fix_failed_functions"
+						]
+					},
+					"message": {
+						"type": "string",
+						"description": "Human-readable next step."
+					},
+					"command": {
+						"type": "string",
+						"description": "Suggested Primitive CLI command when there is an obvious next step."
+					}
+				},
+				"required": ["kind", "message"]
+			},
+			"InboxStatusDomain": {
+				"type": "object",
+				"additionalProperties": false,
+				"properties": {
+					"id": { "type": "string" },
+					"domain": { "type": "string" },
+					"verified": { "type": "boolean" },
+					"active": { "type": "boolean" },
+					"managed": { "type": "boolean" },
+					"receiving_ready": { "type": "boolean" },
+					"processing_ready": { "type": "boolean" },
+					"processing_route_count": { "type": "integer" },
+					"endpoint_count": { "type": "integer" },
+					"enabled_endpoint_count": { "type": "integer" },
+					"function_endpoint_count": { "type": "integer" },
+					"email_count": {
+						"type": "integer",
+						"description": "Number of inbound emails received for this domain in the last 30 days."
+					},
+					"latest_email_received_at": {
+						"type": ["string", "null"],
+						"format": "date-time",
+						"description": "Most recent inbound email received for this domain in the last 30 days."
+					},
+					"status": {
+						"type": "string",
+						"enum": [
+							"ready",
+							"stored_only",
+							"pending_dns",
+							"inactive"
+						]
+					}
+				},
+				"required": [
+					"id",
+					"domain",
+					"verified",
+					"active",
+					"managed",
+					"receiving_ready",
+					"processing_ready",
+					"processing_route_count",
+					"endpoint_count",
+					"enabled_endpoint_count",
+					"function_endpoint_count",
+					"email_count",
+					"latest_email_received_at",
+					"status"
+				]
+			},
+			"InboxStatusEndpointSummary": {
+				"type": "object",
+				"additionalProperties": false,
+				"properties": {
+					"total": { "type": "integer" },
+					"enabled": { "type": "integer" },
+					"disabled": { "type": "integer" },
+					"fallback_enabled": { "type": "integer" },
+					"domain_scoped_enabled": { "type": "integer" },
+					"http_enabled": { "type": "integer" },
+					"function_enabled": { "type": "integer" }
+				},
+				"required": [
+					"total",
+					"enabled",
+					"disabled",
+					"fallback_enabled",
+					"domain_scoped_enabled",
+					"http_enabled",
+					"function_enabled"
+				]
+			},
+			"InboxStatusFunctionSummary": {
+				"type": "object",
+				"additionalProperties": false,
+				"properties": {
+					"total": { "type": "integer" },
+					"deployed": { "type": "integer" },
+					"pending": { "type": "integer" },
+					"failed": { "type": "integer" }
+				},
+				"required": [
+					"total",
+					"deployed",
+					"pending",
+					"failed"
+				]
+			},
+			"InboxStatusRecentEmailSummary": {
+				"type": "object",
+				"description": "Inbound email activity from the last 30 days.",
+				"additionalProperties": false,
+				"properties": {
+					"total": {
+						"type": "integer",
+						"description": "Number of inbound emails received in the last 30 days."
+					},
+					"latest_received_at": {
+						"type": ["string", "null"],
+						"format": "date-time",
+						"description": "Most recent inbound email received in the last 30 days."
+					}
+				},
+				"required": ["total", "latest_received_at"]
+			},
 			"Domain": {
 				"description": "A domain can be either verified or unverified. Verified domains have\n`is_active` and `spam_threshold` fields. Unverified domains have a\n`verification_token` and `dns_records` for DNS setup.\n",
 				"oneOf": [{ "$ref": "#/components/schemas/VerifiedDomain" }, { "$ref": "#/components/schemas/UnverifiedDomain" }]
@@ -10881,6 +11100,193 @@ const operationManifest = [
 		"tag": "Functions",
 		"tagCommand": "functions"
 	},
+	{
+		"binaryResponse": false,
+		"bodyRequired": false,
+		"command": "get-inbox-status",
+		"description": "Returns one consolidated view of inbound domain readiness,\nwebhook/function processing routes, deployed Functions, and\nrecent inbound email activity.\n\nAgents should call this before guiding a user through inbound\nsetup. It answers the practical questions \"can I receive mail\",\n\"will anything process that mail\", and \"what should I do next\"\nwithout forcing clients to stitch together domains, endpoints,\nfunctions, and emails manually.\n",
+		"hasJsonBody": false,
+		"method": "GET",
+		"operationId": "getInboxStatus",
+		"path": "/inbox/status",
+		"pathParams": [],
+		"queryParams": [],
+		"requestSchema": null,
+		"responseSchema": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"ready": {
+					"type": "boolean",
+					"description": "True when at least one active inbound domain has an enabled processing route."
+				},
+				"receiving_ready": {
+					"type": "boolean",
+					"description": "True when at least one active verified or managed domain can receive mail."
+				},
+				"processing_ready": {
+					"type": "boolean",
+					"description": "True when at least one receiving-ready domain has an enabled webhook or function route."
+				},
+				"summary": {
+					"type": "string",
+					"description": "Short human-readable status summary."
+				},
+				"next_actions": {
+					"type": "array",
+					"items": {
+						"type": "object",
+						"additionalProperties": false,
+						"properties": {
+							"kind": {
+								"type": "string",
+								"enum": [
+									"add_domain",
+									"verify_domain",
+									"configure_processing",
+									"send_test_email",
+									"fix_failed_functions"
+								]
+							},
+							"message": {
+								"type": "string",
+								"description": "Human-readable next step."
+							},
+							"command": {
+								"type": "string",
+								"description": "Suggested Primitive CLI command when there is an obvious next step."
+							}
+						},
+						"required": ["kind", "message"]
+					}
+				},
+				"domains": {
+					"type": "array",
+					"items": {
+						"type": "object",
+						"additionalProperties": false,
+						"properties": {
+							"id": { "type": "string" },
+							"domain": { "type": "string" },
+							"verified": { "type": "boolean" },
+							"active": { "type": "boolean" },
+							"managed": { "type": "boolean" },
+							"receiving_ready": { "type": "boolean" },
+							"processing_ready": { "type": "boolean" },
+							"processing_route_count": { "type": "integer" },
+							"endpoint_count": { "type": "integer" },
+							"enabled_endpoint_count": { "type": "integer" },
+							"function_endpoint_count": { "type": "integer" },
+							"email_count": {
+								"type": "integer",
+								"description": "Number of inbound emails received for this domain in the last 30 days."
+							},
+							"latest_email_received_at": {
+								"type": ["string", "null"],
+								"format": "date-time",
+								"description": "Most recent inbound email received for this domain in the last 30 days."
+							},
+							"status": {
+								"type": "string",
+								"enum": [
+									"ready",
+									"stored_only",
+									"pending_dns",
+									"inactive"
+								]
+							}
+						},
+						"required": [
+							"id",
+							"domain",
+							"verified",
+							"active",
+							"managed",
+							"receiving_ready",
+							"processing_ready",
+							"processing_route_count",
+							"endpoint_count",
+							"enabled_endpoint_count",
+							"function_endpoint_count",
+							"email_count",
+							"latest_email_received_at",
+							"status"
+						]
+					}
+				},
+				"endpoints": {
+					"type": "object",
+					"additionalProperties": false,
+					"properties": {
+						"total": { "type": "integer" },
+						"enabled": { "type": "integer" },
+						"disabled": { "type": "integer" },
+						"fallback_enabled": { "type": "integer" },
+						"domain_scoped_enabled": { "type": "integer" },
+						"http_enabled": { "type": "integer" },
+						"function_enabled": { "type": "integer" }
+					},
+					"required": [
+						"total",
+						"enabled",
+						"disabled",
+						"fallback_enabled",
+						"domain_scoped_enabled",
+						"http_enabled",
+						"function_enabled"
+					]
+				},
+				"functions": {
+					"type": "object",
+					"additionalProperties": false,
+					"properties": {
+						"total": { "type": "integer" },
+						"deployed": { "type": "integer" },
+						"pending": { "type": "integer" },
+						"failed": { "type": "integer" }
+					},
+					"required": [
+						"total",
+						"deployed",
+						"pending",
+						"failed"
+					]
+				},
+				"recent_emails": {
+					"type": "object",
+					"description": "Inbound email activity from the last 30 days.",
+					"additionalProperties": false,
+					"properties": {
+						"total": {
+							"type": "integer",
+							"description": "Number of inbound emails received in the last 30 days."
+						},
+						"latest_received_at": {
+							"type": ["string", "null"],
+							"format": "date-time",
+							"description": "Most recent inbound email received in the last 30 days."
+						}
+					},
+					"required": ["total", "latest_received_at"]
+				}
+			},
+			"required": [
+				"ready",
+				"receiving_ready",
+				"processing_ready",
+				"summary",
+				"next_actions",
+				"domains",
+				"endpoints",
+				"functions",
+				"recent_emails"
+			]
+		},
+		"sdkName": "getInboxStatus",
+		"summary": "Get inbound inbox readiness",
+		"tag": "Inbox",
+		"tagCommand": "inbox"
+	},
 	{
 		"binaryResponse": false,
 		"bodyRequired": false,
@@ -13082,6 +13488,7 @@ const OPERATION_HINTS = {
 	addDomain: "Tip: after this returns a domain id, run `primitive domains zone-file --id <domain-id> --output <domain>.zone` when the user wants an importable DNS zone file.",
 	verifyDomain: "Tip: if DNS is still missing, run `primitive domains zone-file --id <domain-id> --output <domain>.zone` to give the user an importable DNS zone file.",
 	downloadDomainZoneFile: "Tip: prefer `primitive domains zone-file --id <domain-id> --output <domain>.zone` for CLI-friendly file output.",
+	getInboxStatus: "Tip: prefer `primitive inbox status` for a compact readiness summary and next-step commands.",
 	sendEmail: "Tip: prefer `primitive send --to <address> --body <text> --attachment <file>` for file attachments. This raw command exists for callers passing JSON.",
 	createFunction: "Tip: prefer `primitive functions deploy --name <name> --file <bundle>` for file-input ergonomics. This raw command exists for callers passing JSON.",
 	updateFunction: "Tip: prefer `primitive functions redeploy --id <id> --file <bundle>` for file-input ergonomics. This raw command exists for callers passing JSON.",
@@ -14108,7 +14515,7 @@ const ADDRESS_DISPLAY_WIDTH = 32;
 const ID_DISPLAY_WIDTH_SHORT = 8;
 const ID_DISPLAY_WIDTH_FULL = 36;
 const RECEIVED_DISPLAY_WIDTH = 19;
-function truncate(value, width) {
+function truncate$1(value, width) {
 	if (value.length <= width) return value.padEnd(width);
 	return `${value.slice(0, width - 3)}...`;
 }
@@ -14123,7 +14530,7 @@ function pickIdWidth(isTty) {
 	return isTty ? ID_DISPLAY_WIDTH_SHORT : ID_DISPLAY_WIDTH_FULL;
 }
 function formatRow(email, idWidth) {
-	return `${truncate(email.id.slice(0, idWidth), idWidth)}  ${formatReceivedAt(email.received_at)}  ${truncate(email.sender ?? "", ADDRESS_DISPLAY_WIDTH)}  ${truncate(email.recipient ?? "", ADDRESS_DISPLAY_WIDTH)}  ${truncate((email.subject ?? "").replace(/\s+/g, " "), SUBJECT_DISPLAY_WIDTH)}`;
+	return `${truncate$1(email.id.slice(0, idWidth), idWidth)}  ${formatReceivedAt(email.received_at)}  ${truncate$1(email.sender ?? "", ADDRESS_DISPLAY_WIDTH)}  ${truncate$1(email.recipient ?? "", ADDRESS_DISPLAY_WIDTH)}  ${truncate$1((email.subject ?? "").replace(/\s+/g, " "), SUBJECT_DISPLAY_WIDTH)}`;
 }
 function formatHeader(idWidth) {
 	return `${"ID".padEnd(idWidth)}  ${"RECEIVED (UTC)".padEnd(RECEIVED_DISPLAY_WIDTH)}  ${"FROM".padEnd(ADDRESS_DISPLAY_WIDTH)}  ${"TO".padEnd(ADDRESS_DISPLAY_WIDTH)}  SUBJECT`;
@@ -16509,6 +16916,174 @@ var FunctionsTestFunctionCommand = class FunctionsTestFunctionCommand extends Co
 	}
 };
 //#endregion
+//#region src/oclif/commands/inbox-status.ts
+const DOMAIN_DISPLAY_WIDTH = 34;
+const STATUS_DISPLAY_WIDTH = 12;
+const BOOL_DISPLAY_WIDTH = 7;
+const NUM_DISPLAY_WIDTH = 6;
+function plural(count, singular, pluralValue = `${singular}s`) {
+	return `${count} ${count === 1 ? singular : pluralValue}`;
+}
+function statusText(status) {
+	switch (status) {
+		case "ready": return "ready";
+		case "stored_only": return "stored-only";
+		case "pending_dns": return "pending-dns";
+		case "inactive": return "inactive";
+		default: return String(status);
+	}
+}
+function yesNo(value) {
+	return value ? "yes" : "no";
+}
+function formatInboxDate(value) {
+	if (!value) return "never";
+	const d = new Date(value);
+	if (Number.isNaN(d.getTime())) return value;
+	const pad = (n) => String(n).padStart(2, "0");
+	return `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())} ${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())}:${pad(d.getUTCSeconds())} UTC`;
+}
+function truncate(value, width) {
+	if (value.length <= width) return value.padEnd(width);
+	return `${value.slice(0, width - 3)}...`;
+}
+function domainSummary(domain) {
+	switch (domain.status) {
+		case "ready": return `${domain.domain} can receive mail and has ${plural(domain.processing_route_count, "processing route")}.`;
+		case "stored_only": return `${domain.domain} can receive and store mail, but has no enabled processing route.`;
+		case "pending_dns": return `${domain.domain} is waiting on DNS verification before it can receive mail.`;
+		case "inactive": return `${domain.domain} is verified but inactive.`;
+		default: return `${domain.domain} has status ${String(domain.status)}.`;
+	}
+}
+function focusInboxStatus(status, domainName) {
+	const normalized = domainName.toLowerCase();
+	const domain = status.domains.find((entry) => entry.domain.toLowerCase() === normalized);
+	if (!domain) throw new Errors.CLIError(`Domain ${domainName} was not found.`, { exit: 1 });
+	return {
+		...status,
+		domains: [domain],
+		ready: domain.receiving_ready && domain.processing_ready,
+		receiving_ready: domain.receiving_ready,
+		processing_ready: domain.processing_ready,
+		summary: domainSummary(domain),
+		recent_emails: {
+			total: domain.email_count,
+			latest_received_at: domain.latest_email_received_at
+		}
+	};
+}
+function formatDomainHeader() {
+	return [
+		"DOMAIN".padEnd(DOMAIN_DISPLAY_WIDTH),
+		"STATUS".padEnd(STATUS_DISPLAY_WIDTH),
+		"RECEIVE".padEnd(BOOL_DISPLAY_WIDTH),
+		"PROCESS".padEnd(BOOL_DISPLAY_WIDTH),
+		"EMAILS".padStart(NUM_DISPLAY_WIDTH),
+		"ROUTES".padStart(NUM_DISPLAY_WIDTH)
+	].join("  ");
+}
+function formatDomainRow(domain) {
+	return [
+		truncate(domain.domain, DOMAIN_DISPLAY_WIDTH),
+		statusText(domain.status).padEnd(STATUS_DISPLAY_WIDTH),
+		yesNo(domain.receiving_ready).padEnd(BOOL_DISPLAY_WIDTH),
+		yesNo(domain.processing_ready).padEnd(BOOL_DISPLAY_WIDTH),
+		String(domain.email_count).padStart(NUM_DISPLAY_WIDTH),
+		String(domain.processing_route_count).padStart(NUM_DISPLAY_WIDTH)
+	].join("  ");
+}
+function formatNextAction(action) {
+	return action.command ? `- ${action.message}\n  ${action.command}` : `- ${action.message}`;
+}
+function formatInboxStatus(status) {
+	const lines = [
+		status.summary,
+		"",
+		"Domains"
+	];
+	if (status.domains.length === 0) lines.push("No domains configured.");
+	else {
+		lines.push(formatDomainHeader());
+		for (const domain of status.domains) lines.push(formatDomainRow(domain));
+	}
+	lines.push("", `Endpoints: ${status.endpoints.enabled}/${status.endpoints.total} enabled (${status.endpoints.fallback_enabled} fallback, ${status.endpoints.domain_scoped_enabled} domain-scoped, ${status.endpoints.function_enabled} function)`, `Functions: ${status.functions.deployed}/${status.functions.total} deployed (${status.functions.pending} pending, ${status.functions.failed} failed)`, `Recent inbound: ${plural(status.recent_emails.total, "email")} latest ${formatInboxDate(status.recent_emails.latest_received_at)}`);
+	if (status.next_actions.length > 0) {
+		lines.push("", "Next actions");
+		for (const action of status.next_actions) lines.push(formatNextAction(action));
+	}
+	return lines.join("\n");
+}
+var InboxStatusCommand = class InboxStatusCommand extends Command {
+	static description = `Show consolidated inbound email readiness.
+
+  This checks the server-owned inbox status API instead of reconstructing readiness locally from separate domain, endpoint, function, and email lists. Use it before testing inbound email setup: it tells you whether mail can be received, whether anything will process it, and which next command is most useful.`;
+	static summary = "Show inbound email readiness";
+	static examples = [
+		"<%= config.bin %> inbox status",
+		"<%= config.bin %> inbox status --domain example.com",
+		"<%= config.bin %> inbox status --json | jq '.data.next_actions'"
+	];
+	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-1": Flags.string({
+			description: API_BASE_URL_1_FLAG_DESCRIPTION,
+			env: "PRIMITIVE_API_BASE_URL_1",
+			hidden: true
+		}),
+		"api-base-url-2": Flags.string({
+			description: API_BASE_URL_2_FLAG_DESCRIPTION,
+			env: "PRIMITIVE_API_BASE_URL_2",
+			hidden: true
+		}),
+		domain: Flags.string({ description: "Focus domain readiness and recent email fields on one domain returned by the inbox status API." }),
+		json: Flags.boolean({ description: "Print the raw response envelope as JSON. With --domain, domain readiness and recent email fields are focused while endpoint, function, and next-action summaries remain account-level." }),
+		time: Flags.boolean({ description: TIME_FLAG_DESCRIPTION })
+	};
+	async run() {
+		const { flags } = await this.parse(InboxStatusCommand);
+		await runWithTiming(flags.time, async () => {
+			const { apiClient, auth, baseUrlOverridden } = await createAuthenticatedCliApiClient({
+				apiKey: flags["api-key"],
+				apiBaseUrl1: flags["api-base-url-1"],
+				apiBaseUrl2: flags["api-base-url-2"],
+				configDir: this.config.configDir
+			});
+			const result = await getInboxStatus({
+				client: apiClient.client,
+				responseStyle: "fields"
+			});
+			if (result.error) {
+				const errorPayload = extractErrorPayload(result.error);
+				writeErrorWithHints(errorPayload);
+				surfaceUnauthorizedHint({
+					auth,
+					baseUrlOverridden,
+					configDir: this.config.configDir,
+					payload: errorPayload
+				});
+				process.exitCode = 1;
+				return;
+			}
+			const envelope = result.data ?? {};
+			const status = envelope.data;
+			if (!status) throw new Errors.CLIError("Primitive API returned no inbox status.", { exit: 1 });
+			const outputStatus = flags.domain ? focusInboxStatus(status, flags.domain) : status;
+			if (flags.json) {
+				this.log(JSON.stringify({
+					...envelope,
+					data: outputStatus
+				}, null, 2));
+				return;
+			}
+			this.log(formatInboxStatus(outputStatus));
+		});
+	}
+};
+//#endregion
 //#region src/oclif/commands/login.ts
 const MAX_CLI_LOGIN_POLL_INTERVAL_SECONDS = 60;
 function cliError$3(message) {
@@ -17915,25 +18490,39 @@ var SigninOtpResendCommand = class SigninOtpResendCommand extends Command {
 };
 //#endregion
 //#region src/oclif/commands/whoami.ts
+function formatWhoamiSummary(account) {
+	return [
+		`Authenticated as ${account.email}`,
+		`Account id: ${account.id}`,
+		`Plan: ${account.plan}`
+	].join("\n");
+}
 var WhoamiCommand = class WhoamiCommand extends Command {
-	static description = `Print the account currently authenticated by saved OAuth credentials or an explicit API key. Useful as a credentials smoke test: confirms auth is live and shows which account it belongs to.`;
+	static description = `Print the account currently authenticated by saved OAuth credentials or an explicit API key. Useful as a credentials smoke test: confirms auth is live and shows which account it belongs to.
+
+  The default output is a concise human summary. Pass --json only when a script intentionally needs the full /account response.`;
 	static summary = "Print the authenticated account (credentials smoke test)";
-	static examples = ["<%= config.bin %> whoami", "<%= config.bin %> whoami --api-key prim_..."];
+	static examples = [
+		"<%= config.bin %> whoami",
+		"<%= config.bin %> whoami --api-key prim_...",
+		"<%= config.bin %> whoami --json | jq .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-1": Flags.string({
-			description: "Override the primary API base URL. Internal testing only; not documented to customers.",
+			description: API_BASE_URL_1_FLAG_DESCRIPTION,
 			env: "PRIMITIVE_API_BASE_URL_1",
 			hidden: true
 		}),
 		"api-base-url-2": Flags.string({
-			description: "Override the attachments-supporting send host base URL. Internal testing only; not documented to customers.",
+			description: API_BASE_URL_2_FLAG_DESCRIPTION,
 			env: "PRIMITIVE_API_BASE_URL_2",
 			hidden: true
 		}),
+		json: Flags.boolean({ description: "Print the full account JSON response. Default output hides setup and billing internals." }),
 		time: Flags.boolean({ description: TIME_FLAG_DESCRIPTION })
 	};
 	async run() {
@@ -17966,12 +18555,11 @@ var WhoamiCommand = class WhoamiCommand extends Command {
 				process.stderr.write("Server returned an empty account body; this should not happen for a valid key.\n");
 				throw new Errors.CLIError("unexpected empty response");
 			}
-			const onboarding = account.onboarding_completed === true ? "complete" : account.onboarding_step ? `in progress (step: ${account.onboarding_step})` : "incomplete";
-			process.stderr.write(`Authenticated as ${account.email}\n`);
-			process.stderr.write(`  Account id: ${account.id}\n`);
-			process.stderr.write(`  Plan:       ${account.plan}\n`);
-			process.stderr.write(`  Onboarding: ${onboarding}\n`);
-			this.log(JSON.stringify(account, null, 2));
+			if (flags.json) {
+				this.log(JSON.stringify(account, null, 2));
+				return;
+			}
+			this.log(formatWhoamiSummary(account));
 		});
 	}
 };
@@ -18225,7 +18813,11 @@ const DESCRIBE_OPERATION_ALIASES = {
 function resolveOperationAlias(id) {
 	return DESCRIBE_OPERATION_ALIASES[id] ?? id;
 }
-const OVERRIDDEN_OPERATION_IDS = new Set(["domains:download-domain-zone-file", "functions:test-function"]);
+const OVERRIDDEN_OPERATION_IDS = new Set([
+	"domains:download-domain-zone-file",
+	"functions:test-function",
+	"inbox:get-inbox-status"
+]);
 const generatedCommands = Object.fromEntries(operationManifest.filter((operation) => !OVERRIDDEN_OPERATION_IDS.has(operationId(operation))).map((operation) => [operationId(operation), createOperationCommand(operation)]));
 const COMMANDS = {
 	completion: CompletionCommand,
@@ -18257,6 +18849,8 @@ const COMMANDS = {
 	"emails:wait": EmailsWaitCommand,
 	"domains:zone-file": DomainsZoneFileCommand,
 	"domains:download-domain-zone-file": DomainsZoneFileCommand,
+	"inbox:status": InboxStatusCommand,
+	"inbox:get-inbox-status": InboxStatusCommand,
 	"functions:init": FunctionsInitCommand,
 	"functions:templates": FunctionsTemplatesCommand,
 	"functions:deploy": FunctionsDeployCommand,

package/man/primitive.1

@@ -0,0 +1,94 @@
+.TH PRIMITIVE 1
+.SH NAME
+primitive \- command line interface for Primitive email and Functions
+.SH SYNOPSIS
+.B primitive
+.I command
+[\fIoptions\fR]
+.br
+.B primitive
+.B --help
+.br
+.B primitive
+.I command
+.B --help
+.SH DESCRIPTION
+.B primitive
+is the command line interface for Primitive. It sends mail, inspects inbound and outbound email, manages domains and webhook endpoints, deploys Primitive Functions, and exposes generated API operations for scripting.
+.PP
+Most commands print human-readable output by default. Commands that expose JSON usually provide a
+.B --json
+flag or use generated operation output that can be piped into tools such as
+.BR jq (1).
+.SH AUTHENTICATION
+Commands use saved OAuth credentials from
+.B primitive signin
+or an API key from
+.B --api-key
+or
+.BR PRIMITIVE_API_KEY .
+.PP
+Run
+.B primitive whoami
+to verify which account the CLI is authenticated as.
+.SH COMMON COMMANDS
+.TP
+.B primitive send --to ADDRESS --subject SUBJECT --body TEXT
+Send an outbound email.
+.TP
+.B primitive send --to ADDRESS --body TEXT --attachment PATH
+Send an outbound email with a file attachment.
+.TP
+.B primitive domains add DOMAIN
+Start a custom-domain claim.
+.TP
+.B primitive domains verify --id DOMAIN_ID
+Verify DNS records for a pending domain claim.
+.TP
+.B primitive domains zone-file --id DOMAIN_ID
+Download DNS records as a BIND-format zone file.
+.TP
+.B primitive emails latest
+Show recent inbound emails.
+.TP
+.B primitive functions init NAME
+Scaffold a Primitive Function.
+.TP
+.B primitive functions deploy --name NAME --file PATH
+Deploy a Primitive Function bundle.
+.TP
+.B primitive list-operations
+Print the generated API operation manifest.
+.TP
+.B primitive describe COMMAND_OR_OPERATION
+Describe a generated API operation, including request and response schemas.
+.SH GLOBAL OPTIONS
+.TP
+.B --api-key KEY
+Use an explicit Primitive API key for this command.
+.TP
+.B --time
+Print command duration to standard error after completion.
+.TP
+.B --help
+Show command help.
+.SH ENVIRONMENT
+.TP
+.B PRIMITIVE_API_KEY
+API key used when
+.B --api-key
+is not supplied and no saved OAuth credential should be used.
+.TP
+.B PRIMITIVE_API_BASE_URL_1
+Override the primary API base URL. Intended for development and testing.
+.TP
+.B PRIMITIVE_API_BASE_URL_2
+Override the secondary API base URL used for selected send flows. Intended for development and testing.
+.SH FILES
+.TP
+.I ~/.config/primitive
+Default CLI configuration directory used by oclif on most systems.
+.SH SEE ALSO
+.B primitive --help
+.br
+Primitive documentation: https://primitive.dev

package/package.json

@@ -1,16 +1,20 @@
 {
   "name": "@primitivedotdev/cli",
-  "version": "0.31.4",
+  "version": "0.31.5",
   "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,
   "files": [
     "bin",
-    "dist"
+    "dist",
+    "man"
   ],
   "bin": {
     "primitive": "./bin/run.js"
   },
+  "man": [
+    "./man/primitive.1"
+  ],
   "oclif": {
     "bin": "primitive",
     "commands": {
@@ -40,6 +44,9 @@
       "domains": {
         "description": "Claim, verify, manage email domains, and download DNS zone files"
       },
+      "inbox": {
+        "description": "Check inbound email setup and processing readiness"
+      },
       "emails": {
         "description": "List, inspect, and wait for received emails. Prefer task aliases like `primitive emails list`, `primitive emails get`, `primitive emails latest`, `primitive emails wait`, and `primitive emails watch`; generated API names remain available for compatibility."
       },