@dench.com/cli 3.8.1-staging.390 → 3.8.2-staging.392

package/ads.ts

@@ -2000,7 +2000,11 @@ async function runWithdrawCommand(opts: {
 // ---------------------------------------------------------------------------
 
 function adsHelp(): void {
-  console.log(`dench ads — monetize the AI "thinking…" line. (aliases: dench ad, dench adline)
+  console.log(adsHelpText());
+}
+
+export function adsHelpText(): string {
+  return `\`dench ads\` — monetize the AI "thinking…" line. (aliases: dench ad, dench adline)
 
 Usage:
   dench ads                 Print the sponsored ad in a decorated rainbow box
@@ -2035,7 +2039,7 @@ Notes:
   • Set DENCH_ADS_ENDPOINT=https://your-server/ads to serve real ads:
     GET returns {id,label,url,icon,iconUrl}; POST {endpoint}/impressions
     takes {events:[{adId,count,flushId}]}.
-`);
+`;
 }
 
 // ---------------------------------------------------------------------------

package/apps.ts

@@ -91,8 +91,12 @@ function withAuth(ctx: Ctx, args: Record<string, unknown>) {
   } as never;
 }
 
-function appsHelp() {
-  console.log(`Usage: dench apps <subcommand>   (App Store — not connected apps; see 'dench integrations')
+function appsHelp(): void {
+  console.log(appsHelpText());
+}
+
+export function appsHelpText(): string {
+  return `Usage: dench apps <subcommand>   (App Store — not connected apps; see 'dench integrations')
 
   dench apps list [--json]                       Installed apps in this workspace
   dench apps gallery [--json]                    Discover listings — Official (Dench) + Community
@@ -113,7 +117,7 @@ function appsHelp() {
   dench apps webhooks list <slug>
   dench apps webhooks poll <slug> <hookName> [--since <ms>] [--limit <n>]
   dench apps webhooks delete <slug> <hookName>
-`);
+`;
 }
 
 const TEXT_FILE = /\.(html?|js|mjs|cjs|ts|jsx|tsx|css|json|ya?ml|md|txt|svg)$/i;

package/browser.ts

@@ -81,7 +81,11 @@ const ACTIONS = new Set([
 ]);
 
 function browserHelp(): void {
-  console.log(`Usage: dench browser <action> [options]
+  console.log(browserHelpText());
+}
+
+export function browserHelpText(): string {
+  return `Usage: dench browser <action> [options]
 
 Control Dench Browser without opening dench.com locally.
 Commands authenticate with the active dench signin session or DENCH_API_KEY.
@@ -105,6 +109,7 @@ Common:
   dench browser activate-tab <targetId>
   dench browser close-tab <targetId>
   dench browser stop
+  dench browser reset
 
 Playwright sessions:
   dench browser session create --json
@@ -114,8 +119,8 @@ Playwright sessions:
 State:
   The CLI remembers the latest browser thread per Dench host/session.
   Use --thread <threadId> to control a specific thread, or
-  dench browser reset to forget the local remembered thread.
-`);
+  \`dench browser reset\` to forget the local remembered thread.
+`;
 }
 
 function consumeFlagValue(args: string[], name: string): string | undefined {

package/campaign.ts

@@ -4218,7 +4218,7 @@ export function campaignHelp(subcommand?: string): void {
   );
 }
 
-function campaignHelpText(): string {
+export function campaignHelpText(): string {
   return `Usage: dench campaign <subcommand> [--json]
 
 Outreach campaigns send email and LinkedIn steps to a list of people on one

package/chat.ts

@@ -112,7 +112,11 @@ function out(ctx: ChatCliContext, value: unknown): void {
 }
 
 function chatHelp(): void {
-  console.log(`Usage: dench chat <subcommand>
+  console.log(chatHelpText());
+}
+
+export function chatHelpText(): string {
+  return `Usage: dench chat <subcommand>
 
 List past chat threads (own + shared in this workspace):
   dench chat list [--query <substr>] [--limit N] [--include-archived] [--include-automated] [--json]
@@ -165,7 +169,7 @@ Auth:
 Global flags:
   --json    Output raw JSON instead of pretty-printed text.
   --follow  After spawning, stream the chat response to stdout.
-`);
+`;
 }
 
 export async function runChatCommand(opts: {

package/cron.ts

@@ -871,7 +871,11 @@ async function runHistory(ctx: CronCliContext): Promise<void> {
 // ─── Help ─────────────────────────────────────────────────────────────────
 
 function cronHelp(): void {
-  console.log(`Usage: dench cron <subcommand>
+  console.log(cronHelpText());
+}
+
+export function cronHelpText(): string {
+  return `Usage: dench cron <subcommand>
        dench routine <subcommand>     (alias)
        dench routines <subcommand>    (alias)
 
@@ -902,7 +906,7 @@ Create / update:
   dench cron create "Inbound lead triage" --prompt "Triage the lead…" --type webhook [--signed]
 
   # App-event automation (fires when something happens in a connected app).
-  #   1. dench apps --json                    → connectedAccountId + toolkit
+  #   1. dench integrations --json            → connectedAccountId + toolkit
   #   2. dench cron events <toolkit>          → event slug
   dench cron create "New GitHub star" --prompt "Thank the new stargazer" \\
       --type app --connection <connectedAccountId> --event <triggerSlug> \\
@@ -955,7 +959,7 @@ Examples:
 Auth: prefers DENCH_API_KEY (sandbox envVar). Falls back to a session token from
 \`dench login\` for local terminals. The Bearer token must carry either
 \`crons:read\` (queries) or \`crons:write\` (mutations) scope, or the wildcard \`*\`.
-`);
+`;
 }
 
 // ─── Entry point ──────────────────────────────────────────────────────────

package/dench.ts

@@ -18,7 +18,6 @@ import { makeFunctionReference } from "convex/server";
 import { agentKindLabel, normalizeAgentKind } from "./agentKind";
 import {
   apiHostForDenchHost,
-  DEFAULT_HOST,
   isLocalHost,
   LOCAL_HOST,
   normalizeHost,
@@ -281,6 +280,11 @@ const BOOLEAN_FLAGS = new Set([
 ]);
 
 function positionalArgs() {
+  const fileArgs = stripRuntimeFlags(filteredArgs);
+  if (fileArgs[0] === "files") {
+    const switches = new Set(["--recursive", "-r", "--url"]);
+    return fileArgs.filter((value, index) => index < 2 || !switches.has(value));
+  }
   const positionals: string[] = [];
   for (let i = 0; i < filteredArgs.length; i++) {
     if (filteredArgs[i].startsWith("--")) {
@@ -467,8 +471,8 @@ function logHuman(message: string) {
   }
 }
 
-function help() {
-  console.log(`Dench CLI
+function rootUsageText() {
+  return `Dench CLI
 
 Usage:
   dench signin [--kind <kind>] [--name "AI Agent - Project"] [--no-open] [--json]
@@ -479,7 +483,9 @@ 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 backend show [--json]
+  dench backend set <production|staging|local|url> [--json]
+  dench backend clear [--json]
   dench context [--instructions] [--json]
   dench context --sections organisation,user,memory [--json]
   dench instructions [--json]
@@ -686,62 +692,17 @@ Standing context and memory:
   dench context --sections identity,organisation,user,memory,rules,tools [--json]
   dench context set <identity|organisation|user|tools|rules> --stdin
   dench memory search "<query>" | save <key> "<fact>"
-  dench model default <id|clear> | thread <threadId> <id|clear>
+  dench model default <id|clear>
+  dench model thread <threadId> <id|clear>
   Context describes preferences and instructions. Environments store setup;
   secrets store credentials. A memory note does not install or save either.
 
-External tools:
-  dench integrations is an alias for dench tool status -- it lists connected apps.
-  dench apps is the App Store (create / install / publish / list), not connected apps.
-  dench tool with no subcommand prints tool help.
-  Read-only FETCH, GET, LIST, SEARCH, READ, and FIND tools do not need manual approval.
-
-Billing:
-  dench billing status shows current AI credits.
-  dench billing topup --amount 5 creates a Stripe Checkout link for the human to pay.
-
-Agent setup:
-  dench signin is the only auth surface. Two transports (browser link
-  by default, OTP paste-back with --email <addr>) cover both intents:
-  signing in to an existing workspace or creating a new free CRM-only
-  workspace (--new-workspace --org-name "<name>"). New workspaces have
-  full CRM access; run \`dench upgrade\` to unlock chat, file sync,
-  enrichment, and image generation.
-  --kind accepts any string. Suggested values: claude_code, codex, cursor,
-  hermes, openclaw, or any custom kind (e.g. aider, goose, internal_orchestrator).
-  Defaults to "other" when omitted. Values are normalized to lowercase
-  snake_case before send (e.g. "Claude Code" -> claude_code).
-  After sign-in, run dench context --json and dench crm objects list --json
-  to verify the workspace + CRM are wired up. Tasks live as CRM \`task\`
-  entries — there is no separate \`dench tasks\` / \`dench task\` /
-  \`dench claim\` / \`dench log\` command.
-
-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 dev deployment with a dev key):
-  DENCH_DEV_AGENT_KEY=... DENCH_WORKSPACE=... dench status --dev
-  Inside the dench.com repo, --dev also auto-loads .env / .env.local,
-  which carry the dev backend URL and GATEWAY_URL etc. 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:
-    DENCH_SESSION_KEY=stable-agent-id dench signin
-    DENCH_SESSION_KEY=stable-agent-id dench logout
-    DENCH_SESSION_KEY=stable-agent-id dench status
-`);
+`;
+}
+
+async function help() {
+  const { commandHelp } = await import("./lib/command-help");
+  console.log(commandHelp([], rootUsageText()));
 }
 
 function contextHelp() {
@@ -3780,7 +3741,7 @@ async function runFilesCat() {
       code: "files_cat_not_found",
       nextActions: [
         "Run `dench files ls` on the parent directory to confirm.",
-        "If the file only exists on the sandbox FS, run `dench fs sync --initial` first.",
+        "If the file exists only on local disk, upload it with `dench stage <local-path> <workspace-path>`.",
       ],
     });
   }
@@ -3850,11 +3811,11 @@ async function runFilesWrite() {
   )) as { path: string; contentHash: string };
 
   if (json) {
-    print({ ok: true, ...result, bytes: content.length });
+    print({ ok: true, ...result, bytes: Buffer.byteLength(content, "utf8") });
     return;
   }
   process.stdout.write(
-    `dench files write: ${result.path} (${content.length}B)\n`,
+    `dench files write: ${result.path} (${Buffer.byteLength(content, "utf8")}B)\n`,
   );
 }
 
@@ -3916,7 +3877,7 @@ async function runFilesDownload() {
         code: "files_download_not_found",
         nextActions: [
           "Run `dench files ls` on the parent directory to confirm.",
-          "If the file only exists on the sandbox FS, run `dench fs sync --initial` first.",
+          "If the file exists only on local disk, upload it with `dench stage <local-path> <workspace-path>`.",
         ],
       });
     }
@@ -3990,25 +3951,8 @@ async function runFilesDownload() {
 async function runFilesCommand() {
   const sub = positional(1);
   if (!sub || sub === "help" || hasFlag("--help")) {
-    process.stdout.write(
-      [
-        "dench files <ls|cat|write|mv|rm|download> — workspace file ops that update the UI tree",
-        "",
-        "  dench files ls [<path>] [--recursive] [--json]",
-        "  dench files cat <path> [--json]",
-        "  dench files write <path> < file.md   (content on stdin)",
-        "  dench files mv <src> <dst> [--json]",
-        "  dench files rm <path> [--recursive] [--json]",
-        "  dench files download <path> [<local-dest>] [--url] [--json]",
-        "",
-        "Paths are POSIX paths under /workspace; you can pass either form.",
-        "These change workspace storage directly (and the daemon syncs to the volume).",
-        "cat prints inline text and is the only way to read the magic files",
-        "(IDENTITY.md, ORGANISATION.md, …), which have no stored bytes.",
-        "download fetches the canonical bytes from workspace storage (dirs recurse);",
-        "--url prints a short-lived signed URL instead of saving.",
-      ].join("\n"),
-    );
+    const { commandHelp } = await import("./lib/command-help");
+    process.stdout.write(`${commandHelp(["files"], rootUsageText())}\n`);
     return;
   }
   if (sub === "ls") return await runFilesLs();
@@ -4328,7 +4272,7 @@ async function main() {
     );
     if (helpArgs[0] === "help") helpArgs.shift();
     if (!helpArgs.length) {
-      help();
+      await help();
       return;
     }
     const path = helpArgs.filter(
@@ -4402,24 +4346,38 @@ async function main() {
       });
       return;
     }
-    const { commandHelp } = await import("./lib/command-help");
-    const usage =
-      helpArgs[0] === "email"
-        ? (await import("./email")).emailHelpText()
-        : helpArgs[0] === "crm"
-          ? (await import("./crm")).crmHelpText()
-          : helpArgs[0] === "env"
-            ? (await import("./environments")).environmentHelpText()
-            : helpArgs[0] === "secrets"
-              ? (await import("./workspace-secrets")).workspaceSecretsHelpText()
-              : "";
+    const { commandHelp, normalizeHelpCommand } = await import(
+      "./lib/command-help"
+    );
+    const family = normalizeHelpCommand(helpArgs)[0];
+    const helpText: Record<string, () => Promise<string>> = {
+      tool: async () => (await import("./tools")).toolHelpText(),
+      email: async () => (await import("./email")).emailHelpText(),
+      crm: async () => (await import("./crm")).crmHelpText(),
+      env: async () => (await import("./environments")).environmentHelpText(),
+      secrets: async () =>
+        (await import("./workspace-secrets")).workspaceSecretsHelpText(),
+      chat: async () => (await import("./chat")).chatHelpText(),
+      cron: async () => (await import("./cron")).cronHelpText(),
+      apps: async () => (await import("./apps")).appsHelpText(),
+      members: async () => (await import("./members")).membersHelpText(),
+      web: async () => (await import("./web")).webHelpText(),
+      meetings: async () => (await import("./meetings")).meetingsHelpText(),
+      lists: async () => (await import("./leads")).listsHelpText(),
+      browser: async () => (await import("./browser")).browserHelpText(),
+      search: async () => (await import("./search")).searchHelpText(),
+      image: async () => (await import("./image")).imageHelpText(),
+      ads: async () => (await import("./ads")).adsHelpText(),
+      campaign: async () => (await import("./campaign")).campaignHelpText(),
+    };
+    const usage = helpText[family] ? await helpText[family]() : rootUsageText();
     console.log(commandHelp(helpArgs, usage));
     return;
   }
   const command = positional(0);
   const subcommand = positional(1);
 
-  assertDeclaredCommandFlags(stripRuntimeFlags(runtimeArgs));
+  assertDeclaredCommandFlags(stripRuntimeFlags(args));
 
   // New setup commands validate before authentication and never consume child flags.
   if (command === "env" || command === "secrets") {
@@ -4555,7 +4513,7 @@ async function main() {
   }
 
   if (!command || command === "help") {
-    help();
+    await help();
     return;
   }
 

package/image.ts

@@ -384,7 +384,11 @@ async function runEditSubcommand(ctx: ImageCliContext): Promise<void> {
 }
 
 function imageHelp(): void {
-  console.log(`Usage: dench image <subcommand>
+  console.log(imageHelpText());
+}
+
+export function imageHelpText(): string {
+  return `Usage: dench image <subcommand>
 
 Generate or edit images via the Dench Cloud Gateway. Auths
 with DENCH_API_KEY or the active \`dench signin\` agent session. Agent
@@ -415,7 +419,7 @@ Environment variables:
   DENCH_ORG_ID         Forwarded so wildcard keys can target an org.
   DENCH_RUN_ID         Forwarded for telemetry correlation.
 
-Exit codes: 0 success, non-zero on gateway / network errors.`);
+Exit codes: 0 success, non-zero on gateway / network errors.`;
 }
 
 // ────────────────────────────────────────────────────────────────────────────

package/leads.ts

@@ -646,7 +646,11 @@ Rename/delete saved searches with \`dench lists rename|delete\`.
 }
 
 export function listsHelp(): void {
-  console.log(`Dench lists
+  console.log(listsHelpText());
+}
+
+export function listsHelpText(): string {
+  return `Dench lists
 
 Usage:
   dench lists [--search "September"] [--limit 25] [--cursor <cursor>] [--json]
@@ -680,7 +684,7 @@ Use \`--preview\` first to review the selection without importing or enrolling a
 Delete removes the list, its exported CSV/JSONL files, and any linked watch.
 CRM lists (saved views on Leads/Companies/Job Postings) are managed with
 \`dench crm views list|get|create|rename|delete\`.
-`);
+`;
 }
 
 /**

package/lib/command-args.ts

@@ -1,4 +1,5 @@
 import { CliArgError, missingFlagValue } from "./cli-args";
+import { FILE_COMMAND_ARGUMENTS } from "./file-command-contract";
 
 type PositionalArity = readonly [min: number, max: number | null];
 
@@ -8,6 +9,10 @@ type CommandArguments = {
   switches: string[];
   positionals: PositionalArity;
   flagPositionals: Record<string, PositionalArity>;
+  usage?: string;
+  description?: string;
+  examples?: string[];
+  notes?: string[];
 };
 const spec = (
   command: string,
@@ -138,9 +143,7 @@ export const COMMAND_ARGUMENTS = [
   ...["delete", "enable", "disable"].map((verb) =>
     spec(`cron ${verb}`, [1, 1]),
   ),
-  spec("files rm", [1, 1], "", "--recursive -r"),
-  spec("files mv", [2, 2]),
-  spec("files write", [1, 1]),
+  ...FILE_COMMAND_ARGUMENTS,
   spec("stage", [1, 2], "", "--clean"),
   ...["identity", "organisation", "user", "tools", "mem"].flatMap((group) =>
     ["edit", "set"].map((verb) =>
@@ -200,16 +203,30 @@ export const COMMAND_ARGUMENTS = [
   browserSpec("stop", [0, 0]),
 ];
 
-export function assertDeclaredCommandFlags(argv: readonly string[]): void {
-  const boundary = argv.indexOf("--");
-  const args = argv
-    .slice(0, boundary < 0 ? undefined : boundary)
-    .filter((arg) => arg !== "--json");
+/** Keep compatibility aliases identical in validation and local discovery. */
+export function normalizeCommandAlias(argv: readonly string[]): string[] {
+  const args = [...argv];
   if (["routine", "routines"].includes(args[0])) args[0] = "cron";
   if (["ad", "adline"].includes(args[0])) args[0] = "ads";
-  if (args[0] === "agent" && ["new", "send"].includes(args[1]))
+  if (args[0] === "agent" && ["new", "send", "follow"].includes(args[1]))
     args[0] = "chat";
   if (args[0] === "crm" && args[1] === "members") args.shift();
+  if (args[0] === "campaigns") args[0] = "campaign";
+  return args;
+}
+
+export function assertDeclaredCommandFlags(argv: readonly string[]): void {
+  const boundary = argv.indexOf("--");
+  const args = normalizeCommandAlias(
+    argv
+      .slice(0, boundary < 0 ? undefined : boundary)
+      .filter((arg) => arg !== "--json"),
+  );
+  if (args[0] === "files" && boundary >= 0) {
+    throw new CliArgError(
+      "dench files does not accept a child-command separator (--). Run `dench files --help` for usage.",
+    );
+  }
   const contract = COMMAND_ARGUMENTS.find(({ command }) =>
     command.split(" ").every((part, index) => args[index] === part),
   );