@dench.com/cli 2.0.0 → 2.0.1

package/crm.ts

@@ -26,7 +26,7 @@
  *   crm docs      list / create / link
  *   crm actions   list / run / runs
  */
-import { ConvexHttpClient } from "convex/browser";
+import type { ConvexHttpClient } from "convex/browser";
 import { makeFunctionReference } from "convex/server";
 import {
   assertNoUnknownFlags as assertNoUnknownFlagsRaw,
@@ -40,18 +40,19 @@ import {
 import {
   autoDetectInputField,
   detectEnrichmentCategory,
-  extractEnrichmentValue,
-  findEnrichmentColumn,
-  getRequiredFieldsForApolloPath,
   type EnrichmentCategory,
   type EnrichmentColumnDef,
+  extractEnrichmentValue,
   type FieldCandidate,
+  findEnrichmentColumn,
+  getRequiredFieldsForApolloPath,
 } from "./lib/crm-enrichment";
 import {
   aviatoEnrichCompany,
   aviatoEnrichPerson,
-  enrichCompany,
   EnrichmentGatewayError,
+  type EnrichmentGatewayOptions,
+  enrichCompany,
   enrichPersonByIdentifier,
 } from "./lib/enrichment-gateway";
 
@@ -82,6 +83,7 @@ type CrmCliContext = {
    * organization context.
    */
   sessionToken?: string;
+  enrichmentGateway?: Pick<EnrichmentGatewayOptions, "apiKey" | "baseUrl">;
 };
 
 // Adapt the shared helpers to throw CrmCliError so existing call sites
@@ -310,12 +312,14 @@ function out(ctx: CrmCliContext, value: unknown): void {
   console.log(JSON.stringify(value, null, 2));
 }
 
-function getFieldEnrichmentFlag(args: string[]): {
-  category: EnrichmentCategory;
-  key: string;
-  apolloPath: string;
-  inputFieldName: string;
-} | undefined {
+function getFieldEnrichmentFlag(args: string[]):
+  | {
+      category: EnrichmentCategory;
+      key: string;
+      apolloPath: string;
+      inputFieldName: string;
+    }
+  | undefined {
   const category = parseCategoryFlag(getFlag(args, "--enrichment-category"));
   const key = getFlag(args, "--enrichment-key");
   const apolloPath = getFlag(args, "--apollo-path");
@@ -431,6 +435,7 @@ export async function runCrmCommand(opts: {
   convex: ConvexHttpClient;
   args: string[];
   sessionToken?: string;
+  enrichmentGateway?: Pick<EnrichmentGatewayOptions, "apiKey" | "baseUrl">;
 }): Promise<void> {
   const args = [...opts.args];
   const jsonOutput = hasFlag(args, "--json");
@@ -439,6 +444,7 @@ export async function runCrmCommand(opts: {
     args,
     jsonOutput,
     sessionToken: opts.sessionToken,
+    enrichmentGateway: opts.enrichmentGateway,
   };
   const subcommand = args.shift();
   if (!subcommand || subcommand === "help" || subcommand === "--help") {
@@ -1531,13 +1537,18 @@ type ObjectEnrichmentArgs = Omit<CellEnrichmentArgs, "entryId"> & {
   limit?: number;
 };
 
-function parseCategoryFlag(value: string | undefined): EnrichmentCategory | undefined {
+function parseCategoryFlag(
+  value: string | undefined,
+): EnrichmentCategory | undefined {
   if (value === undefined) return undefined;
   if (value === "people" || value === "company") return value;
   throw new CrmCliError("--category must be people or company");
 }
 
-function parsePositiveInt(flag: string, value: string | undefined): number | undefined {
+function parsePositiveInt(
+  flag: string,
+  value: string | undefined,
+): number | undefined {
   if (value === undefined) return undefined;
   const parsed = Number(value);
   if (!Number.isInteger(parsed) || parsed < 1) {
@@ -1556,7 +1567,9 @@ function asFields(value: unknown): CrmFieldForEnrichment[] {
     .filter((field): field is CrmFieldForEnrichment => {
       if (!field || typeof field !== "object") return false;
       const candidate = field as Record<string, unknown>;
-      return typeof candidate.name === "string" && typeof candidate.type === "string";
+      return (
+        typeof candidate.name === "string" && typeof candidate.type === "string"
+      );
     })
     .map((field) => ({
       id: typeof field.id === "string" ? field.id : undefined,
@@ -1601,7 +1614,9 @@ function asEntry(value: unknown): CrmEntryForEnrichment | null {
 
 function asEntries(value: unknown): CrmEntryForEnrichment[] {
   if (!Array.isArray(value)) return [];
-  return value.map(asEntry).filter((entry): entry is CrmEntryForEnrichment => !!entry);
+  return value
+    .map(asEntry)
+    .filter((entry): entry is CrmEntryForEnrichment => !!entry);
 }
 
 function resolveEnrichmentColumn(args: {
@@ -1668,7 +1683,8 @@ async function resolveEnrichmentTarget(
     apolloPath: args.apolloPath ?? outputField.enrichment?.apolloPath,
   });
 
-  const inputFieldName = args.inputFieldName ?? outputField.enrichment?.inputFieldName;
+  const inputFieldName =
+    args.inputFieldName ?? outputField.enrichment?.inputFieldName;
   const inputField = inputFieldName
     ? fields.find((field) => field.name === inputFieldName)
     : autoDetectInputField(category, fields);
@@ -1693,6 +1709,7 @@ async function callEnrichmentGatewayForEntry(args: {
   entry: CrmEntryForEnrichment;
   /** Explicit provider override. Defaults: people=fullenrich, company=aviato. */
   provider?: string;
+  gateway?: Pick<EnrichmentGatewayOptions, "apiKey" | "baseUrl">;
 }): Promise<Record<string, unknown>> {
   const input = args.entry.fields[args.target.inputField.name];
   if (!hasCellValue(input)) {
@@ -1702,7 +1719,8 @@ async function callEnrichmentGatewayForEntry(args: {
   }
   const inputValue = String(input);
   const isCompany = args.target.category === "company";
-  const resolvedProvider = args.provider ?? (isCompany ? "aviato" : "fullenrich");
+  const resolvedProvider =
+    args.provider ?? (isCompany ? "aviato" : "fullenrich");
 
   if (resolvedProvider === "aviato") {
     // Guard: Aviato does not return phone or email.
@@ -1718,25 +1736,37 @@ async function callEnrichmentGatewayForEntry(args: {
       const isLinkedin = /linkedin\.com/i.test(inputValue);
       return aviatoEnrichCompany(
         isLinkedin ? { linkedinUrl: inputValue } : { website: inputValue },
+        args.gateway,
       );
     } else {
       // For people, inputValue may be a LinkedIn URL, email, or LinkedIn ID
       const isLinkedin = /linkedin\.com/i.test(inputValue);
       const isEmail = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(inputValue);
-      if (isLinkedin) return aviatoEnrichPerson({ linkedinUrl: inputValue });
-      if (isEmail) return aviatoEnrichPerson({ email: inputValue });
-      return aviatoEnrichPerson({ linkedinID: inputValue });
+      if (isLinkedin) {
+        return aviatoEnrichPerson({ linkedinUrl: inputValue }, args.gateway);
+      }
+      if (isEmail) {
+        return aviatoEnrichPerson({ email: inputValue }, args.gateway);
+      }
+      return aviatoEnrichPerson({ linkedinID: inputValue }, args.gateway);
     }
   }
 
   // fullenrich path (default for people, explicit override for companies)
   if (isCompany) {
-    return enrichCompany({
-      domain: inputValue,
-      requiredFields: args.target.requiredFields,
-    });
+    return enrichCompany(
+      {
+        domain: inputValue,
+        requiredFields: args.target.requiredFields,
+      },
+      args.gateway,
+    );
   }
-  return enrichPersonByIdentifier(inputValue, args.target.requiredFields);
+  return enrichPersonByIdentifier(
+    inputValue,
+    args.target.requiredFields,
+    args.gateway,
+  );
 }
 
 async function enrichOneEntry(
@@ -1751,6 +1781,7 @@ async function enrichOneEntry(
       target: args.target,
       entry: args.entry,
       provider: args.provider,
+      gateway: ctx.enrichmentGateway,
     });
     const value = extractEnrichmentValue(payload, args.target.column);
     if (value === null) {
@@ -1779,7 +1810,10 @@ async function enrichOneEntry(
       ...writeResult,
     };
   } catch (error) {
-    if (error instanceof EnrichmentGatewayError || error instanceof CrmCliError) {
+    if (
+      error instanceof EnrichmentGatewayError ||
+      error instanceof CrmCliError
+    ) {
       return {
         entryId: args.entry.id,
         ok: false,

package/dench.ts

@@ -966,11 +966,12 @@ function backendSnapshot(config: ConfigFile) {
     : null;
   const envHost = process.env.DENCH_HOST?.trim() || null;
   const argBackend =
-    option("--backend") ?? (hasFlag("--prod")
+    option("--backend") ??
+    (hasFlag("--prod")
       ? "production"
       : hasFlag("--staging")
         ? "staging"
-        : option("--host") ?? null);
+        : (option("--host") ?? null));
 
   let source: "flag" | "env" | "config" | "default";
   if (argBackend) source = "flag";
@@ -1078,7 +1079,9 @@ async function backendSet() {
       "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.");
+  print(
+    "Future `dench` commands without --prod/--staging/--host will target this backend.",
+  );
 }
 
 async function backendClear() {
@@ -1706,8 +1709,7 @@ async function signinViaBrowser(input: {
       agentName: input.agentName,
       agentKind: input.agentKind,
       intent: input.intent,
-      proposedOrganizationName:
-        input.proposedOrganizationName ?? undefined,
+      proposedOrganizationName: input.proposedOrganizationName ?? undefined,
       requestedOrganizationSelector: input.orgSelector ?? undefined,
       userAgent: "@dench.com/cli",
     },
@@ -1841,7 +1843,8 @@ async function signinViaOtp(input: {
   // resolvable (single admin org or create_workspace intent) and the
   // server hands us a session, OR we get an auth token + list and
   // need a third call.
-  const code = option("--otp-code")?.trim() || (await promptLine("Paste OTP: "));
+  const code =
+    option("--otp-code")?.trim() || (await promptLine("Paste OTP: "));
   if (!/^\d{6}$/.test(code)) {
     throw new CliError("OTP code must be exactly 6 digits.", {
       code: "invalid_otp_code",
@@ -1857,8 +1860,7 @@ async function signinViaOtp(input: {
       agentKind: input.agentKind,
       sessionTokenHash: input.sessionTokenHash,
       intent: input.intent,
-      proposedOrganizationName:
-        input.proposedOrganizationName ?? undefined,
+      proposedOrganizationName: input.proposedOrganizationName ?? undefined,
       organizationSelector: input.orgSelector ?? undefined,
       userAgent: "@dench.com/cli",
     }),
@@ -1878,8 +1880,15 @@ async function signinViaOtp(input: {
 
   // Branch A: server minted the session in one shot.
   if (result.kind === "completed") {
-    assertOtpCompletedOrgMatchesSelector(result.organization, input.orgSelector);
-    await finalizeOtpSession(input, result.organization, result.sessionExpiresAt);
+    assertOtpCompletedOrgMatchesSelector(
+      result.organization,
+      input.orgSelector,
+    );
+    await finalizeOtpSession(
+      input,
+      result.organization,
+      result.sessionExpiresAt,
+    );
     return;
   }
 
@@ -2020,7 +2029,11 @@ async function resolveOrgChoiceForOtp(input: {
 
   const answer = await promptLine("Pick a number: ");
   const choice = Number(answer);
-  if (!Number.isFinite(choice) || choice < 1 || choice > input.organizations.length + 1) {
+  if (
+    !Number.isFinite(choice) ||
+    choice < 1 ||
+    choice > input.organizations.length + 1
+  ) {
     throw new CliError(`Invalid choice: ${answer}`, {
       code: "invalid_org_choice",
     });
@@ -2234,9 +2247,7 @@ async function denchUpgrade(runtime: Runtime) {
   if (updatedInPlace) {
     const message = `Upgraded to Dench ${tierFlag === "pro" ? "Pro" : "Max"} in place — no Stripe Checkout needed.`;
     print(
-      json
-        ? { ok: true, updated: true, tier: tierFlag, message }
-        : message,
+      json ? { ok: true, updated: true, tier: tierFlag, message } : message,
     );
     return;
   }
@@ -2487,6 +2498,103 @@ function requireAuthenticatedRuntime(
   throw loginRequiredError(command);
 }
 
+type GatewayCommandAuth = {
+  bearerToken: string;
+  gatewayBaseUrl?: string;
+};
+
+function gatewayBaseUrlForCli(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim().replace(/\/+$/, "");
+  if (!trimmed) return undefined;
+  // The desktop endpoint returns a `/v1` base; CLI gateway modules append
+  // `/v1/...` paths themselves, so normalize to the root origin here.
+  return trimmed.replace(/\/v1$/, "");
+}
+
+async function parseJsonResponseBody(response: Response): Promise<JsonRecord> {
+  const text = await response.text().catch(() => "");
+  if (!text.trim()) return {};
+  try {
+    const parsed = JSON.parse(text);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? (parsed as JsonRecord)
+      : {};
+  } catch {
+    return { error: text };
+  }
+}
+
+function gatewayAuthError(
+  command: string,
+  response: Response,
+  body: JsonRecord,
+) {
+  const code =
+    typeof body.error === "string" && body.error.trim()
+      ? body.error.trim()
+      : `gateway_key_${response.status}`;
+  if (response.status === 403 && code === "no_active_subscription") {
+    return new CliError(`${command} requires a paid Dench workspace`, {
+      code: "paid_workspace_required",
+      nextActions: [
+        "Run dench upgrade --tier pro or dench upgrade --tier max, then retry.",
+      ],
+    });
+  }
+  if (response.status === 401) {
+    return loginRequiredError(command);
+  }
+  return new CliError(`${command} could not get a gateway key (${code})`, {
+    code,
+    status: response.status,
+    nextActions: [
+      "Confirm this agent is signed in to the intended workspace.",
+      "If the workspace is paid, retry after a minute in case gateway key provisioning is still finishing.",
+    ],
+  });
+}
+
+async function resolveGatewayCommandAuth(
+  runtime: Runtime,
+  command: string,
+): Promise<GatewayCommandAuth> {
+  if (runtime.mode === "apiKey") {
+    return { bearerToken: runtime.sessionToken };
+  }
+
+  if (runtime.mode === "session") {
+    const response = await fetch(
+      `${runtime.host.replace(/\/+$/, "")}/api/desktop/organizations/gateway-key`,
+      {
+        headers: {
+          accept: "application/json",
+          authorization: `Bearer ${runtime.sessionToken}`,
+        },
+      },
+    );
+    const body = await parseJsonResponseBody(response);
+    if (!response.ok) {
+      throw gatewayAuthError(command, response, body);
+    }
+    const gatewayKey =
+      typeof body.gatewayKey === "string" ? body.gatewayKey.trim() : "";
+    if (!gatewayKey) {
+      throw new CliError(`${command} could not get a gateway key`, {
+        code: "missing_gateway_key",
+      });
+    }
+    return {
+      bearerToken: gatewayKey,
+      gatewayBaseUrl: gatewayBaseUrlForCli(body.gatewayBaseUrl),
+    };
+  }
+
+  const envApiKey = process.env.DENCH_API_KEY?.trim();
+  if (envApiKey) return { bearerToken: envApiKey };
+  throw loginRequiredError(command);
+}
+
 function encodeDevCrmSessionToken(args: {
   workspaceSlug: string;
   devKey: string;
@@ -2609,12 +2717,24 @@ function nextContextCommands() {
   ];
 }
 
-async function connectedAppsContext(_runtime: Runtime) {
-  // Reach the Dench gateway directly with DENCH_API_KEY (mirrors the
-  // denchclaw pattern). This works for every Runtime mode — session,
-  // apiKey, dev — because the gateway only cares about the bearer key,
-  // not which Convex session is calling.
-  return fetchConnectedAppsSummary();
+async function connectedAppsContext(runtime: Runtime) {
+  try {
+    const gatewayAuth = await resolveGatewayCommandAuth(
+      runtime,
+      "dench context",
+    );
+    return fetchConnectedAppsSummary({
+      bearerToken: gatewayAuth.bearerToken,
+      gatewayBaseUrl: gatewayAuth.gatewayBaseUrl,
+    });
+  } catch (error) {
+    return {
+      available: false,
+      reason: errorMessage(error),
+      count: 0,
+      connections: [],
+    };
+  }
 }
 
 async function buildContext(runtime: Runtime) {
@@ -3024,26 +3144,12 @@ function normalizeFilesPath(input: string): string {
   return cleaned;
 }
 
-function filesApiKey(runtime: Runtime): string | undefined {
-  if (runtime.mode === "apiKey") return runtime.sessionToken;
-  return process.env.DENCH_API_KEY?.trim() || undefined;
-}
-
-function requireFilesApiKey(runtime: Runtime, command: string): string {
-  const apiKey = filesApiKey(runtime);
-  if (!apiKey) {
-    throw new CliError(
-      `${command} needs DENCH_API_KEY (or a sandbox-baked api-key session). It bypasses the user-session auth path.`,
-      {
-        code: "files_api_key_required",
-        nextActions: [
-          "Run inside a Dench sandbox where DENCH_API_KEY is baked in.",
-          "Or export DENCH_API_KEY=<key> first (see dench signin output).",
-        ],
-      },
-    );
-  }
-  return apiKey;
+async function requireFilesApiKey(
+  runtime: Runtime,
+  command: string,
+): Promise<string> {
+  const auth = await resolveGatewayCommandAuth(runtime, command);
+  return auth.bearerToken;
 }
 
 type FileTreeRow = {
@@ -3143,7 +3249,7 @@ async function uploadConvexFileBytes(
 
 async function runFilesLs() {
   const runtime = await getRuntime();
-  const apiKey = requireFilesApiKey(runtime, "dench files ls");
+  const apiKey = await requireFilesApiKey(runtime, "dench files ls");
   const target = normalizeFilesPath(positional(2) ?? "/");
   const recursive = hasFlag("--recursive") || hasFlag("-r");
   const rows = recursive
@@ -3180,7 +3286,7 @@ async function runFilesLs() {
 
 async function runFilesMv() {
   const runtime = await getRuntime();
-  const apiKey = requireFilesApiKey(runtime, "dench files mv");
+  const apiKey = await requireFilesApiKey(runtime, "dench files mv");
   const fromRaw = positional(2);
   const toRaw = positional(3);
   if (!fromRaw || !toRaw) {
@@ -3252,7 +3358,7 @@ async function runFilesMv() {
 
 async function runFilesRm() {
   const runtime = await getRuntime();
-  const apiKey = requireFilesApiKey(runtime, "dench files rm");
+  const apiKey = await requireFilesApiKey(runtime, "dench files rm");
   const targetRaw = positional(2);
   if (!targetRaw) {
     throw new CliError("Usage: dench files rm <path> [--recursive]", {
@@ -3439,7 +3545,7 @@ async function* walkLocalFiles(
 
 async function runStage() {
   const runtime = await getRuntime();
-  const apiKey = requireFilesApiKey(runtime, "dench stage");
+  const apiKey = await requireFilesApiKey(runtime, "dench stage");
   const localRaw = positional(1);
   const destRaw = positional(2);
   if (!localRaw) {
@@ -3694,15 +3800,13 @@ async function main() {
   // clean redirect to the new unified surface so old `npx` caches and
   // pre-existing agent prompts get a one-line nudge instead of an
   // opaque "Unknown command" error.
-  if (
-    isDeprecatedAuthCommand
-  ) {
+  if (isDeprecatedAuthCommand) {
     throw new CliError(
       `\`dench ${command}\` was removed in @dench.com/cli v2. Run \`dench signin\` instead.`,
       {
         code: "deprecated_command",
         nextActions: [
-          'Run `dench signin` to connect this agent to an existing workspace.',
+          "Run `dench signin` to connect this agent to an existing workspace.",
           'Run `dench signin --new-workspace --org-name "<name>"` to create a free CRM-only workspace.',
           "Upgrade the CLI globally with `npm install -g @dench.com/cli@latest`.",
         ],
@@ -3746,10 +3850,7 @@ async function main() {
     return;
   }
 
-  if (
-    command === "backend" &&
-    (subcommand === "help" || hasFlag("--help"))
-  ) {
+  if (command === "backend" && (subcommand === "help" || hasFlag("--help"))) {
     backendHelp();
     return;
   }
@@ -3776,18 +3877,38 @@ async function main() {
     // `requireCrmAccess` (convex/lib/crm/access.ts) dispatches on the
     // bearer prefix and resolves the org for both.
     if (runtime.mode === "dev") {
+      const gatewayAuth =
+        subArgs[0] === "enrich"
+          ? await resolveGatewayCommandAuth(runtime, "dench crm enrich")
+          : undefined;
       await runCrmCommand({
         convex: runtime.client,
         args: subArgs,
         sessionToken: encodeDevCrmSessionToken(runtime.workspaceArgs),
+        enrichmentGateway: gatewayAuth
+          ? {
+              apiKey: gatewayAuth.bearerToken,
+              baseUrl: gatewayAuth.gatewayBaseUrl,
+            }
+          : undefined,
       });
       return;
     }
     const authedRuntime = requireAuthenticatedRuntime(runtime, "dench crm");
+    const gatewayAuth =
+      subArgs[0] === "enrich"
+        ? await resolveGatewayCommandAuth(authedRuntime, "dench crm enrich")
+        : undefined;
     await runCrmCommand({
       convex: authedRuntime.client,
       args: subArgs,
       sessionToken: authedRuntime.sessionToken,
+      enrichmentGateway: gatewayAuth
+        ? {
+            apiKey: gatewayAuth.bearerToken,
+            baseUrl: gatewayAuth.gatewayBaseUrl,
+          }
+        : undefined,
     });
     return;
   }
@@ -3820,10 +3941,7 @@ async function main() {
       });
       return;
     }
-    const authedRuntime = requireAuthenticatedRuntime(
-      runtime,
-      "dench members",
-    );
+    const authedRuntime = requireAuthenticatedRuntime(runtime, "dench members");
     await runMembersCommand({
       convex: authedRuntime.client,
       args: subArgs,
@@ -3848,44 +3966,76 @@ async function main() {
   }
 
   if (command === "search") {
-    // `dench search` talks straight to the gateway over HTTP using
-    // DENCH_API_KEY; it deliberately bypasses requireSessionRuntime so
-    // it works in any sandbox / CI environment that has the key.
     const subArgs = args.slice(args.indexOf("search") + 1);
     const filteredSubArgs = subArgs.filter((a) => a !== "--json");
     const { runSearchCommand } = await import("./search");
-    await runSearchCommand({ args: filteredSubArgs, jsonOutput: json });
+    const sub = filteredSubArgs[0];
+    if (!sub || sub === "help" || sub === "--help" || sub === "-h") {
+      await runSearchCommand({ args: filteredSubArgs, jsonOutput: json });
+      return;
+    }
+    const runtime = await getRuntime();
+    const gatewayAuth = await resolveGatewayCommandAuth(
+      runtime,
+      "dench search",
+    );
+    await runSearchCommand({
+      args: filteredSubArgs,
+      jsonOutput: json,
+      bearerToken: gatewayAuth.bearerToken,
+      gatewayBaseUrl: gatewayAuth.gatewayBaseUrl,
+    });
     return;
   }
 
   if (command === "image") {
-    // `dench image generate|edit` mirrors `dench search`: straight HTTP
-    // to the gateway with DENCH_API_KEY, no Convex session required.
-    // The gateway writes the bytes to Convex Storage on success; we
-    // also drop them on local disk so the next bash command sees them.
     const subArgs = args.slice(args.indexOf("image") + 1);
     const filteredSubArgs = subArgs.filter((a) => a !== "--json");
     const { runImageCommand } = await import("./image");
-    await runImageCommand({ args: filteredSubArgs, jsonOutput: json });
+    const sub = filteredSubArgs[0];
+    if (!sub || sub === "help" || sub === "--help" || sub === "-h") {
+      await runImageCommand({ args: filteredSubArgs, jsonOutput: json });
+      return;
+    }
+    const runtime = await getRuntime();
+    const gatewayAuth = await resolveGatewayCommandAuth(runtime, "dench image");
+    await runImageCommand({
+      args: filteredSubArgs,
+      jsonOutput: json,
+      bearerToken: gatewayAuth.bearerToken,
+      gatewayBaseUrl: gatewayAuth.gatewayBaseUrl,
+    });
     return;
   }
 
   if (command === "apps") {
-    // `dench apps` is an alias for `dench tool status`. Both speak
-    // straight HTTP to the Dench Cloud Gateway with DENCH_API_KEY —
-    // mirrors the denchclaw pattern. No Convex session involved.
-    await runToolCommand({ args: ["status"], jsonOutput: json });
+    const runtime = await getRuntime();
+    const gatewayAuth = await resolveGatewayCommandAuth(runtime, "dench apps");
+    await runToolCommand({
+      args: ["status"],
+      jsonOutput: json,
+      bearerToken: gatewayAuth.bearerToken,
+      gatewayBaseUrl: gatewayAuth.gatewayBaseUrl,
+    });
     return;
   }
 
   if (command === "tool") {
-    // `dench tool {status,connect,search,run,disconnect}` is the model-facing
-    // composio surface and only needs DENCH_API_KEY (Bearer) on the
-    // gateway. Bypasses requireSessionRuntime entirely so it works in
-    // every sandbox / API-key context.
     const subArgs = stripRuntimeFlags(args.slice(args.indexOf("tool") + 1));
     const filteredSubArgs = subArgs.filter((a) => a !== "--json");
-    await runToolCommand({ args: filteredSubArgs, jsonOutput: json });
+    const sub = filteredSubArgs[0];
+    if (!sub || sub === "help" || sub === "--help" || sub === "-h") {
+      await runToolCommand({ args: filteredSubArgs, jsonOutput: json });
+      return;
+    }
+    const runtime = await getRuntime();
+    const gatewayAuth = await resolveGatewayCommandAuth(runtime, "dench tool");
+    await runToolCommand({
+      args: filteredSubArgs,
+      jsonOutput: json,
+      bearerToken: gatewayAuth.bearerToken,
+      gatewayBaseUrl: gatewayAuth.gatewayBaseUrl,
+    });
     return;
   }
 

package/image.ts

@@ -3,9 +3,9 @@
  * the Dench Cloud Gateway.
  *
  * Mirrors `dench search`: bypasses Convex entirely and talks straight HTTP
- * to the gateway, authenticating with the `DENCH_API_KEY` baked into every
- * sandbox at create time. Works anywhere that env var is exported (sandbox,
- * CI, local dev).
+ * to the gateway, authenticating with either `DENCH_API_KEY` or a
+ * paid-workspace gateway key resolved from the active agent session by the
+ * top-level dispatcher.
  *
  * Persistence model: the gateway already writes the bytes to Convex Storage
  * + the org's fileTree on success (so the workspace UI sees the file
@@ -27,38 +27,33 @@
 
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, resolve } from "node:path";
-import {
-  CliArgError,
-  getFlag,
-  hasFlag,
-  shift as shiftRaw,
-} from "./lib/cli-args";
+import { getFlag, hasFlag } from "./lib/cli-args";
 
 type ImageCliContext = {
   args: string[];
   jsonOutput: boolean;
+  bearerToken?: string;
+  gatewayBaseUrl?: string;
 };
 
 class ImageCliError extends Error {}
 
-function shift(args: string[], expected: string): string {
-  try {
-    return shiftRaw(args, expected);
-  } catch (error) {
-    if (error instanceof CliArgError) {
-      throw new ImageCliError(error.message);
-    }
-    throw error;
-  }
-}
-
 const ALLOWED_QUALITIES = new Set(["auto", "low", "medium", "high"]);
 const ALLOWED_FORMATS = new Set(["png", "jpeg", "webp"]);
 
-function resolveGatewayBaseUrl(): string {
+function normalizeGatewayBaseUrl(value: string): string {
+  return value.replace(/\/+$/, "").replace(/\/v1$/, "");
+}
+
+function resolveGatewayBaseUrl(
+  ctx?: Pick<ImageCliContext, "gatewayBaseUrl">,
+): string {
+  if (ctx?.gatewayBaseUrl?.trim()) {
+    return normalizeGatewayBaseUrl(ctx.gatewayBaseUrl.trim());
+  }
   const explicit =
     process.env.DENCH_GATEWAY_URL?.trim() || process.env.GATEWAY_URL?.trim();
-  if (explicit) return explicit.replace(/\/+$/, "");
+  if (explicit) return normalizeGatewayBaseUrl(explicit);
   const host = process.env.DENCH_HOST?.trim();
   if (host && /localhost|127\.0\.0\.1/.test(host)) {
     return "http://localhost:8787";
@@ -66,16 +61,17 @@ function resolveGatewayBaseUrl(): string {
   return "https://gateway.merseoriginals.com";
 }
 
-function requireApiKey(): string {
-  const apiKey = process.env.DENCH_API_KEY?.trim();
-  if (!apiKey) {
+function requireBearerToken(
+  ctx?: Pick<ImageCliContext, "bearerToken">,
+): string {
+  const bearerToken =
+    ctx?.bearerToken?.trim() || process.env.DENCH_API_KEY?.trim();
+  if (!bearerToken) {
     throw new ImageCliError(
-      "DENCH_API_KEY is not set. Inside a Dench sandbox it is baked into " +
-        "the env automatically; outside, export it manually or run " +
-        "`dench login` first.",
+      "No Dench gateway credential found. Set DENCH_API_KEY or run `dench signin` for a paid workspace.",
     );
   }
-  return apiKey;
+  return bearerToken;
 }
 
 function resolveDefaultVolumeRoot(): string {
@@ -125,16 +121,17 @@ type GatewayImageResponse = {
 };
 
 async function callGateway(
+  ctx: ImageCliContext,
   path: "/v1/images/generations" | "/v1/images/edits",
   body: Record<string, unknown>,
 ): Promise<GatewayImageResponse> {
-  const apiKey = requireApiKey();
-  const baseUrl = resolveGatewayBaseUrl();
+  const bearerToken = requireBearerToken(ctx);
+  const baseUrl = resolveGatewayBaseUrl(ctx);
   const response = await fetch(`${baseUrl}${path}`, {
     method: "POST",
     headers: {
       "content-type": "application/json",
-      Authorization: `Bearer ${apiKey}`,
+      Authorization: `Bearer ${bearerToken}`,
     },
     body: JSON.stringify(body),
   });
@@ -246,7 +243,16 @@ function parseCommonOpts(args: string[]): CommonImageOpts {
       `Invalid --moderation: ${moderation}. Allowed: auto, low`,
     );
   }
-  return { size, quality, format, savePath, output, noWrite, background, moderation };
+  return {
+    size,
+    quality,
+    format,
+    savePath,
+    output,
+    noWrite,
+    background,
+    moderation,
+  };
 }
 
 function buildGenerationBody(
@@ -283,7 +289,7 @@ async function runGenerateSubcommand(ctx: ImageCliContext): Promise<void> {
     );
   }
   const body = buildGenerationBody(prompt, opts);
-  const result = await callGateway("/v1/images/generations", body);
+  const result = await callGateway(ctx, "/v1/images/generations", body);
   if (!result.b64_json) {
     throw new ImageCliError("Gateway response did not include image bytes.");
   }
@@ -341,14 +347,16 @@ async function runEditSubcommand(ctx: ImageCliContext): Promise<void> {
       `Too many --input paths (${inputs.length}); the gateway accepts at most 8.`,
     );
   }
-  const inputBase64 = await Promise.all(inputs.map((p) => readBase64FromPath(p)));
+  const inputBase64 = await Promise.all(
+    inputs.map((p) => readBase64FromPath(p)),
+  );
   const maskBase64 = mask ? await readBase64FromPath(mask) : undefined;
   const body = {
     ...buildGenerationBody(prompt, opts),
     input_images_base64: inputBase64,
     ...(maskBase64 ? { mask_base64: maskBase64 } : {}),
   };
-  const result = await callGateway("/v1/images/edits", body);
+  const result = await callGateway(ctx, "/v1/images/edits", body);
   if (!result.b64_json) {
     throw new ImageCliError("Gateway response did not include image bytes.");
   }
@@ -379,9 +387,10 @@ function imageHelp(): void {
   console.log(`Usage: dench image <subcommand>
 
 Generate or edit images via the Dench Cloud Gateway (gpt-image-2). Auths
-with DENCH_API_KEY (baked into every sandbox automatically). Each call
-writes the bytes to Convex Storage (workspace tree updates immediately)
-and, when running inside a sandbox, also writes the decoded bytes to
+with DENCH_API_KEY or the active \`dench signin\` agent session. Agent
+sessions require a paid workspace. Each call writes the bytes to Convex
+Storage (workspace tree updates immediately) and, when running inside a sandbox,
+also writes the decoded bytes to
 local disk so subsequent bash commands see the file without waiting on
 the daemon's downward sync.
 
@@ -397,7 +406,7 @@ Edit / remix one or more existing images (image-to-image):
                               [--save-path ...] [--output ...] [--no-write] [--json]
 
 Environment variables:
-  DENCH_API_KEY        Required. Bearer token sent to the gateway.
+  DENCH_API_KEY        Optional when a dench signin agent session is active.
   DENCH_GATEWAY_URL    Override the gateway base URL.
   GATEWAY_URL          Same, used when DENCH_GATEWAY_URL is unset.
   DENCH_HOST           If it points at localhost, defaults to

package/lib/enrichment-gateway.ts

@@ -81,7 +81,7 @@ export function resolveEnrichmentGatewayBaseUrl(
   env: EnrichmentGatewayEnv = process.env,
 ): string {
   const explicit = env.DENCH_GATEWAY_URL?.trim() || env.GATEWAY_URL?.trim();
-  if (explicit) return explicit.replace(/\/+$/, "");
+  if (explicit) return explicit.replace(/\/+$/, "").replace(/\/v1$/, "");
 
   const host = env.DENCH_HOST?.trim();
   if (host && /localhost|127\.0\.0\.1/.test(host)) {
@@ -1248,7 +1248,7 @@ async function callGatewayJson(
 
 function resolveBaseUrl(options: EnrichmentGatewayOptions): string {
   return (
-    options.baseUrl?.trim().replace(/\/+$/, "") ??
+    options.baseUrl?.trim().replace(/\/+$/, "").replace(/\/v1$/, "") ??
     resolveEnrichmentGatewayBaseUrl(options.env)
   );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dench.com/cli",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Dench agent workspace CLI. v2 unifies auth behind `dench signin`; the legacy `dench login` / `dench onboard` / `dench setup` / `dench what-can-i-do` / `dench register` commands now error with a redirect.",
   "type": "module",
   "bin": {

package/search.ts

@@ -2,11 +2,9 @@
  * `dench search` — live web access through the Dench Cloud Gateway.
  *
  * The gateway exposes Exa Search at three routes; we mirror them as
- * three subcommands and authenticate with the `DENCH_API_KEY` baked
- * into every sandbox at create time. Unlike most other CLI surfaces
- * this one bypasses Convex entirely — it speaks straight HTTP to the
- * gateway, so it works in any environment that has the env var
- * (sandboxes, CI, local dev with `DENCH_API_KEY` exported manually).
+ * three subcommands and authenticate with either `DENCH_API_KEY` or a
+ * paid-workspace gateway key resolved from the active agent session by
+ * the top-level dispatcher.
  *
  * Subcommands:
  *   search "<query>"       [--num-results N] [--type auto|fast|deep|deep-reasoning|neural]
@@ -17,32 +15,21 @@
  *   search answer "<query>" [--json]
  */
 
-import {
-  CliArgError,
-  getFlag,
-  hasFlag,
-  shift as shiftRaw,
-} from "./lib/cli-args";
+import { getFlag } from "./lib/cli-args";
 
 type SearchCliContext = {
   args: string[];
   jsonOutput: boolean;
+  bearerToken?: string;
+  gatewayBaseUrl?: string;
 };
 
 class SearchCliError extends Error {}
 
-function shift(args: string[], expected: string): string {
-  try {
-    return shiftRaw(args, expected);
-  } catch (error) {
-    if (error instanceof CliArgError) {
-      throw new SearchCliError(error.message);
-    }
-    throw error;
-  }
-}
-
-function parsePositiveInt(name: string, raw: string | undefined): number | undefined {
+function parsePositiveInt(
+  name: string,
+  raw: string | undefined,
+): number | undefined {
   if (raw === undefined) return undefined;
   const parsed = Number(raw);
   if (!Number.isFinite(parsed) || parsed <= 0) {
@@ -78,10 +65,19 @@ const ALLOWED_CATEGORIES = new Set([
   "people",
 ]);
 
-function resolveGatewayBaseUrl(): string {
+function normalizeGatewayBaseUrl(value: string): string {
+  return value.replace(/\/+$/, "").replace(/\/v1$/, "");
+}
+
+function resolveGatewayBaseUrl(
+  ctx?: Pick<SearchCliContext, "gatewayBaseUrl">,
+): string {
+  if (ctx?.gatewayBaseUrl?.trim()) {
+    return normalizeGatewayBaseUrl(ctx.gatewayBaseUrl.trim());
+  }
   const explicit =
     process.env.DENCH_GATEWAY_URL?.trim() || process.env.GATEWAY_URL?.trim();
-  if (explicit) return explicit.replace(/\/+$/, "");
+  if (explicit) return normalizeGatewayBaseUrl(explicit);
   // Local dev: the gateway listens on :8787 (matches gateway/src/index.ts
   // and the dev-server skill). Anything that smells like localhost in
   // DENCH_HOST routes to the local gateway too so `dench --host
@@ -93,29 +89,31 @@ function resolveGatewayBaseUrl(): string {
   return "https://gateway.merseoriginals.com";
 }
 
-function requireApiKey(): string {
-  const apiKey = process.env.DENCH_API_KEY?.trim();
-  if (!apiKey) {
+function requireBearerToken(
+  ctx?: Pick<SearchCliContext, "bearerToken">,
+): string {
+  const bearerToken =
+    ctx?.bearerToken?.trim() || process.env.DENCH_API_KEY?.trim();
+  if (!bearerToken) {
     throw new SearchCliError(
-      "DENCH_API_KEY is not set. Inside a Dench sandbox it is baked into " +
-        "the env automatically; outside, export it manually or run " +
-        "`dench login` first.",
+      "No Dench gateway credential found. Set DENCH_API_KEY or run `dench signin` for a paid workspace.",
     );
   }
-  return apiKey;
+  return bearerToken;
 }
 
 async function callGateway(
+  ctx: SearchCliContext,
   path: "/v1/search" | "/v1/search/contents" | "/v1/search/answer",
   body: Record<string, unknown>,
 ): Promise<unknown> {
-  const apiKey = requireApiKey();
-  const baseUrl = resolveGatewayBaseUrl();
+  const bearerToken = requireBearerToken(ctx);
+  const baseUrl = resolveGatewayBaseUrl(ctx);
   const response = await fetch(`${baseUrl}${path}`, {
     method: "POST",
     headers: {
       "content-type": "application/json",
-      Authorization: `Bearer ${apiKey}`,
+      Authorization: `Bearer ${bearerToken}`,
     },
     body: JSON.stringify(body),
   });
@@ -143,7 +141,9 @@ function asString(value: unknown): string | undefined {
 }
 
 function asNumber(value: unknown): number | undefined {
-  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+  return typeof value === "number" && Number.isFinite(value)
+    ? value
+    : undefined;
 }
 
 function asObject(value: unknown): Record<string, unknown> | undefined {
@@ -184,7 +184,8 @@ function formatSearchResults(payload: unknown, limit?: number): string {
     lines.push("(no results)");
     return lines.join("\n");
   }
-  const cap = limit !== undefined ? Math.min(results.length, limit) : results.length;
+  const cap =
+    limit !== undefined ? Math.min(results.length, limit) : results.length;
   for (let i = 0; i < cap; i++) {
     const result = asObject(results[i]);
     if (!result) continue;
@@ -197,7 +198,9 @@ function formatSearchResults(payload: unknown, limit?: number): string {
     const snippet =
       asString(result.text) ??
       (Array.isArray(result.highlights)
-        ? result.highlights.filter((h): h is string => typeof h === "string").join(" ")
+        ? result.highlights
+            .filter((h): h is string => typeof h === "string")
+            .join(" ")
         : undefined) ??
       asString(result.summary);
     lines.push(`${i + 1}. ${title}`);
@@ -284,7 +287,10 @@ function out(ctx: SearchCliContext, payload: unknown, formatted: string): void {
 // ────────────────────────────────────────────────────────────────────────────
 
 async function runSearchSubcommand(ctx: SearchCliContext): Promise<void> {
-  const numResults = parsePositiveInt("--num-results", getFlag(ctx.args, "--num-results"));
+  const numResults = parsePositiveInt(
+    "--num-results",
+    getFlag(ctx.args, "--num-results"),
+  );
   const type = getFlag(ctx.args, "--type");
   if (type !== undefined && !ALLOWED_TYPES.has(type)) {
     throw new SearchCliError(
@@ -321,12 +327,15 @@ async function runSearchSubcommand(ctx: SearchCliContext): Promise<void> {
   if (category) body.category = category;
   if (includeDomains) body.includeDomains = includeDomains;
   if (excludeDomains) body.excludeDomains = excludeDomains;
-  const payload = await callGateway("/v1/search", body);
+  const payload = await callGateway(ctx, "/v1/search", body);
   out(ctx, payload, formatSearchResults(payload, numResults));
 }
 
 async function runContentsSubcommand(ctx: SearchCliContext): Promise<void> {
-  const maxChars = parsePositiveInt("--max-chars", getFlag(ctx.args, "--max-chars"));
+  const maxChars = parsePositiveInt(
+    "--max-chars",
+    getFlag(ctx.args, "--max-chars"),
+  );
   const summary = getFlag(ctx.args, "--summary");
   const urls = ctx.args.slice();
   ctx.args.length = 0;
@@ -346,7 +355,7 @@ async function runContentsSubcommand(ctx: SearchCliContext): Promise<void> {
     highlights: { maxCharacters: 200 },
   };
   if (summary) body.summary = { query: summary };
-  const payload = await callGateway("/v1/search/contents", body);
+  const payload = await callGateway(ctx, "/v1/search/contents", body);
   out(ctx, payload, formatContentsResults(payload));
 }
 
@@ -355,11 +364,9 @@ async function runAnswerSubcommand(ctx: SearchCliContext): Promise<void> {
   ctx.args.length = 0;
   const query = queryParts.join(" ").trim();
   if (!query) {
-    throw new SearchCliError(
-      'Usage: dench search answer "<query>" [--json]',
-    );
+    throw new SearchCliError('Usage: dench search answer "<query>" [--json]');
   }
-  const payload = await callGateway("/v1/search/answer", {
+  const payload = await callGateway(ctx, "/v1/search/answer", {
     query,
     text: true,
     stream: false,
@@ -371,7 +378,8 @@ function searchHelp(): void {
   console.log(`Usage: dench search <subcommand>
 
 Live web access through the Dench Cloud Gateway (Exa Search). Auths
-with DENCH_API_KEY (baked into every sandbox automatically).
+with DENCH_API_KEY or the active \`dench signin\` agent session. Agent
+sessions require a paid workspace.
 
 Search the web (default subcommand):
   dench search "<query>" [--num-results N] [--type auto|fast|deep|deep-reasoning|neural]
@@ -386,7 +394,7 @@ One-shot synthesised answer with citations (Exa /search/answer):
   dench search answer "<query>" [--json]
 
 Environment variables:
-  DENCH_API_KEY        Required. Bearer token sent to the gateway.
+  DENCH_API_KEY        Optional when a dench signin agent session is active.
   DENCH_GATEWAY_URL    Override the gateway base URL.
   GATEWAY_URL          Same, used when DENCH_GATEWAY_URL is unset.
   DENCH_HOST           If it points at localhost, defaults to

package/tools.ts

@@ -3,13 +3,9 @@
  * Composio's get-apps / get-tools / execute-tool surface.
  *
  * Mirrors `denchclaw`'s pattern: this CLI is a thin wrapper over five
- * gateway endpoints, authenticated with the unified `DENCH_API_KEY`
- * baked into every Dench sandbox at create time. There is no Convex
- * session involved; that means these subcommands work in any
- * environment that has the API key (sandboxes, CI, local dev with the
- * key exported manually). The previous implementation forced
- * `requireSessionRuntime` and routed through a Convex action, which
- * broke `apiKey` runtime mode entirely.
+ * gateway endpoints, authenticated with either `DENCH_API_KEY` or a
+ * paid-workspace gateway key resolved from the active agent session by
+ * the top-level dispatcher.
  *
  * Subcommands:
  *
@@ -20,7 +16,7 @@
  *   dench tool connect <toolkit> [--callback-url <url>] [--json]   — print OAuth redirect URL
  *   dench tool disconnect <connectionId> [--json]
  *
- * Endpoints used (all `Authorization: Bearer DENCH_API_KEY`):
+ * Endpoints used (all `Authorization: Bearer <gateway credential>`):
  *
  *   GET    /v1/composio/connections
  *   GET    /v1/composio/toolkits?search=<slug>
@@ -36,10 +32,7 @@
  * working.
  */
 
-import {
-  PRODUCTION_API_URL,
-  PRODUCTION_GATEWAY_URL,
-} from "./host";
+import { PRODUCTION_API_URL, PRODUCTION_GATEWAY_URL } from "./host";
 import {
   CliArgError,
   getFlag,
@@ -55,8 +48,15 @@ import {
 export type ToolCliContext = {
   args: string[];
   jsonOutput: boolean;
+  bearerToken?: string;
+  gatewayBaseUrl?: string;
 };
 
+type GatewayAuthContext = Pick<
+  ToolCliContext,
+  "bearerToken" | "gatewayBaseUrl"
+>;
+
 export async function runToolCommand(ctx: ToolCliContext): Promise<void> {
   const sub = ctx.args[0];
   if (!sub || sub === "help" || sub === "--help" || sub === "-h") {
@@ -91,11 +91,14 @@ export async function runToolCommand(ctx: ToolCliContext): Promise<void> {
 
 /**
  * Summarise the user's connected apps for `dench context` and friends.
- * Bypasses any Convex session and speaks straight to the gateway.
+ * Speaks straight to the gateway with either DENCH_API_KEY or a gateway
+ * key resolved from the active agent session.
  * Returns the same legacy shape the previous Convex-routed path did so
  * existing parsers don't need to change.
  */
-export async function fetchConnectedAppsSummary(): Promise<{
+export async function fetchConnectedAppsSummary(
+  ctx: GatewayAuthContext = {},
+): Promise<{
   available: boolean;
   count: number;
   connections: Array<{
@@ -109,7 +112,7 @@ export async function fetchConnectedAppsSummary(): Promise<{
 }> {
   let payload: unknown;
   try {
-    payload = await callGateway("GET", "/v1/composio/connections");
+    payload = await callGateway(ctx, "GET", "/v1/composio/connections");
   } catch (error) {
     if (error instanceof MissingApiKeyError) {
       return {
@@ -139,6 +142,7 @@ async function runStatusSubcommand(ctx: ToolCliContext): Promise<void> {
   if (filterToolkit) ctx.args.shift();
 
   const connectionsPayload = await callGateway(
+    ctx,
     "GET",
     "/v1/composio/connections",
   );
@@ -146,6 +150,7 @@ async function runStatusSubcommand(ctx: ToolCliContext): Promise<void> {
   if (filterToolkit) {
     const search = encodeURIComponent(filterToolkit);
     toolkitsPayload = await callGateway(
+      ctx,
       "GET",
       `/v1/composio/toolkits?search=${search}`,
     );
@@ -194,7 +199,12 @@ async function runSearchSubcommand(ctx: ToolCliContext): Promise<void> {
   if (toolkit) body.toolkit_slug = toolkit;
   if (limit) body.limit = limit;
 
-  const payload = await callGateway("POST", "/v1/composio/tools/search", body);
+  const payload = await callGateway(
+    ctx,
+    "POST",
+    "/v1/composio/tools/search",
+    body,
+  );
   if (ctx.jsonOutput) {
     console.log(JSON.stringify(payload, null, 2));
     return;
@@ -231,7 +241,12 @@ async function runRunSubcommand(ctx: ToolCliContext): Promise<void> {
 
   let payload: unknown;
   try {
-    payload = await callGateway("POST", "/v1/composio/tools/execute", body);
+    payload = await callGateway(
+      ctx,
+      "POST",
+      "/v1/composio/tools/execute",
+      body,
+    );
   } catch (error) {
     if (error instanceof GatewayHttpError && isLikelyNoConnection(error)) {
       const noConnPayload = noConnectionPayload(toolSlug, error);
@@ -266,7 +281,7 @@ async function runConnectSubcommand(ctx: ToolCliContext): Promise<void> {
     process.env.DENCH_OAUTH_CALLBACK_URL?.trim() ??
     `${resolveAppPublicOrigin()}/api/composio/callback`;
 
-  const payload = await callGateway("POST", "/v1/composio/connect", {
+  const payload = await callGateway(ctx, "POST", "/v1/composio/connect", {
     toolkit,
     callback_url: callbackUrl,
   });
@@ -313,7 +328,7 @@ async function runDisconnectSubcommand(ctx: ToolCliContext): Promise<void> {
   const path = `/v1/composio/connections/${encodeURIComponent(connectionId)}`;
   let payload: unknown = { ok: true, deleted: true };
   try {
-    payload = await callGateway("DELETE", path);
+    payload = await callGateway(ctx, "DELETE", path);
   } catch (error) {
     // Composio returns 404 for connections that are already gone — surface
     // that as a soft success so callers can keep their local state in sync.
@@ -350,9 +365,8 @@ class ToolCliError extends Error {
 class MissingApiKeyError extends ToolCliError {
   constructor() {
     super(
-      "DENCH_API_KEY is not set. Inside a Dench sandbox it is baked into " +
-        "the env automatically; outside, export it manually or run " +
-        "`dench login` and copy the api-key from the output.",
+      "No Dench gateway credential found. Set DENCH_API_KEY or run " +
+        "`dench signin` for a paid workspace.",
     );
     this.name = "MissingApiKeyError";
   }
@@ -376,10 +390,19 @@ class GatewayHttpError extends ToolCliError {
   }
 }
 
-function resolveGatewayBaseUrl(): string {
+function normalizeGatewayBaseUrl(value: string): string {
+  return value.replace(/\/+$/, "").replace(/\/v1$/, "");
+}
+
+function resolveGatewayBaseUrl(
+  ctx?: Pick<ToolCliContext, "gatewayBaseUrl">,
+): string {
+  if (ctx?.gatewayBaseUrl?.trim()) {
+    return normalizeGatewayBaseUrl(ctx.gatewayBaseUrl.trim());
+  }
   const explicit =
     process.env.DENCH_GATEWAY_URL?.trim() || process.env.GATEWAY_URL?.trim();
-  if (explicit) return explicit.replace(/\/+$/, "");
+  if (explicit) return normalizeGatewayBaseUrl(explicit);
   const host = process.env.DENCH_HOST?.trim();
   if (host && /localhost|127\.0\.0\.1/.test(host)) {
     return "http://localhost:8787";
@@ -410,24 +433,26 @@ function resolveAppPublicOrigin(): string {
   return PRODUCTION_API_URL;
 }
 
-function requireApiKey(): string {
-  const apiKey = process.env.DENCH_API_KEY?.trim();
-  if (!apiKey) throw new MissingApiKeyError();
-  return apiKey;
+function requireBearerToken(ctx?: Pick<ToolCliContext, "bearerToken">): string {
+  const bearerToken =
+    ctx?.bearerToken?.trim() || process.env.DENCH_API_KEY?.trim();
+  if (!bearerToken) throw new MissingApiKeyError();
+  return bearerToken;
 }
 
 async function callGateway(
+  ctx: GatewayAuthContext,
   method: "GET" | "POST" | "DELETE",
   path: string,
   body?: Record<string, unknown>,
 ): Promise<unknown> {
-  const apiKey = requireApiKey();
-  const baseUrl = resolveGatewayBaseUrl();
+  const bearerToken = requireBearerToken(ctx);
+  const baseUrl = resolveGatewayBaseUrl(ctx);
   const init: RequestInit = {
     method,
     headers: {
       "content-type": "application/json",
-      authorization: `Bearer ${apiKey}`,
+      authorization: `Bearer ${bearerToken}`,
     },
   };
   if (body !== undefined) init.body = JSON.stringify(body);
@@ -730,8 +755,8 @@ Usage:
   dench tool disconnect <connectionId> [--json]
 
 Notes:
-  All commands authenticate with DENCH_API_KEY (Bearer) directly to the
-  Dench Cloud Gateway. No \`dench login\` agent session required.
+  All commands authenticate with DENCH_API_KEY or the active \`dench signin\`
+  agent session. Agent sessions require a paid workspace.
   dench tool connect prints the OAuth redirect URL for the human to open.
   dench tool run output is redacted for display; pass --json for raw output.
   Override the gateway base with DENCH_GATEWAY_URL or GATEWAY_URL.
@@ -804,7 +829,7 @@ function parsePositiveInt(name: string, raw: string): number {
 // them as unused when callers tree-shake.
 export { ToolCliError, GatewayHttpError, MissingApiKeyError };
 // Kept reachable so a future caller can build their own dispatcher.
-export { resolveGatewayBaseUrl, requireApiKey, callGateway };
+export { resolveGatewayBaseUrl, requireBearerToken, callGateway };
 // shiftRaw / hasFlag from cli-args are not used in this module yet but
 // keep the import group consistent with cli/search.ts conventions.
 void shiftRaw;