@dench.com/cli 0.4.6 → 0.4.8

package/README.md

@@ -23,7 +23,27 @@ dench login --name "AI Agent - Billing Repo"
 to lowercase snake_case before send (e.g. `--kind "Claude Code"` becomes
 `claude_code`).
 
-The default host is `https://dench.dev`.
+The default backend is `https://dench.dev` (production). Use `dench backend`
+to switch:
+
+```bash
+dench backend show
+dench backend set production
+dench backend set staging
+dench backend set local                  # http://localhost:3000
+dench backend set https://example.com    # custom URL
+dench backend clear                      # revert to production
+```
+
+For one-shot overrides (no config change):
+
+```bash
+dench --prod <cmd>
+dench --staging <cmd>
+dench --backend local <cmd>
+dench --host https://example.com <cmd>
+DENCH_HOST=https://example.com dench <cmd>
+```
 
 The smooth setup flow is:
 
@@ -197,13 +217,31 @@ Auth precedence:
 
 1. Explicit `--dev` flag → use the dev workspace env (`NEXT_PUBLIC_CONVEX_URL`,
    `DENCH_WORKSPACE`, `DENCH_DEV_AGENT_KEY`).
-2. A locally-stored `dench login` session for the current host.
+2. A locally-stored `dench login` session for the current backend (set via
+   `dench backend`, `--host`, `--prod`, or `--staging`).
 3. `DENCH_API_KEY` + `CONVEX_URL` (sandbox / automation path).
 
 Plain terminal usage does not silently fall back to dev env vars. Without
 `--dev`, a saved session, or `DENCH_API_KEY` + `CONVEX_URL`, live commands
 return `login_required`.
 
+### `.env` auto-load is opt-in
+
+When `dench` runs from inside the `dench.com` repo it does **not**
+auto-load workspace `.env` / `.env.local` files by default — that used
+to silently flip `NEXT_PUBLIC_CONVEX_URL` to the dev Convex deployment
+and made the CLI talk to local Convex even when the user expected
+production.
+
+Auto-load now turns on only when one of:
+
+- `--dev` (also switches the runtime to dev-workspace mode)
+- `--use-dev-env` (load `.env` files but keep the rest of the runtime)
+- `DENCH_USE_DEV_ENV=1` in the shell env (e.g. via `direnv`)
+- `dench backend set local` (a stored local backend implies dev env)
+
+Explicit shell exports (`GATEWAY_URL=… ./dench …`) always win regardless.
+
 Commands that need to impersonate a specific agent (`dench memory`,
 `dench task`, `dench claim`, `dench log`, `dench approval request`,
 etc.) still require an agent session (`dench login`) — the unified API

package/crm.ts

@@ -412,6 +412,9 @@ const api = {
       "functions/crm/actions:startActionRun",
     ),
   },
