@pithy-sh/cli 0.1.0

package/src/commands/email.ts

@@ -0,0 +1,425 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { CloudflareClients } from "@pithy-sh/cloudflare/src/client/clients";
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import type { WorkerDomains } from "@pithy-sh/core/src/naming/domains";
+import { type EmailCapability, isEmailCapability } from "@pithy-sh/email/src/capability";
+import { deprovisionEmail, provisionEmail } from "@pithy-sh/email/src/provision/provisionEmail";
+import { type RenderTracking, renderEmail } from "@pithy-sh/email/src/templates/engine";
+import { samplePayloads } from "@pithy-sh/email/src/templates/samples";
+import { managerWorkerName } from "@pithy-sh/secrets/src/provision/resolveManagerConfig";
+import type { ManagedEnvironment } from "@pithy-sh/secrets/src/scope";
+import { defineCommand } from "citty";
+import { parse } from "comment-json";
+import { createProjectCliAudit } from "../audit/cliAudit";
+import {
+  CloudflareEmailDeprovisioner,
+  CloudflareEmailProvisioner,
+  type EmailEnvResources,
+} from "../capabilities/emailProvisioner";
+import { type ConfirmedAccount, findOnConfirmedAccount } from "../cloudflare/accountAnswer";
+import { type CloudflareAccountSelection, cloudflareAccountConfirmation, cloudflareEnv } from "../cloudflare/config";
+import {
+  loadProject,
+  loadProjectEnvironments,
+  loadWorkerConfig,
+  loadWorkerDomains,
+  projectCloudflareAccount,
+  requireProjectName,
+} from "../project/config";
+import { resolveWorkerAddress } from "../project/workerAddress";
+import {
+  composedProjectCapabilities,
+  type ResolvedWorker,
+  resolveSingleWorker,
+  resolveWorkers,
+} from "../project/workerScope";
+import { formatDone, formatJsonLine, withErrorReporting } from "../terminal/output";
+
+/**
+ * The audit emitter for an email command. Provisioning spans every managed environment at once, so
+ * there is no single target env to key the audit database on — `"dev"` is the fallback (mirrors
+ * `pithy feature`'s convention for env-spanning commands). A no-op when creds or the audit capability
+ * aren't there.
+ */
+async function buildAudit(projectDir: string, accountId: string, apiToken: string) {
+  // `env` selects the audit database only, and defaults to `dev`: this command spans environments, so no
+  // single value is true for the run; each event states the environment it acted on.
+  return createProjectCliAudit({ projectDir, accountId, apiToken });
+}
+
+/**
+ * Load the composed email capability. Capabilities live in each Worker's `apps/<name>/pithy.config.ts`,
+ * and the config is one brand identity for the project, so the first Worker composing `email` provides
+ * it.
+ *
+ * The **capability**, not its `emailConfig`, because two of the three things a provision run stamps into
+ * the host's vars now come from it: the theme off `emailConfig`, and the catalogs off `hostCatalogs()`,
+ * which only answers correctly once `compose` has run. Returning the resolved config alone left the
+ * catalogs unreachable, and the `EMAIL_MESSAGES` var unwritten (pithy-sh/pithy#441).
+ *
+ * **The project's whole capability surface, assembled, and that is deliberate rather than a shortcut
+ * past per-Worker composition.** The Worker this stamps is `<project>-<env>-email`: it composes
+ * nothing, it is deployed once for the project, and it sends every Worker's mail. So the catalogs it
+ * carries are the project's, not one app Worker's — a project where `apps/web` composes `i18n()` and
+ * `apps/api` composes `email()` gets a host that speaks Spanish, which is the only useful answer for a
+ * Worker that belongs to neither. `capabilities/compose.ts` states the rule once for all three CLI
+ * sites that resolve a host.
+ *
+ * Exported for `capabilities/emailHostCatalogs.test.ts`, which is what proves this command reads a *composed*
+ * capability rather than a freshly built one — the wiring existed and nothing held the command to it.
+ * `resolve` is the filesystem seam that test drives it through.
+ */
+export async function loadEmailCapability(
+  projectDir: string,
+  resolve: (options: { projectDir: string }) => Promise<ResolvedWorker[]> = resolveWorkers,
+): Promise<EmailCapability> {
+  // A hook that refuses here refuses for the same reason the Worker would refuse to boot, which is
+  // worth knowing before a host is deployed for it rather than after.
+  const capabilities = await resolve({ projectDir }).then(composedProjectCapabilities);
+  const cap = capabilities.find(isEmailCapability);
+  if (!cap) {
+    throw new ValidationError({
+      message: "The email capability is not configured.",
+      action: "Add `email({ ... })` to a worker's pithy.config.ts (run `pithy add email`).",
+    });
+  }
+  return cap;
+}
+
+/**
+ * The Cloudflare credentials this command provisions with, for **the account the project belongs to**.
+ *
+ * The account is a parameter rather than an ambient, so this cannot resolve before something has
+ * established which account the project is for (#206).
+ *
+ * It also carries **what vouches for the account** (#378). A bare id is what every destructive and
+ * creative site here used to hold, and an id alone cannot tell "this account has no such Worker" from
+ * "I asked an account nothing claims" — the two arrive as one empty listing.
+ */
+function loadCloudflareCreds(account: CloudflareAccountSelection | null): {
+  account: ConfirmedAccount;
+  accountId: string;
+  apiToken: string;
+  storeId: string;
+} {
+  const vars = cloudflareEnv({ account });
+  const confirmation = cloudflareAccountConfirmation({ account });
+  const accountId = vars.CLOUDFLARE_ACCOUNT_ID ?? "";
+  const apiToken = vars.CLOUDFLARE_API_TOKEN ?? "";
+  const storeId = vars.SECRETS_STORE_ID ?? "";
+  if (!accountId || !apiToken) {
+    throw new ValidationError({
+      message: "Cloudflare credentials are missing.",
+      action: "Run pithy init to record CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN, or export them.",
+    });
+  }
+  if (!storeId) {
+    throw new ValidationError({
+      message: "The CF Secrets Store id is missing.",
+      action: "Run pithy add secrets to record SECRETS_STORE_ID (the email worker decrypts its signing key from it).",
+    });
+  }
+  return { account: { accountId, confirmation }, accountId, apiToken, storeId };
+}
+
+/** A wrangler env stanza — only the fields the email worker deploy reads from the project's config. */
+interface WranglerStanza {
+  d1_databases?: { binding: string; database_id?: string }[];
+  vars?: Record<string, string>;
+  env?: Record<string, WranglerStanza | undefined>;
+}
+
+/**
+ * Resolve the per-environment resources the email worker binds, from the **app Worker's** `wrangler.jsonc`
+ * (the app `DB` id and `BASE_URL` per env) and a live lookup of the env's secrets database. Each missing
+ * value throws an actionable error rather than deploying a half-wired worker.
+ *
+ * Which Worker is the app Worker? Every Worker owns its own `wrangler.jsonc`, so a project with several
+ * names one with `--worker`; one Worker needs no ceremony. `BASE_URL` in particular is that Worker's public
+ * URL — the address a tracked link resolves back to — so it is not something to guess.
+ */
+function buildResolveEnv(
+  worker: ResolvedWorker,
+  cf: CloudflareClients,
+  /**
+   * The project name the secrets database is found by — `<project>-<env>-secrets`. Resolved once by the
+   * caller via `requireProjectName`, never guessed: the lookup is by name, so a wrong one either reports
+   * a database that "does not exist" or binds another project's secrets store.
+   */
+  project: string,
+  /**
+   * The account the secrets database is looked for on, and what vouches for it (#378).
+   *
+   * The refusal below reads a missing database as "provision it first". Against an account nothing
+   * claims, that database is missing because this run asked the wrong account — and the sentence sends
+   * an operator to run a provisioning command they have already run.
+   */
+  account: ConfirmedAccount,
+): (env: ManagedEnvironment) => Promise<EmailEnvResources> {
+  return async (env) => {
+    const path = join(worker.dir, "wrangler.jsonc");
+    const config = parse(await readFile(path, "utf8")) as unknown as WranglerStanza;
+    const stanza = config.env?.[env];
+    if (!stanza) {
+      throw new ValidationError({
+        message: `${worker.name}'s wrangler.jsonc has no env.${env} stanza.`,
+        action: `Add the ${env} environment to ${path} with its DB binding and a BASE_URL var.`,
+      });
+    }
+    const appDatabaseId = stanza.d1_databases?.find((db) => db.binding === "DB")?.database_id;
+    if (!appDatabaseId) {
+      throw new ValidationError({
+        message: `${worker.name}'s wrangler.jsonc env.${env} has no DB database_id.`,
+        action: `Provision the ${env} app database and set its id on the DB binding.`,
+      });
+    }
+    // Through the one resolver, which prefers the `domains` declaration and falls back to the route and
+    // then to this same var — so an adopter who set it by hand still works, and one who declared a domain
+    // is not told to set a var that would only duplicate it. This used to read `vars.BASE_URL` directly
+    // with no validation at all, passing whatever string was there through to the deployed email Worker.
+    let domains: WorkerDomains | undefined;
+    try {
+      domains = loadWorkerDomains(await loadWorkerConfig(worker.dir));
+    } catch {
+      // A malformed declaration must not block provisioning off a good route or var; `pithy env` and
+      // `pithy deploy` are where it gets reported.
+      domains = undefined;
+    }
+    const address = resolveWorkerAddress({ environment: env, domains, stanza });
+    if (!address) {
+      throw new ValidationError({
+        message: `${worker.name} has no ${env} address.`,
+        action: `Declare it in the Worker's pithy.config.ts — \`domains: { ${env}: { pattern: "…", zone: "…" } }\`. Tracking and unsubscribe links are built against it.`,
+        detail: `no domains declaration, route, or vars.BASE_URL resolved for env.${env} in ${path}`,
+      });
+    }
+    const baseUrl = address.url;
+    const secretsDb = await findOnConfirmedAccount({
+      ...account,
+      what: `the ${managerWorkerName(project, env)} database`,
+      find: () => cf.d1Provisioner().findDatabaseByName(managerWorkerName(project, env)),
+    });
+    if (!secretsDb) {
+      throw new ValidationError({
+        message: `The ${env} secrets database (${managerWorkerName(project, env)}) does not exist.`,
+        action: "Run `pithy secrets provision` first — the email worker reads its signing key from it.",
+      });
+    }
+    return { appDatabaseId, secretsDatabaseId: secretsDb.uuid, baseUrl };
+  };
+}
+
+/** The three routing flags, in the order the refusal names them. */
+const ROUTING_FLAGS = ["--routing-zone", "--inbound-address", "--app-worker"] as const;
+
+/**
+ * The three routing flags, **together or not at all**.
+ *
+ * Routing is opt-in: the inbound address, its zone, and the worker that answers are an operator choice
+ * (and must avoid the apex MX), so none of them is derived and passing none is an ordinary run.
+ *
+ * A *partial* set is a different thing, and it used to be treated as the same thing — two flags of
+ * three wired nothing, said nothing, and exited 0. The consequence is invisible until somebody replies
+ * to a message and the mail goes nowhere, by which time nobody is looking at this command. A
+ * provisioning command that half-configures a mail path and reports success is worse than one that
+ * refuses.
+ *
+ * `pithy support` makes this decision already (`commands/support.ts` `resolveRouting`); this is the
+ * sibling's rule, with the missing flags named — that is the only thing the operator has to type next.
+ */
+export function resolveRouting(
+  zoneId: string | undefined,
+  address: string | undefined,
+  appWorkerName: string | undefined,
+): { zoneId: string; address: string; appWorkerName: string } | undefined {
+  if (zoneId && address && appWorkerName) return { zoneId, address, appWorkerName };
+  if (!zoneId && !address && !appWorkerName) return undefined;
+  const missing = [zoneId, address, appWorkerName]
+    .map((value, index) => (value ? undefined : ROUTING_FLAGS[index]))
+    .filter((flag): flag is (typeof ROUTING_FLAGS)[number] => flag !== undefined);
+  throw new ValidationError({
+    message: "The inbound routing options are incomplete.",
+    action: `Also pass ${missing.join(" and ")}, or none of the three. Inbound mail is routed only when ${ROUTING_FLAGS.join(", ")} are given together.`,
+    detail: `routing flags given: ${ROUTING_FLAGS.filter((flag) => !missing.includes(flag)).join(", ")}`,
+  });
+}
+
+const provision = defineCommand({
+  meta: { name: "provision", description: "Provision the shared suppression DB and per-environment email workers" },
+  args: {
+    json: { type: "boolean", default: false, description: "Machine-readable output" },
+    worker: {
+      type: "string",
+      description:
+        "The app worker whose wrangler.jsonc carries the per-environment DB binding and BASE_URL (default: the project's only worker)",
+    },
+    "routing-zone": {
+      type: "string",
+      description:
+        "Cloudflare Zone ID of the (sub)domain receiving the mail — Email Routing must already be enabled on it (its MX points to Cloudflare). Use a subdomain zone (e.g. bounce.example.com), never your apex, so your primary MX is untouched. Find it on the zone's Overview page.",
+    },
+    "inbound-address": {
+      type: "string",
+      description:
+        "The exact recipient address the rule matches (e.g. bounce@bounce.example.com); mail sent to it is delivered to the app worker's email() handler.",
+    },
+    "app-worker": {
+      type: "string",
+      description:
+        "Deployed name of your production app worker — the one running createEntrypoint with the email() bounce handler (e.g. pithy-app-prod).",
+    },
+  },
+  run: ({ args }) =>
+    withErrorReporting(args.json, async () => {
+      const projectDir = process.cwd();
+      // First, before the project name, the credentials, and every Cloudflare call: a mistyped or
+      // half-remembered flag set must cost nothing and must not provision anything.
+      const routing = resolveRouting(args["routing-zone"], args["inbound-address"], args["app-worker"]);
+      // The leading segment of the suppression database, the email workers, and the bounce rule. The
+      // database is found by name and reused, so `requireProjectName` refuses to guess — a guessed name
+      // adopts another project's opt-out list (docs/NAMING.md).
+      const config = await loadProject(projectDir);
+      const project = requireProjectName(config);
+      // The project's own environment set (#241): what this command fans out across, rather than a
+      // pair the CLI assumed. A project declaring `live` gets `live` provisioned and torn down too.
+      const environments = loadProjectEnvironments(config);
+      const { account, accountId, apiToken, storeId } = loadCloudflareCreds(await projectCloudflareAccount(projectDir));
+      const emailCapability = await loadEmailCapability(projectDir);
+      const appWorker = await resolveSingleWorker({
+        projectDir,
+        ...(args.worker !== undefined ? { worker: args.worker } : {}),
+      });
+      const cf = new CloudflareClients({ accountId, apiToken });
+      const provisioner = new CloudflareEmailProvisioner({
+        cf,
+        project,
+        account,
+        apiToken,
+        storeId,
+        theme: emailCapability.emailConfig.theme,
+        // Read now, after `loadEmailCapability` ran every capability's `compose` hook — the adopter's
+        // overrides and the kit's translations, flattened for the standalone host. Read before that,
+        // this is `{}` and the host is deployed English-only.
+        messages: emailCapability.hostCatalogs(),
+        resolveEnv: buildResolveEnv(appWorker, cf, project, account),
+        routing,
+        audit: await buildAudit(projectDir, accountId, apiToken),
+      });
+
+      const result = await provisionEmail(provisioner, environments);
+
+      if (args.json) {
+        process.stdout.write(`${formatJsonLine({ command: "email provision", ...result })}\n`);
+        return;
+      }
+      process.stdout.write(`Suppression database and ${result.environments.length} email workers ready.\n`);
+      process.stdout.write(`${formatDone()}\n`);
+    }),
+});
+
+const deprovision = defineCommand({
+  meta: { name: "deprovision", description: "Remove the email workers (and optionally the suppression DB)" },
+  args: {
+    suppression: {
+      type: "boolean",
+      default: false,
+      description: "Also delete this project's suppression DB (irreversible)",
+    },
+    json: { type: "boolean", default: false, description: "Machine-readable output" },
+  },
+  run: ({ args }) =>
+    withErrorReporting(args.json, async () => {
+      const projectDir = process.cwd();
+      // Teardown finds resources by recomputing their names, so this must be the same name
+      // `provision` used. A guess would match nothing, delete nothing, and still exit 0.
+      const config = await loadProject(projectDir);
+      const project = requireProjectName(config);
+      // The project's own environment set (#241): what this command fans out across, rather than a
+      // pair the CLI assumed. A project declaring `live` gets `live` provisioned and torn down too.
+      const environments = loadProjectEnvironments(config);
+      const { account, accountId, apiToken } = loadCloudflareCreds(await projectCloudflareAccount(projectDir));
+      const cf = new CloudflareClients({ accountId, apiToken });
+      const deprovisioner = new CloudflareEmailDeprovisioner({
+        account,
+        cf,
+        project,
+        audit: await buildAudit(projectDir, accountId, apiToken),
+      });
+
+      await deprovisionEmail(deprovisioner, environments, { deleteSuppression: args.suppression });
+
+      if (args.json) {
+        process.stdout.write(
+          `${formatJsonLine({ command: "email deprovision", suppressionDeleted: args.suppression })}\n`,
+        );
+        return;
+      }
+      process.stdout.write(`Email workers removed${args.suppression ? ", including the suppression database" : ""}.\n`);
+      process.stdout.write(`${formatDone()}\n`);
+    }),
+});
+
+const test = defineCommand({
+  meta: { name: "test", description: "Render one template through your config and send it to an address" },
+  args: {
+    to: { type: "string", description: "Recipient address", required: true },
+    template: { type: "string", default: "welcome", description: "Template id (e.g. magicLink, newsletter)" },
+    from: { type: "string", description: "Override the configured from address" },
+    json: { type: "boolean", default: false, description: "Machine-readable output" },
+  },
+  run: ({ args }) =>
+    withErrorReporting(args.json, async () => {
+      const projectDir = process.cwd();
+      const { accountId, apiToken } = loadCloudflareCreds(await projectCloudflareAccount(projectDir));
+      const { fromAddress, fromName, baseUrl, theme } = (await loadEmailCapability(projectDir)).emailConfig;
+      const payload = samplePayloads[args.template];
+      if (!payload) {
+        throw new ValidationError({
+          message: `No sample payload for template "${args.template}".`,
+          action: `Known templates: ${Object.keys(samplePayloads).join(", ")}.`,
+        });
+      }
+
+      // A throwaway tracking context so any template (incl. marketing, which forces an unsubscribe link)
+      // renders. Links are not actually tracked — this is a visual/delivery check of the config.
+      const tracking: RenderTracking = {
+        baseUrl,
+        jobId: "test",
+        recipient: args.to,
+        key: "email-test-preview-key",
+        kid: "test",
+        expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
+        openTracking: false,
+        clickTracking: false,
+      };
+      const rendered = await renderEmail(args.template, payload, theme, tracking);
+      const from = args.from ?? fromAddress;
+      const result = await new CloudflareClients({ accountId, apiToken }).email().send({
+        to: args.to,
+        from: { email: from, name: fromName },
+        subject: rendered.subject,
+        html: rendered.html,
+        text: rendered.text,
+      });
+
+      if (args.json) {
+        process.stdout.write(
+          `${formatJsonLine({ command: "email test", template: args.template, to: args.to, from, messageId: result.messageId })}\n`,
+        );
+        return;
+      }
+      process.stdout.write(
+        `Sent "${args.template}" from ${from} to ${args.to}${result.messageId ? ` (${result.messageId})` : ""}.\n`,
+      );
+      process.stdout.write(`${formatDone()}\n`);
+    }),
+});
+
+export default defineCommand({
+  meta: { name: "email", description: "Provision and manage the email infrastructure" },
+  subCommands: { provision, deprovision, test },
+});

