@dench.com/cli 2.0.0 → 2.0.2

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.2",
   "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;