+  members: {
+    list: makeFunctionReference<"query">("functions/crm/members:list"),
+  },
 };
 
 export async function runCrmCommand(opts: {
@@ -472,11 +475,31 @@ export async function runCrmCommand(opts: {
       return await runDocsCommand(ctx);
     case "actions":
       return await runActionsCommand(ctx);
+    case "members":
+      // Alias for `dench members` so the AI agent finds the roster
+      // surface from inside the `dench crm` namespace it's primed
+      // on. Delegates to the shared implementation in cli/members.ts
+      // so payload formatting + flag handling stay in lockstep.
+      return await runCrmMembersCommand(ctx);
     default:
       throw new CrmCliError(`Unknown crm subcommand: ${subcommand}`);
   }
 }
 
+async function runCrmMembersCommand(ctx: CrmCliContext): Promise<void> {
+  const { runMembersCommand } = await import("./members");
+  // Re-prepend `--json` so the members dispatcher's own `hasFlag`
+  // pass sees it again — we already drained it once when computing
+  // `ctx.jsonOutput`, but the members CLI re-parses argv from scratch
+  // (same shape as a top-level invocation).
+  const args = ctx.jsonOutput ? ["--json", ...ctx.args] : [...ctx.args];
+  await runMembersCommand({
+    convex: ctx.convex,
+    args,
+    sessionToken: ctx.sessionToken,
+  });
+}
+
 async function runObjectsCommand(ctx: CrmCliContext): Promise<void> {
   const verb = ctx.args.shift();
   switch (verb) {
@@ -1653,7 +1676,7 @@ async function callEnrichmentGatewayForEntry(args: {
 
 async function enrichOneEntry(
   ctx: CrmCliContext,
-  args: CellEnrichmentArgs & {
+  args: Omit<CellEnrichmentArgs, "entryId"> & {
     target: EnrichmentTarget;
     entry: CrmEntryForEnrichment;
   },
@@ -2057,6 +2080,15 @@ Statuses (kanban columns):
   dench crm statuses list <object>
   dench crm statuses set <object> --statuses '[{"name":"New","color":"#94a3b8"},...]'
 
+Workspace members (for user-type fields):
+  dench crm members list [--json]              (alias: dench members list)
+      List \`{ userId, role, name, email }\` for every member of the
+      current org. Use the userIds when setting \`Owner\`, \`Assignee\`,
+      or any other \`user\`-type field so the UI shows a real linked
+      avatar instead of an unlinked literal-string badge:
+        dench crm cells set task --entry <id> --field Owner --value <userId>
+        dench crm entries create task --data '{"Name":"X","Owner":"<userId>"}'
+
 Batch:
   dench crm batch --file ops.jsonl [--idempotency-key <key>]
   For repeated writes, prefer entries create-many/update-many or cells set-many;

package/dench.ts

@@ -18,7 +18,12 @@ import { agentKindLabel, normalizeAgentKind } from "./agentKind";
 import {
   DEFAULT_HOST,
   isLocalHost,
+  LOCAL_HOST,
   normalizeHost,
+  PRODUCTION_API_URL,
+  PRODUCTION_CONVEX_URL,
+  PRODUCTION_HOST,
+  resolveBackendAlias,
   resolveHostFromArgs,
   STAGING_HOST,
 } from "./host";
@@ -29,7 +34,6 @@ import {
   listStoredSessionEntries,
   removeAllStoredSessions,
   removeStoredSession,
-  resolveConfigHost,
   resolveSessionScope,
   type SessionScope,
   type StoredSessionEntry,
@@ -65,6 +69,24 @@ type StoredSession = {
 };
 
 type ConfigFile = {
+  /**
+   * Explicit user choice of which Dench backend to talk to by default,
+   * set via `dench backend set <local|staging|prod|<url>>`. Takes
+   * precedence over the legacy `currentHost` field (which used to be
+   * silently updated by every `dench login` and caused the CLI to
+   * silently follow the last-logged-in environment).
+   *
+   * Resolution order in `resolveHost`:
+   *   1. CLI flags (`--prod`, `--staging`, `--backend`, `--host`)
+   *   2. `DENCH_HOST` env var
+   *   3. `defaultBackend` from this config
+   *   4. `PRODUCTION_HOST` (the safe fallback)
+   *
+   * `currentHost` / `currentHosts` / `currentSessionKey` /
+   * `currentSessionKeys` keep their old role of remembering which
+   * stored session to use, but they no longer drive backend choice.
+   */
+  defaultBackend?: string;
   currentHost?: string;
   currentSessionKey?: string;
   currentHosts?: Record<string, string>;
@@ -244,6 +266,7 @@ const BOOLEAN_FLAGS = new Set([
   "--staging",
   "--prod",
   "--no-open",
+  "--use-dev-env",
   "--version",
   "--yolo",
   "--ask-before-publishing",
@@ -407,6 +430,7 @@ Usage:
   dench sessions [--host <host>] [--json]
   dench use <session-key-or-workspace-slug> [--host <host>] [--json]
   dench logout [session-key-or-workspace-slug] [--session <key-or-scope>] [--host <host>] [--all] [--json]
+  dench backend [show|set|clear] [<production|staging|local|<url>>] [--json]
   dench context [--json]
   dench status [--mine|--self] [--json]
   dench tasks [--json]
@@ -454,6 +478,13 @@ CRM (Daytona-native rewrite):
   Batch write helpers: entries create-many/update-many, cells set-many
   Help: dench crm help
 
+Workspace members (for CRM \`user\`-type fields):
+  dench members list [--json]                  (top-level alias)
+  dench crm members list [--json]              (canonical CRM-scoped name)
+      Look up real userIds for the active org so \`Owner\` / \`Assignee\`
+      cells assign to real members instead of being stored as unlinked
+      display-name strings. See \`dench members help\`.
+
 Live web search (Exa via the Dench Cloud Gateway, auths with DENCH_API_KEY):
   dench search "<query>" [--num-results N] [--type auto|fast|deep|deep-reasoning|neural] [--category news|company|people|...] [--include-domains a.com,b.com] [--exclude-domains c.com] [--max-chars 800] [--json]
   dench search contents <url> [<url>...] [--max-chars 4000] [--summary "..."] [--json]
@@ -549,13 +580,25 @@ Agent setup:
   Use dench memory and dench artifacts to continue from durable context.
   Do not create, claim, or log a setup task by default.
 
-Hosts:
-  Default production host: ${DEFAULT_HOST}
-  Staging: dench login --staging
-  Staging with explicit host: dench login --host ${STAGING_HOST}
-
-Dev fallback:
+Backends and hosts:
+  Default backend: ${DEFAULT_HOST} (overridden by \`dench backend set\`)
+  Show / change the persistent default:
+    dench backend show
+    dench backend set production | staging | local | <url>
+    dench backend clear
+  One-shot overrides for a single command:
+    dench --prod <cmd>
+    dench --staging <cmd>
+    dench --backend local <cmd>
+    dench --host https://example.com <cmd>
+    DENCH_HOST=https://example.com dench <cmd>
+
+Dev fallback (run against a local Convex deployment with a dev key):
   DENCH_DEV_AGENT_KEY=... DENCH_WORKSPACE=... NEXT_PUBLIC_CONVEX_URL=... dench status --dev
+  Inside the dench.com repo, --dev also auto-loads .env / .env.local
+  so GATEWAY_URL etc. flow through. Use --use-dev-env (or
+  DENCH_USE_DEV_ENV=1) when you want that auto-load without switching
+  the runtime to the dev workspace mode.
 
 Advanced:
   For long-lived agents or when the human asks:
@@ -728,8 +771,49 @@ Notes:
 `);
 }
 
-function resolveHost(config: ConfigFile | undefined, scope: SessionScope) {
-  return resolveHostFromArgs(filteredArgs, resolveConfigHost(config, scope));
+function backendHelp() {
+  console.log(`Dench backend
+
+Usage:
+  dench backend                                         # alias for "show"
+  dench backend show [--json]
+  dench backend set <production|staging|local|<url>> [--json]
+  dench backend clear [--json]
+
+Aliases: prod = production, dev / localhost = local, stage = staging.
+
+What this does:
+  The default Dench backend is production (${PRODUCTION_HOST}). "dench backend set"
+  stores an explicit override in ~/.dench/config.json so every future
+  "dench" invocation talks to that backend by default. Use it instead of
+  relying on a stale currentHost from a past "dench login".
+
+  Setting the backend to "local" also opts the CLI into auto-loading
+  .env and .env.local from the dench.com workspace at startup, which is
+  needed for GATEWAY_URL and similar local-only env vars.
+
+One-shot overrides (no config change):
+  dench --prod <cmd>             # one command against production
+  dench --staging <cmd>          # one command against staging
+  dench --backend local <cmd>    # one command against http://localhost:3000
+  dench --host https://… <cmd>   # one command against a custom URL
+  DENCH_HOST=https://… dench …   # same, via env
+
+Opt into dev .env auto-loading without changing the default backend:
+  --use-dev-env             # one-shot flag
+  DENCH_USE_DEV_ENV=1       # env var (e.g. via direnv)
+`);
+}
+
+function resolveHost(config: ConfigFile | undefined, _scope: SessionScope) {
+  // `defaultBackend` is only ever set via `dench backend set`, so it
+  // represents an explicit user choice. Production wins on fresh
+  // installs (no flags, no env, no config) — which is the safe default
+  // for an agent CLI. The per-scope `currentHosts[scope.key]` map is
+  // intentionally NOT consulted here so that a past `dench login
+  // --host http://localhost:3000` doesn't silently keep routing every
+  // future command at local dev.
+  return resolveHostFromArgs(filteredArgs, config?.defaultBackend);
 }
 
 async function loadConfig(): Promise<ConfigFile> {
@@ -868,6 +952,194 @@ function formatSessionChoices(
   return lines.length > 0 ? lines.join("\n") : "  No Dench sessions found.";
 }
 
+function backendLabelForHost(host: string) {
+  const normalized = normalizeHost(host);
+  if (normalized === PRODUCTION_HOST) return "production";
+  if (normalized === STAGING_HOST) return "staging";
+  if (isLocalHost(normalized)) return "local";
+  return "custom";
+}
+
+function backendSnapshot(config: ConfigFile) {
+  const resolved = resolveHost(config, {
+    key: "auto:backend-show",
+    label: "cwd",
+  });
+  const stored = config.defaultBackend?.trim()
+    ? normalizeHost(config.defaultBackend.trim())
+    : null;
+  const envHost = process.env.DENCH_HOST?.trim() || null;
+  const argBackend =
+    option("--backend") ?? (hasFlag("--prod")
+      ? "production"
+      : hasFlag("--staging")
+        ? "staging"
+        : option("--host") ?? null);
+
+  let source: "flag" | "env" | "config" | "default";
+  if (argBackend) source = "flag";
+  else if (envHost) source = "env";
+  else if (stored) source = "config";
+  else source = "default";
+
+  return {
+    host: resolved,
+    label: backendLabelForHost(resolved),
+    source,
+    defaultBackend: stored,
+    envHost,
+    knownBackends: {
+      production: PRODUCTION_HOST,
+      staging: STAGING_HOST,
+      local: LOCAL_HOST,
+    },
+  };
+}
+
+function formatBackendShow(snapshot: ReturnType<typeof backendSnapshot>) {
+  const sourceHint =
+    snapshot.source === "flag"
+      ? "(set via CLI flag for this invocation)"
+      : snapshot.source === "env"
+        ? "(set via DENCH_HOST env var)"
+        : snapshot.source === "config"
+          ? "(set via `dench backend set`)"
+          : "(default — no explicit choice in env or config)";
+  const lines = [
+    `Active backend: ${snapshot.host} [${snapshot.label}] ${sourceHint}`,
+  ];
+  if (snapshot.defaultBackend && snapshot.source !== "config") {
+    lines.push(`Stored default backend: ${snapshot.defaultBackend}`);
+  }
+  if (snapshot.envHost) {
+    lines.push(`DENCH_HOST env: ${snapshot.envHost}`);
+  }
+  lines.push(
+    "",
+    "Manage default backend:",
+    "  dench backend set production            # default fallback",
+    "  dench backend set staging",
+    "  dench backend set local                 # http://localhost:3000",
+    "  dench backend set https://example.com   # custom URL",
+    "  dench backend clear                     # revert to production default",
+    "",
+    "One-shot override flags also work on every command:",
+    "  dench --prod <cmd>     dench --staging <cmd>",
+    "  dench --backend local <cmd>     dench --host https://example.com <cmd>",
+  );
+  return lines.join("\n");
+}
+
+async function backendShow() {
+  const config = await loadConfig();
+  const snapshot = backendSnapshot(config);
+  print(json ? snapshot : formatBackendShow(snapshot));
+}
+
+async function backendSet() {
+  const target = positional(2);
+  if (!target) {
+    throw new CliError(
+      "Missing backend value. Pass local, staging, prod, or a URL.",
+      {
+        code: "backend_set_missing_value",
+        nextActions: [
+          "Run dench backend set production.",
+          "Run dench backend set local.",
+          "Run dench backend set https://your-host.example.com.",
+        ],
+      },
+    );
+  }
+  let resolved: string;
+  try {
+    resolved = resolveBackendAlias(target);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new CliError(message, {
+      code: "backend_set_invalid_value",
+      nextActions: [
+        "Run dench backend set production / staging / local.",
+        "Or pass an explicit URL: dench backend set https://your-host.example.com.",
+      ],
+    });
+  }
+  const config = await loadConfig();
+  await saveConfig({ ...config, defaultBackend: resolved });
+  const label = backendLabelForHost(resolved);
+  if (json) {
+    print({
+      ok: true,
+      defaultBackend: resolved,
+      label,
+      message: `Default Dench backend set to ${resolved} (${label}).`,
+    });
+    return;
+  }
+  print(`Default Dench backend set to ${resolved} (${label}).`);
+  if (label === "local") {
+    print(
+      "Local backend selected. dench will now also load .env / .env.local from the workspace so GATEWAY_URL etc. are picked up.",
+    );
+  }
+  print("Future `dench` commands without --prod/--staging/--host will target this backend.");
+}
+
+async function backendClear() {
+  const config = await loadConfig();
+  if (!config.defaultBackend) {
+    print(
+      json
+        ? { ok: true, cleared: false, defaultBackend: null }
+        : "No default backend is set. dench already falls back to production.",
+    );
+    return;
+  }
+  const previous = config.defaultBackend;
+  const next: ConfigFile = { ...config };
+  delete next.defaultBackend;
+  await saveConfig(next);
+  print(
+    json
+      ? {
+          ok: true,
+          cleared: true,
+          previous,
+          defaultBackend: null,
+          fallback: PRODUCTION_HOST,
+        }
+      : `Cleared default backend (was ${previous}). dench will fall back to ${PRODUCTION_HOST}.`,
+  );
+}
+
+async function runBackendCommand() {
+  const sub = positional(1);
+  if (!sub || sub === "show" || sub === "status") {
+    await backendShow();
+    return;
+  }
+  if (sub === "set") {
+    await backendSet();
+    return;
+  }
+  if (sub === "clear" || sub === "reset" || sub === "unset") {
+    await backendClear();
+    return;
+  }
+  if (sub === "help" || sub === "--help" || sub === "-h") {
+    backendHelp();
+    return;
+  }
+  throw new CliError(`Unknown dench backend subcommand: ${sub}`, {
+    code: "unknown_backend_subcommand",
+    nextActions: [
+      "Run dench backend show to print the active backend.",
+      "Run dench backend set <local|staging|prod|<url>>.",
+      "Run dench backend clear to revert to production.",
+    ],
+  });
+}
+
 async function listSessions() {
   const config = await loadConfig();
   const scope = resolveSessionScope({ args: filteredArgs });
@@ -1487,12 +1759,37 @@ function hasDevEnv() {
  * dev typically only has `NEXT_PUBLIC_CONVEX_URL` exported. We accept
  * either so the same code path works in both shells without callers
  * needing to know which env var is set.
+ *
+ * When neither env var is set we fall back to the baked-in production
+ * Convex URL (`PRODUCTION_CONVEX_URL`). This is a deliberate
+ * defense-in-depth move: if a sandbox is provisioned while a Vercel
+ * deployment is half-configured and `CONVEX_URL` lands as empty
+ * string, the CLI inside it still ends up pointed at the production
+ * deployment instead of crashing on a "missing Convex URL" error.
+ * Dev / staging shells override this by exporting `CONVEX_URL` or
+ * `NEXT_PUBLIC_CONVEX_URL` explicitly.
  */
 function resolveApiKeyConvexUrl(): string | undefined {
   return (
     process.env.CONVEX_URL?.trim() ||
     process.env.NEXT_PUBLIC_CONVEX_URL?.trim() ||
-    undefined
+    PRODUCTION_CONVEX_URL
+  );
+}
+
+/**
+ * Resolve the Next.js API host the CLI should hit for HTTP calls (e.g.
+ * Stripe billing topup, the gateway proxy). Same defense-in-depth
+ * pattern as `resolveApiKeyConvexUrl`: env wins, then the resolved
+ * Dench host the runtime is targeting, and finally
+ * `PRODUCTION_API_URL` as the last resort.
+ */
+function resolveApiHost(fallbackHost: string): string {
+  return (
+    process.env.DENCH_API_URL?.trim() ||
+    process.env.DENCH_INTERNAL_BASE?.trim() ||
+    fallbackHost ||
+    PRODUCTION_API_URL
   );
 }
 
@@ -1556,10 +1853,7 @@ async function getRuntime() {
     if (sandboxAgentToken && sandboxConvexUrl) {
       const orgId = process.env.DENCH_ORG_ID?.trim();
       const orgSlug = process.env.DENCH_ORG_SLUG?.trim();
-      const apiHost =
-        process.env.DENCH_API_URL?.trim() ||
-        process.env.DENCH_INTERNAL_BASE?.trim() ||
-        host;
+      const apiHost = resolveApiHost(host);
       return {
         mode: "session" as const,
         host: apiHost,
@@ -1583,10 +1877,7 @@ async function getRuntime() {
     if (apiKey && convexUrl) {
       const orgId = process.env.DENCH_ORG_ID?.trim();
       const orgSlug = process.env.DENCH_ORG_SLUG?.trim();
-      const apiHost =
-        process.env.DENCH_API_URL?.trim() ||
-        process.env.DENCH_INTERNAL_BASE?.trim() ||
-        host;
+      const apiHost = resolveApiHost(host);
       return {
         mode: "apiKey" as const,
         host: apiHost,
@@ -1619,8 +1910,13 @@ async function getRuntime() {
 type Runtime = Awaited<ReturnType<typeof getRuntime>>;
 
 function stripRuntimeFlags(args: string[]) {
-  const booleanFlags = new Set(["--dev", "--prod", "--staging"]);
-  const valueFlags = new Set(["--convex-url", "--host"]);
+  const booleanFlags = new Set([
+    "--dev",
+    "--prod",
+    "--staging",
+    "--use-dev-env",
+  ]);
+  const valueFlags = new Set(["--convex-url", "--host", "--backend"]);
   const stripped: string[] = [];
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -2937,6 +3233,14 @@ async function main() {
     return;
   }
 
+  if (
+    command === "backend" &&
+    (subcommand === "help" || hasFlag("--help"))
+  ) {
+    backendHelp();
+    return;
+  }
+
   if (command === "crm") {
     const subArgs = stripRuntimeFlags(args.slice(args.indexOf("crm") + 1));
     const sub = subArgs[0];
@@ -2975,6 +3279,46 @@ async function main() {
     return;
   }
 
+  if (command === "members") {
+    // Top-level convenience surface for the same Convex query that
+    // `dench crm members list` calls. Lives here (rather than only
+    // under `dench crm`) so it shows up in top-level help and tab
+    // completion — members aren't strictly a CRM concept, even though
+    // the canonical caller today is the AI agent looking up userIds
+    // for `user`-typed CRM cells.
+    const subArgs = stripRuntimeFlags(args.slice(args.indexOf("members") + 1));
+    const sub = subArgs[0];
+    if (!sub || sub === "help" || sub === "--help") {
+      const { runMembersCommand } = await import("./members");
+      // biome-ignore lint/suspicious/noExplicitAny: harmless help-only stub
+      await runMembersCommand({ convex: {} as any, args: subArgs });
+      return;
+    }
+    const { runMembersCommand } = await import("./members");
+    const runtime = await getRuntime();
+    // Member listing is org-scoped via `requireCrmAccess`, identical
+    // auth shape to `dench crm`. Dev workspaces forward the encoded
+    // dev token so local --dev runs work the same way.
+    if (runtime.mode === "dev") {
+      await runMembersCommand({
+        convex: runtime.client,
+        args: subArgs,
+        sessionToken: encodeDevCrmSessionToken(runtime.workspaceArgs),
+      });
+      return;
+    }
+    const authedRuntime = requireAuthenticatedRuntime(
+      runtime,
+      "dench members",
+    );
+    await runMembersCommand({
+      convex: authedRuntime.client,
+      args: subArgs,
+      sessionToken: authedRuntime.sessionToken,
+    });
+    return;
+  }
+
   if (command === "fs") {
     await runFsCommand();
     return;
@@ -3267,6 +3611,11 @@ async function main() {
     return;
   }
 
+  if (command === "backend") {
+    await runBackendCommand();
+    return;
+  }
+
   const runtime = await getRuntime();
 
   if (command === "billing") {

package/host.ts

@@ -1,7 +1,24 @@
 export const PRODUCTION_HOST = "https://dench.dev";
 export const STAGING_HOST = "https://workspace-staging.dench.com";
+export const LOCAL_HOST = "http://localhost:3000";
 export const DEFAULT_HOST = PRODUCTION_HOST;
 
+/**
+ * Production-only fallbacks baked into the CLI binary so it does the
+ * right thing even when run with no config and no env vars (e.g. in a
+ * sandbox whose `buildSandboxEnvVars` map was assembled while the
+ * Vercel deployment was missing one of these keys).
+ *
+ * If any of these is wrong, EVERY install of @dench.com/cli is broken
+ * until republished — keep them in sync with whichever Convex
+ * deployment + Next.js host backs `https://www.dench.com`.
+ */
+export const PRODUCTION_API_URL = "https://www.dench.com";
+export const PRODUCTION_CONVEX_URL = "https://beaming-alligator-67.convex.cloud";
+export const PRODUCTION_GATEWAY_URL = "https://gateway.merseoriginals.com";
+
+export type BackendAlias = "production" | "prod" | "staging" | "local";
+
 function optionFromArgs(args: string[], name: string) {
   const index = args.indexOf(name);
   if (index === -1) return undefined;
@@ -13,7 +30,13 @@ function hasFlag(args: string[], name: string) {
 }
 
 export function normalizeHost(input: string) {
-  const withProtocol = /^https?:\/\//.test(input) ? input : `https://${input}`;
+  const trimmed = input.trim();
+  if (/^(localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\])(?::|$)/.test(trimmed)) {
+    return new URL(`http://${trimmed}`).origin;
+  }
+  const withProtocol = /^https?:\/\//.test(trimmed)
+    ? trimmed
+    : `https://${trimmed}`;
   const url = new URL(withProtocol);
   return url.origin;
 }
@@ -29,6 +52,39 @@ export function isLocalHost(input: string) {
   );
 }
 
+/**
+ * Resolve `local|staging|prod|production|<url>` -> a normalized host
+ * origin. Aliases let `dench backend set <alias>` (and `--backend
+ * <alias>`) accept the short forms most agents reach for first.
+ * Returns `undefined` for empty input and throws on values that
+ * neither match an alias nor parse as a URL.
+ */
+export function resolveBackendAlias(input: string): string {
+  const value = input.trim();
+  if (!value) {
+    throw new Error(
+      "Backend value is empty. Pass local, staging, prod, or a URL like https://dench.dev.",
+    );
+  }
+  const normalized = value.toLowerCase();
+  if (normalized === "prod" || normalized === "production") {
+    return PRODUCTION_HOST;
+  }
+  if (normalized === "staging" || normalized === "stage") {
+    return STAGING_HOST;
+  }
+  if (normalized === "local" || normalized === "localhost" || normalized === "dev") {
+    return LOCAL_HOST;
+  }
+  try {
+    return normalizeHost(value);
+  } catch (_error) {
+    throw new Error(
+      `Unrecognized backend "${value}". Use local, staging, prod, or a URL like https://dench.dev.`,
+    );
+  }
+}
+
 export function resolveHostFromArgs(
   args: string[],
   configHost?: string,
@@ -37,6 +93,9 @@ export function resolveHostFromArgs(
   if (hasFlag(args, "--prod")) return PRODUCTION_HOST;
   if (hasFlag(args, "--staging")) return STAGING_HOST;
 
+  const explicitBackend = optionFromArgs(args, "--backend");
+  if (explicitBackend) return resolveBackendAlias(explicitBackend);
+
   const explicit = optionFromArgs(args, "--host") ?? envHost;
   if (explicit) return normalizeHost(explicit);
   if (configHost) return normalizeHost(configHost);

package/lib/enrichment-gateway.ts

@@ -5,10 +5,13 @@ export type FetchLike = (
   init?: RequestInit,
 ) => Promise<Response>;
 
-export type EnrichmentGatewayEnv = Pick<
-  NodeJS.ProcessEnv,
-  "DENCH_API_KEY" | "DENCH_GATEWAY_URL" | "GATEWAY_URL" | "DENCH_HOST"
->;
+export type EnrichmentGatewayEnv = {
+  DENCH_API_KEY?: string;
+  DENCH_GATEWAY_URL?: string;
+  GATEWAY_URL?: string;
+  DENCH_HOST?: string;
+  [key: string]: string | undefined;
+};
 
 export class EnrichmentGatewayError extends Error {
   readonly status?: number;

package/lib/load-dev-env.mjs

@@ -1,27 +1,100 @@
-// When `./dench` (or `./dench.mjs`) runs through Node from inside the
-// dench.com source tree, Node does not auto-load workspace `.env` files
-// the way Bun does for `bun run`. That made every gateway-backed
-// subcommand (`dench apps`, `dench tool …`, the enrichment helpers,
-// etc.) silently default to production
-// (`https://gateway.merseoriginals.com`), because `cli/tools.ts`
-// resolves the gateway URL purely from `process.env`. A dev-issued
-// `DENCH_API_KEY` then 401'd against prod with `invalid_api_key`.
+// `./dench` and `./dench.mjs` ship as Node entry points. When Node runs
+// them from inside the dench.com source tree it does NOT auto-load
+// workspace `.env` files the way `bun run` does, so we have a one-shot
+// chance here to inject env vars (e.g. `GATEWAY_URL`,
+// `NEXT_PUBLIC_CONVEX_URL`) before `dench.ts` is imported.
 //
-// This helper detects the dench.com source tree (via the parent
-// `package.json` name) and loads `.env` then `.env.local` from the repo
-// root. Globally-installed and sandbox-baked CLI installs never see
-// that marker, so this is a no-op there. Existing `process.env` values
-// always win, so explicit shell exports (e.g.
-// `GATEWAY_URL=… ./dench …`) still take precedence over file values.
+// HISTORY: this helper used to ALWAYS load `.env` and `.env.local` when
+// the parent package was `ironclaw-cloud`. That fixed gateway-backed
+// subcommands (`dench apps`, `dench tool …`, the enrichment helpers)
+// that would otherwise silently 401 against production gateway with a
+// dev-issued `DENCH_API_KEY`. The side effect was severe: the auto-load
+// also injected `NEXT_PUBLIC_CONVEX_URL=…dev convex…` and friends, so
+// every Convex call from the CLI silently pointed at the dev
+// deployment, even when the user expected production.
+//
+// FIX: dev-env loading is now OPT-IN. The default is "do nothing" so
+// the CLI always defaults to production, no matter where it is invoked
+// from. Users opt into local/dev env vars one of three ways:
+//
+//   1. `--dev` flag in argv (existing flag — also flips the runtime to
+//      dev workspace mode).
+//   2. `--use-dev-env` flag in argv (load `.env` files without
+//      switching to dev workspace mode — useful when you want
+//      `GATEWAY_URL=http://0.0.0.0:8787` baked in but still talk to a
+//      stored session).
+//   3. `DENCH_USE_DEV_ENV=1` env var (same effect as `--use-dev-env`,
+//      handy for `direnv` setups).
+//   4. `defaultBackend: "http://localhost:…"` (or any local URL) in
+//      `~/.dench/config.json` — set via `dench backend set local`. If
+//      the user has explicitly pointed the CLI at localhost they almost
+//      always also want the dev gateway URL.
+//
+// Existing `process.env` values always win, so explicit shell exports
+// (e.g. `GATEWAY_URL=… ./dench …`) keep working even with auto-load
+// disabled.
 
 import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const WORKSPACE_PACKAGE_NAME = "ironclaw-cloud";
 const ENV_FILES = [".env", ".env.local"];
+const CONFIG_PATH = join(homedir(), ".dench", "config.json");
+
+const TRUE_ENV_VALUES = new Set(["1", "true", "yes", "on"]);
+
+function envFlagEnabled(value) {
+  if (!value) return false;
+  return TRUE_ENV_VALUES.has(value.trim().toLowerCase());
+}
 
-export function loadDevEnv(callerUrl) {
+function argvOptIn(argv) {
+  if (!Array.isArray(argv)) return false;
+  return argv.includes("--dev") || argv.includes("--use-dev-env");
+}
+
+function configOptIn() {
+  try {
+    if (!existsSync(CONFIG_PATH)) return false;
+    const raw = readFileSync(CONFIG_PATH, "utf8");
+    const config = JSON.parse(raw);
+    const backend = config?.defaultBackend;
+    if (typeof backend !== "string" || !backend.trim()) return false;
+    return isLocalUrl(backend.trim());
+  } catch {
+    return false;
+  }
+}
+
+function isLocalUrl(value) {
+  try {
+    const url = new URL(/^https?:\/\//.test(value) ? value : `https://${value}`);
+    const host = url.hostname;
+    return (
+      host === "localhost" ||
+      host === "127.0.0.1" ||
+      host === "0.0.0.0" ||
+      host === "::1" ||
+      host.endsWith(".localhost")
+    );
+  } catch {
+    return false;
+  }
+}
+
+export function shouldLoadDevEnv({
+  argv = process.argv.slice(2),
+  env = process.env,
+} = {}) {
+  if (envFlagEnabled(env.DENCH_USE_DEV_ENV)) return "env";
+  if (argvOptIn(argv)) return "argv";
+  if (configOptIn()) return "config";
+  return false;
+}
+
+export function loadDevEnv(callerUrl, options = {}) {
   try {
     const here = dirname(fileURLToPath(callerUrl));
     const repoRoot = dirname(here);
@@ -30,6 +103,8 @@ export function loadDevEnv(callerUrl) {
     const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
     if (pkg?.name !== WORKSPACE_PACKAGE_NAME) return;
 
+    if (!shouldLoadDevEnv(options)) return;
+
     for (const filename of ENV_FILES) {
       const path = join(repoRoot, filename);
       if (!existsSync(path)) continue;

package/lib/load-dev-env.test.mjs

@@ -0,0 +1,44 @@
+import { describe, expect, it } from "bun:test";
+import { shouldLoadDevEnv } from "./load-dev-env.mjs";
+
+describe("shouldLoadDevEnv", () => {
+  it("returns false on a fresh install with no opt-in", () => {
+    expect(shouldLoadDevEnv({ argv: [], env: {} })).toBe(false);
+  });
+
+  it("opts in when --dev is in argv", () => {
+    expect(shouldLoadDevEnv({ argv: ["status", "--dev"], env: {} })).toBe(
+      "argv",
+    );
+  });
+
+  it("opts in when --use-dev-env is in argv", () => {
+    expect(
+      shouldLoadDevEnv({ argv: ["apps", "--use-dev-env"], env: {} }),
+    ).toBe("argv");
+  });
+
+  it("opts in when DENCH_USE_DEV_ENV is set to a truthy value", () => {
+    expect(shouldLoadDevEnv({ argv: [], env: { DENCH_USE_DEV_ENV: "1" } })).toBe(
+      "env",
+    );
+    expect(
+      shouldLoadDevEnv({ argv: [], env: { DENCH_USE_DEV_ENV: "true" } }),
+    ).toBe("env");
+    expect(
+      shouldLoadDevEnv({ argv: [], env: { DENCH_USE_DEV_ENV: "yes" } }),
+    ).toBe("env");
+  });
+
+  it("ignores DENCH_USE_DEV_ENV when set to a falsy/empty value", () => {
+    expect(shouldLoadDevEnv({ argv: [], env: { DENCH_USE_DEV_ENV: "" } })).toBe(
+      false,
+    );
+    expect(shouldLoadDevEnv({ argv: [], env: { DENCH_USE_DEV_ENV: "0" } })).toBe(
+      false,
+    );
+    expect(
+      shouldLoadDevEnv({ argv: [], env: { DENCH_USE_DEV_ENV: "false" } }),
+    ).toBe(false);
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dench.com/cli",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "description": "Dench agent workspace CLI.",
   "type": "module",
   "bin": {

package/tools.ts

@@ -36,6 +36,10 @@
  * working.
  */
 
+import {
+  PRODUCTION_API_URL,
+  PRODUCTION_GATEWAY_URL,
+} from "./host";
 import {
   CliArgError,
   getFlag,
@@ -380,7 +384,7 @@ function resolveGatewayBaseUrl(): string {
   if (host && /localhost|127\.0\.0\.1/.test(host)) {
     return "http://localhost:8787";
   }
-  return "https://gateway.merseoriginals.com";
+  return PRODUCTION_GATEWAY_URL;
 }
 
 /**
@@ -403,7 +407,7 @@ function resolveAppPublicOrigin(): string {
     const trimmed = candidate?.trim();
     if (trimmed) return trimmed.replace(/\/+$/, "");
   }
-  return "https://dench.com";
+  return PRODUCTION_API_URL;
 }
 
 function requireApiKey(): string {