package/src/commands/env.ts

@@ -0,0 +1,155 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { defineCommand } from "citty";
+import { projectCloudflareAccount } from "../project/config";
+import { buildEnvInventory, type EnvInventory, type EnvResource } from "../project/envInventory";
+import { formatJsonLine, withErrorReporting } from "../terminal/output";
+import { dim, link, supportsHyperlinks } from "../terminal/style";
+
+/**
+ * `pithy env [name] [--worker <name>] [--json]` — a read-only inventory of every environment every
+ * Worker declares in its own `wrangler.jsonc`: its bindings, resolved ids, provisioned state, base
+ * URL, and Cloudflare dashboard links. It writes nothing, switches nothing, and always exits 0 —
+ * provisioning health and non-zero exits belong to `pithy doctor`. A resource id renders as a
+ * clickable OSC-8 hyperlink to its dashboard page in a terminal, falling back to a printed URL when
+ * hyperlinks are off (piped output / NO_COLOR); `--json` always carries the full `dashboardUrl` per
+ * resource. The positional `name` narrows to one environment across every Worker; `--worker` narrows
+ * to one Worker.
+ */
+
+/** A short parenthetical label for a resource kind. */
+const KIND_LABEL: Record<EnvResource["kind"], string> = {
+  d1: "d1",
+  kv: "kv",
+  r2: "r2",
+  durable_object: "do",
+};
+
+/**
+ * What an unprovisioned binding reads as in a **deployed** environment: an action item, and the reason
+ * `pithy env` is read before and after provisioning.
+ */
+const NOT_PROVISIONED = "not provisioned";
+
+/**
+ * What an unprovisioned binding reads as in a **local** environment: a statement, not an action item.
+ *
+ * **A check that cannot fail meaningfully for an environment should not be run against it.** There is
+ * no remote `dash-dev-db` and there is not supposed to be one — Miniflare serves D1 from the binding
+ * declaration, with state under `.wrangler/state/v3/d1`, and `pithy dev` works precisely because no
+ * Cloudflare resource is involved. Reporting three such bindings as deficiencies taught an operator to
+ * skim past red in the one command they read against production (#320).
+ *
+ * Deliberately not the same string as the deployed one. Sharing it is what made the real action item
+ * weaker.
+ */
+const LOCAL = "local";
+
+/**
+ * The half `local` does not cover, said once per stanza rather than once per binding.
+ *
+ * **The top-level stanza is the local environment and the stanza a bare `pithy deploy` ships.** `wrangler
+ * deploy` with no `--env` takes it to Cloudflare, and it is the one deploy path with no
+ * `assertEnvironmentProvisioned` in front of it — every `--env` deploy is refused before a binding with
+ * no id reaches wrangler (#240), and this one is not. So `local` is a true statement about Miniflare and
+ * an incomplete one about the file: an operator reading `pithy env` before a deploy read it as *nothing
+ * to provision here* (#320 gave the word, this gives back what it took).
+ *
+ * A property of the stanza, so it is printed under the stanza, and only where it is a fact — a local
+ * environment whose bindings all carry ids has nothing ungated about it, and a deployed one already says
+ * `not provisioned`, which is the action item. A line under every environment would be the wallpaper the
+ * word was introduced to remove.
+ */
+const UNGATED = "Miniflare needs no id. A bare pithy deploy ships this stanza, and nothing gates it on one.";
+
+/**
+ * Render an id-carrying value: the resource's state when it has no id, a clickable link when
+ * hyperlinks render and a dashboard URL exists, the plain id + printed URL as the fallback, or the
+ * bare id when there is no URL (no account id, or an unlinkable kind).
+ *
+ * `local` is the environment's own answer, carried on the report rather than guessed from its name — a
+ * local environment that *does* name a real id still shows it, because pointing dev at a remote
+ * database is a thing an adopter may do and the id is the true and useful thing to print.
+ */
+function renderValue(id: string | null, provisioned: boolean, url: string | null, local: boolean): string {
+  if (!provisioned) return dim(local ? LOCAL : NOT_PROVISIONED);
+  const text = id ?? "";
+  if (!url) return text;
+  if (supportsHyperlinks()) return link(url, text);
+  return `${text}  ${dim(url)}`;
+}
+
+/**
+ * Render the full human-readable inventory as a single string, optionally filtered to one environment.
+ * Workers are the outer grouping — each Worker's name, then its environments indented beneath, then
+ * each environment's bindings. A Worker with no matching environment is reported as such, not omitted.
+ */
+export function renderEnvInventory(inventory: EnvInventory, filter?: string): string {
+  return renderLines(inventory, filter).join("\n").concat("\n");
+}
+
+/** The rendered lines, before they are joined — the seam a gate reads so it can assert per line. */
+export function renderLines(inventory: EnvInventory, filter?: string): string[] {
+  const lines: string[] = [];
+  if (!inventory.accountId) lines.push(dim("No CLOUDFLARE_ACCOUNT_ID. Dashboard links omitted."));
+
+  for (const worker of inventory.workers) {
+    lines.push(`${worker.worker}  ${dim(worker.dir)}`);
+
+    const environments = filter
+      ? worker.environments.filter((environment) => environment.name === filter)
+      : worker.environments;
+    if (environments.length === 0) {
+      lines.push(`  ${dim(`No environment named ${filter}.`)}`);
+      continue;
+    }
+
+    for (const environment of environments) {
+      lines.push(`  ${environment.name}  ${dim(environment.baseUrl ?? "no url")}`);
+      if (environment.scriptName) {
+        lines.push(
+          `    worker  ${renderValue(environment.scriptName, true, environment.workerDashboardUrl, environment.local)}`,
+        );
+      }
+      for (const resource of environment.resources) {
+        lines.push(
+          `    ${resource.binding} (${KIND_LABEL[resource.kind]})  ${renderValue(resource.id, resource.provisioned, resource.dashboardUrl, environment.local)}`,
+        );
+      }
+      if (environment.local && environment.resources.some((resource) => !resource.provisioned)) {
+        lines.push(`    ${dim(UNGATED)}`);
+      }
+    }
+  }
+  return lines;
+}
+
+export default defineCommand({
+  meta: {
+    name: "env",
+    description: "Inventory every worker's environments: bindings, ids, provisioned state, dashboard links",
+  },
+  args: {
+    name: { type: "positional", required: false, description: "Show only this environment (e.g. staging)" },
+    worker: { type: "string", description: "Show only this worker (default: every worker under apps/)" },
+    json: { type: "boolean", default: false, description: "Machine-readable output" },
+  },
+  run: ({ args }) =>
+    withErrorReporting(args.json, async () => {
+      const projectDir = process.cwd();
+      // The account first, from the project's own config: the inventory *prints* an account id and
+      // builds every dashboard link out of it, so resolving one this project did not claim labels its
+      // bindings with another company's account and links there (#206).
+      const inventory = await buildEnvInventory({
+        projectDir,
+        account: await projectCloudflareAccount(projectDir),
+        ...(args.worker ? { worker: args.worker } : {}),
+      });
+      if (args.json) {
+        process.stdout.write(`${formatJsonLine({ command: "env", ...inventory })}\n`);
+        return;
+      }
+      process.stdout.write(renderEnvInventory(inventory, args.name));
+    }),
+});