@dharta/cli 0.6.77

package/src/cli.ts

@@ -0,0 +1,2339 @@
+#!/usr/bin/env node
+import { readFileSync, realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import * as readline from "node:readline";
+import { Argument, Command, InvalidArgumentError, Option } from "commander";
+import { API_KEY_SCOPES, type ApiKeyScope, type ModelKeyProvider } from "@dharta/sdk";
+import { buildContext } from "./context.js";
+import { resolveBaseUrl } from "./config.js";
+import { inferAgentSlug, validateAgentSelectorOptions, validateAgentSlug } from "./agent.js";
+import { login } from "./commands/login.js";
+import {
+  authLogout,
+  authLogoutData,
+  authStatus,
+  authStatusData,
+  authToken,
+} from "./commands/auth.js";
+import { whoami, whoamiData } from "./commands/whoami.js";
+import { api as apiCmd, formatApiResult, prepareApiOptions, validateApiRequest } from "./commands/api.js";
+import { auditLog, auditLogData, validateAuditLogInput } from "./commands/audit-log.js";
+import {
+  COST_ANALYTICS_GROUPS,
+  COST_ANALYTICS_RANGES,
+  ENTITY_ANALYTICS_RANGES,
+  analytics,
+  analyticsData,
+  normalizeAnalyticsOptions,
+  type AnalyticsView,
+} from "./commands/analytics.js";
+import {
+  keysCreate,
+  keysCreateData,
+  keysList,
+  keysListData,
+  keysRename,
+  keysRenameData,
+  keysRevoke,
+  keysRevokeData,
+  validateKeysCreateInput,
+} from "./commands/keys.js";
+import {
+  modelKeysCreate,
+  modelKeysCreateData,
+  modelKeysList,
+  modelKeysListData,
+  modelKeysRevoke,
+  modelKeysRevokeData,
+  prepareModelKeysCreateOptions,
+  MODEL_API_FORMATS,
+  validateModelKeyId,
+  validateModelKeysCreateOptions,
+} from "./commands/model-keys.js";
+import {
+  membersInvite,
+  membersInviteData,
+  membersList,
+  membersListData,
+  membersRemove,
+  membersRemoveData,
+  membersSetRole,
+  membersSetRoleData,
+  validateMembersInviteInput,
+} from "./commands/members.js";
+import {
+  kartaMembersGrant,
+  kartaMembersGrantData,
+  kartaMembersRevoke,
+  kartaMembersRevokeData,
+  kartaMembersSetRole,
+  kartaMembersSetRoleData,
+  kartasArchive,
+  kartasArchiveData,
+  kartasConfigure,
+  kartasConfigureData,
+  kartasRestore,
+  kartasRestoreData,
+  kartasCreate,
+  kartasCreateData,
+  kartasList,
+  kartasListData,
+  kartasName,
+  kartasNameData,
+  kartasShow,
+  kartasShowData,
+  kartaEnvList,
+  kartaEnvListData,
+  kartaEnvSet,
+  kartaEnvSetData,
+  kartaEnvUnset,
+  kartaEnvUnsetData,
+  validateKartaCreateOptions,
+  validateKartaConfigureOptions,
+  validateKartaNameOptions,
+} from "./commands/kartas.js";
+import { usage as usageCmd, usageData } from "./commands/usage.js";
+import {
+  type AgentModelSetOptions,
+  agentsActivateRelease,
+  agentsActivateReleaseData,
+  agentsDashboardEditsSet,
+  agentsDashboardEditsSetData,
+  agentsDelete,
+  agentsDeleteData,
+  agentsList,
+  agentsListData,
+  agentsModelSet,
+  agentsModelSetData,
+  agentsReleases,
+  agentsReleasesData,
+  agentsShow,
+  agentsShowData,
+  agentsServingSet,
+  agentsServingSetData,
+  agentsWorkspaceInspectableSet,
+  agentsWorkspaceInspectableSetData,
+  agentsWorkspaceAccessShow,
+  agentsWorkspaceAccessShowData,
+  agentsWorkspaceAccessSet,
+  agentsWorkspaceAccessSetData,
+  parseWorkspaceAccessAssignments,
+  validateAgentModelSetOptions,
+} from "./commands/agents.js";
+import {
+  embedKeysClearIdentity,
+  embedKeysClearIdentityData,
+  embedKeysCreate,
+  embedKeysCreateData,
+  embedKeysList,
+  embedKeysListData,
+  embedKeysRevoke,
+  embedKeysRevokeData,
+  embedKeysRotate,
+  embedKeysRotateData,
+  embedKeysSetIdentity,
+  embedKeysSetIdentityData,
+  embedKeysToggle,
+  embedKeysToggleData,
+  parseOrigins,
+  validateEmbedKeysCreateInput,
+} from "./commands/embed-keys.js";
+import {
+  capsEndUser,
+  capsEndUserData,
+  capsEndUserSet,
+  capsEndUserSetData,
+  capsBudget,
+  capsBudgetData,
+  capsBudgetSet,
+  capsBudgetSetData,
+  capsInstance,
+  capsInstanceData,
+  capsInstanceSet,
+  capsInstanceSetData,
+  capsSeat,
+  capsSeatData,
+  capsSeatSet,
+  capsSeatSetData,
+  validateBudgetSetOptions,
+  validateCapSetOptions,
+} from "./commands/caps.js";
+import {
+  appearanceGet,
+  appearanceGetData,
+  appearanceSet,
+  appearanceSetData,
+  validateAppearanceSetInput,
+} from "./commands/appearance.js";
+import {
+  schedulesAction,
+  schedulesActionData,
+  schedulesCreate,
+  schedulesCreateData,
+  schedulesDelete,
+  schedulesDeleteData,
+  schedulesList,
+  schedulesListData,
+  validateSchedulesCreateInput,
+} from "./commands/schedules.js";
+import {
+  directoryEndUsers,
+  directoryEndUsersData,
+  directoryInstances,
+  directoryInstancesData,
+  directorySessions,
+  directorySessionsData,
+  validateDirectoryOptions,
+} from "./commands/directories.js";
+import {
+  parseEvents,
+  webhooksCreate,
+  webhooksCreateData,
+  webhooksDelete,
+  webhooksDeleteData,
+  webhooksEnable,
+  webhooksEnableData,
+  webhooksList,
+  webhooksListData,
+  webhooksUpdate,
+  webhooksUpdateData,
+  validateWebhooksCreateInput,
+  validateWebhooksUpdateInput,
+} from "./commands/webhooks.js";
+import { rollback, rollbackData } from "./commands/rollback.js";
+import { deploy, inferMode, validateDeployDir } from "./commands/deploy.js";
+import { status, statusData } from "./commands/status.js";
+import { logsTail, validateLogsOptions } from "./commands/logs.js";
+import { create } from "./commands/create.js";
+import { setup } from "./commands/setup.js";
+import { HARNESS_TYPES } from "./harnesses.js";
+import { offerLogin } from "./login-offer.js";
+import { doctor } from "./commands/doctor.js";
+import { dev as devCmd } from "./commands/dev.js";
+import { registerArtifactCommands } from "./commands/artifact.js";
+import {
+  isHandoffTarget,
+  open as openCmd,
+  openData,
+  openHandoff,
+  openHandoffData,
+  OPEN_TARGETS_HELP,
+  normalizeOpenTarget,
+  validateOpenTarget,
+} from "./commands/open.js";
+import {
+  envDiff,
+  envDiffData,
+  envList,
+  envListData,
+  envPull,
+  envPullData,
+  envSet,
+  envSetData,
+  envUnset,
+  envUnsetData,
+  validateEnvAssignment,
+  validateEnvDiffOptions,
+  validateEnvName,
+  validateEnvPullOptions,
+} from "./commands/env.js";
+import {
+  ps as psCmd,
+  psData,
+  run as runCmd,
+  sessionsList,
+  sessionsListData,
+  sessionsShow,
+  sessionsShowData,
+  validateSessionsListOptions,
+} from "./commands/sessions.js";
+import { update } from "./commands/update.js";
+import { filesLs, filesLsData, filesGet } from "./commands/files.js";
+import { gitCredential } from "./commands/git-credential.js";
+import { bashCompletion, zshCompletion } from "./completions.js";
+import { closestChoice, normalizeHttpUrl, normalizeNonBlank, parsePositiveInteger, parseReleaseVersion } from "./validators.js";
+
+const MEMBER_ROLES = ["owner", "admin", "developer", "billing", "viewer"] as const;
+const DHARTA_ACCESS_AUDIENCES = ["members", "anonymous", "off"] as const;
+const DHARTA_MEMBER_ROLES = ["viewer", "participant", "manager"] as const;
+const MODEL_KEY_AUTH_TYPES = ["api_key", "oauth_subscription"] as const;
+const AGENT_MODEL_SOURCES = ["inherit", "platform"] as const;
+const CLI_API_KEY_SCOPES = API_KEY_SCOPES;
+const STATE_HELP = "State values: on/off, enabled/disabled, true/false.";
+
+interface AgentSelectorOptions {
+  agent?: string;
+  project?: string;
+  dir?: string;
+}
+
+interface SessionListSelectorOptions extends AgentSelectorOptions {
+  limit?: string;
+}
+
+interface DirectorySelectorOptions extends AgentSelectorOptions {
+  limit?: string;
+}
+
+// --json output (RFC 0013 §3): every command that produces a result
+// payload prints it as JSON when --json is set. Progress narration
+// (device-flow codes, download logs) moves to stderr so stdout stays
+// parseable. Commands whose stdout is a stream, a REPL, a script, or a
+// protocol rather than a result payload (dev, logs, completion,
+// git-credential, and `deploy --mode git` whose output is the live
+// push sideband) reject --json. `deploy --mode folder` returns a
+// single payload, so it supports --json.
+//
+// Mechanics: the flag is registered on every node of the command tree
+// so commander's
+// outermost option scan consumes it wherever it appears on the line -
+// so actions read it through optsWithGlobals() on their Command. Commands
+// that always reject JSON keep a hidden parser option so help/completions
+// do not advertise an invalid mode.
+function isJson(cmd: Command): boolean {
+  return Boolean(cmd.optsWithGlobals().json);
+}
+
+function printJson(payload: unknown): void {
+  console.log(JSON.stringify(payload, null, 2));
+}
+
+function commandOpts<T extends object>(cmd: Command): T {
+  return cmd.optsWithGlobals() as T;
+}
+
+function validatePositionalAgentSelector(slug: string | undefined, opts: Pick<AgentSelectorOptions, "agent" | "project">): void {
+  if (slug === undefined) return;
+  validateAgentSlug(slug, "agent slug");
+  if (opts.agent !== undefined || opts.project !== undefined) {
+    throw new Error("Use either the positional agent slug or --agent/--project, not both.");
+  }
+}
+
+function validateCreateInput(pathArg: string | undefined, opts: {
+  name?: string;
+  template?: string;
+  harnessVersion?: string;
+}): void {
+  if (pathArg !== undefined) normalizeNonBlank(pathArg, "path");
+  if (opts.name !== undefined) normalizeNonBlank(opts.name, "--name");
+  if (opts.template !== undefined) normalizeNonBlank(opts.template, "--template");
+  if (opts.harnessVersion !== undefined) normalizeNonBlank(opts.harnessVersion, "--harness-version");
+}
+
+type ResolvedAgentOptions<T extends AgentSelectorOptions> = Omit<T, "agent" | "project"> & {
+  agent: string;
+  project?: undefined;
+};
+
+async function resolveAgentOptions<T extends AgentSelectorOptions>(
+  opts: T,
+  positionalSlug?: string,
+): Promise<ResolvedAgentOptions<T>> {
+  validatePositionalAgentSelector(positionalSlug, opts);
+  validateAgentSelectorOptions(opts);
+  const agent = await inferAgentSlug({
+    agent: positionalSlug ?? opts.agent,
+    project: positionalSlug === undefined ? opts.project : undefined,
+    dir: opts.dir,
+  });
+  return { ...opts, agent, project: undefined } as ResolvedAgentOptions<T>;
+}
+
+function rejectJson(cmd: Command, name: string): void {
+  if (isJson(cmd)) {
+    throw new Error(
+      `--json is not supported for \`${name}\` - its output is not a single payload. Run it without --json.`,
+    );
+  }
+}
+
+function helpOnlyAction(name: string) {
+  return (...args: unknown[]): void => {
+    const cmd = args[args.length - 1] as Command;
+    const extra = cmd.args.filter((arg): arg is string => typeof arg === "string");
+    if (extra.length > 0) {
+      const unknown = extra.join(" ");
+      const path = commandPath(cmd);
+      const suggestion = closestCommand(extra[0], commandSuggestionTokens(cmd));
+      cmd.error(
+        `error: unknown command '${unknown}'${path === "dharta" ? "" : ` for ${path}`}. ` +
+          `Run \`${path} --help\` for available commands.` +
+          (suggestion ? ` Did you mean \`${suggestion}\`?` : ""),
+      );
+    }
+    rejectJson(cmd, name);
+    cmd.outputHelp();
+  };
+}
+
+const logToStderr = (line: string) => process.stderr.write(line + "\n");
+
+function commandPath(cmd: Command): string {
+  const names: string[] = [];
+  let cursor: Command | null = cmd;
+  while (cursor) {
+    names.unshift(cursor.name());
+    cursor = cursor.parent;
+  }
+  return names.join(" ");
+}
+
+function closestCommand(input: string, commands: string[]): string | null {
+  return closestChoice(input, commands);
+}
+
+function commandSuggestionTokens(cmd: Command): string[] {
+  return Array.from(
+    new Set(
+      cmd.commands
+        .filter((child) => !(child as unknown as { _hidden?: boolean })._hidden)
+        .flatMap((child) => [child.name(), ...child.aliases()]),
+    ),
+  );
+}
+
+export function buildProgram(): Command {
+  const program = new Command();
+  // Commander 12 has no native help groups, so render the top-level command
+  // list grouped (addHelpText below) and suppress commander's default flat
+  // list on the ROOT only - subcommand help (e.g. `dharta agent --help`) keeps
+  // commander's default rendering. `defaultHelp` is captured before the
+  // override so it supplies the unmodified list for subcommands.
+  const defaultHelp = program.createHelp();
+  program
+    .name("dharta")
+    .configureHelp({
+      visibleCommands: (cmd) => (cmd.parent === null ? [] : defaultHelp.visibleCommands(cmd)),
+    })
+    .description(
+      "Build, run, and deploy AI agents on dharta.ai - one tool from create to open.\n" +
+        "Agents are harness-native folders (Claude Code, OpenCode, DeepAgents, Goose, Codex CLI) plus dharta.toml; `dharta deploy` ships one selected folder.",
+    )
+    // Read from package.json so `--version` can never drift from the published
+    // package or the release pin-pair (the 0.3.0-vs-0.3.1 mismatch that shipped).
+    .version(
+      (JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as { version: string })
+        .version,
+    )
+    .addHelpText(
+      "after",
+      [
+        "",
+        "Agent lifecycle",
+        "  create     Scaffold a brand-new agent",
+        "  setup      Configure an agent here; write dharta.toml",
+        "  dev        Preview locally as a user would (hot reload)",
+        "  deploy     Deploy this agent folder",
+        "  open       Open the live hosted page",
+        "  status     Every agent here and its live release",
+        "",
+        "Operate",
+        "  sessions   Inspect an agent's sessions",
+        "  session    View one session transcript",
+        "  ps         Sessions active right now",
+        "  logs       Stream runtime logs",
+        "  files      Read a karta's workspace files",
+        "  send       One-shot message to a deployed agent",
+        "  rollback   Roll back to a previous release",
+        "  env        Environment bindings",
+        "",
+        "Manage",
+        "  agent      List and show your agents",
+        "  artifact   Designate durable workspace work product",
+        "",
+        "Account",
+        "  login      Sign in (device flow)",
+        "  whoami     Show the authenticated principal",
+        "  auth       Status, tokens, logout",
+        "  audit-log  Export audit events",
+        "  analytics  Usage and cost analytics",
+        "  keys       API keys",
+        "  model-keys BYOK provider credentials",
+        "  members    Organization members and invitations",
+        "  kartas     Durable Dharta identity, URLs, and ACLs",
+        "  api        Authenticated public API passthrough",
+        "  embed-keys Publishable widget keys",
+        "  caps       Spend caps and monthly budget",
+        "  appearance Agent appearance theme",
+        "  schedules  Recurring agent runs",
+        "  directories Agent-scoped kartas, users, sessions",
+        "  webhooks   Event delivery endpoints",
+        "",
+        "Utilities",
+        "  usage · doctor · update · completion",
+        "",
+        "Golden path:  dharta login -> create -> setup -> dev -> deploy -> open",
+        "Run `karta <command> --help` for details. Docs: https://docs.dharta.ai",
+      ].join("\n"),
+    )
+    .action(helpOnlyAction("dharta"));
+
+  program
+    .command("login")
+    .description(
+      "Sign in via your browser (device flow) and store the credential in ~/.dharta/config.toml",
+    )
+    .option("--with-token", "Read an API key from stdin instead (CI, air-gapped)")
+    .option("--base-url <url>", "Override the API base URL")
+    .option("--git-base-url <url>", "Override the git server base URL")
+    .option("--profile <name>", "Named profile (default: default)")
+    .action(
+      async (
+        opts: {
+          withToken?: boolean;
+          baseUrl?: string;
+          gitBaseUrl?: string;
+          profile?: string;
+        },
+        cmd: Command,
+      ) => {
+        if (opts.baseUrl !== undefined) normalizeHttpUrl(opts.baseUrl, "--base-url");
+        if (opts.gitBaseUrl !== undefined) normalizeHttpUrl(opts.gitBaseUrl, "--git-base-url");
+        if (opts.profile !== undefined) normalizeNonBlank(opts.profile, "--profile");
+        const json = isJson(cmd);
+        const result = await login({
+          baseUrl: opts.baseUrl,
+          gitBaseUrl: opts.gitBaseUrl,
+          profile: opts.profile,
+          apiKey: opts.withToken ? await readStdin() : undefined,
+          // In JSON mode the device-flow narration (code, approve URL)
+          // still has to reach the human - on stderr.
+          log: json ? logToStderr : undefined,
+        });
+        if (json) {
+          printJson(result);
+          return;
+        }
+        // keyName is "CLI - <hostname>" from the browser flow; show just
+        // the machine name. Token-flow keys keep their given name.
+        const identity = result.keyName.replace(/^CLI - /, "");
+        console.log(`✓ Logged in to ${result.organization.name} as ${identity}`);
+        console.log(
+          result.helperInstalled
+            ? "✓ git push dharta - enabled"
+            : "✗ git push dharta - not enabled (is git installed?)\n" +
+                '  git push will prompt: username "dharta", password = your API key',
+        );
+      },
+    );
+
+  const auth = program.command("auth").description("Manage CLI authentication.").action(helpOnlyAction("dharta auth"));
+  auth
+    .command("status")
+    .description("Show who you are, per profile.")
+    .action(async (_opts: unknown, cmd: Command) => {
+      if (isJson(cmd)) printJson(await authStatusData());
+      else console.log(await authStatus());
+    });
+  auth
+    .command("token")
+    .description("Print the active API token (for piping).")
+    .action(async (_opts: unknown, cmd: Command) => {
+      const token = await authToken();
+      if (isJson(cmd)) printJson({ token });
+      else console.log(token);
+    });
+  auth
+    .command("logout")
+    .description("Remove the stored credential (the key stays revocable on the dashboard).")
+    .option("--profile <name>", "Profile to remove (default: the default profile)")
+    .action(async (opts: { profile?: string }, cmd: Command) => {
+      if (isJson(cmd)) printJson(await authLogoutData(opts.profile));
+      else console.log(await authLogout(opts.profile));
+    });
+
+  program
+    .command("create [path]")
+    .description(
+      "Scaffold a brand-new agent in a supported harness format: a starter template + a default dharta.toml (deploy off). Configure delivery + the deploy gate afterward with `dharta setup`. Local only.",
+    )
+    .option("--name <name>", "agent name (default: the folder's slug)")
+    .option("--template <key>", "starter template (default: blank); see /agent_templates")
+    .addOption(choiceOption("--harness <type>", "harness format to scaffold", HARNESS_TYPES).default("claude-code"))
+    .option("--harness-version <version>", "optional harness version/range pin; omit for Dharta's curated default")
+    .action(
+      async (
+        pathArg: string | undefined,
+        opts: { name?: string; template?: string; harness?: string; harnessVersion?: string },
+        cmd: Command,
+      ) => {
+        validateCreateInput(pathArg, opts);
+        const json = isJson(cmd);
+        const result = await create(pathArg, {
+          name: opts.name,
+          template: opts.template,
+          harness: opts.harness,
+          harnessVersion: opts.harnessVersion,
+          baseUrl: await resolveBaseUrl(),
+          log: json ? logToStderr : (line: string) => console.log(line),
+        });
+        if (json) printJson(result);
+      },
+    );
+
+  program
+    .command("setup [path]")
+    .description(
+      "Configure an existing agent (name, deploy gate, persisted git/folder method, optional CI) and write a self-documenting dharta.toml. Destination-agnostic - does NOT deploy.",
+    )
+    .option("--name <name>", "agent name (default: the folder's slug)")
+    .option("--enable", "set deploy = true (allow this agent to deploy)")
+    .option("--disable", "set deploy = false (configured, not deployed)")
+    .addOption(
+      choiceOption(
+        "--method <m>",
+        "persisted transport: git | folder (`github` remains a compatibility alias for folder + --ci github)",
+        ["git", "folder", "github"],
+      ),
+    )
+    .addOption(choiceOption("--ci <provider>", "optional automation provider: github", ["github"]))
+    .option("--login", "also log in (device flow) - optional; setup works without it")
+    .option("-y, --yes", "non-interactive: take defaults, skip confirmations (including git init)")
+    .action(
+      async (
+        pathArg: string | undefined,
+        opts: { name?: string; enable?: boolean; disable?: boolean; method?: "git" | "github" | "folder"; ci?: "github"; login?: boolean; yes?: boolean },
+        cmd: Command,
+      ) => {
+        const json = isJson(cmd);
+        if (json && opts.login) {
+          throw new Error("--login is not supported with `dharta setup --json`. Run `dharta setup --json` first, then `dharta login`.");
+        }
+        const interactive = !json && !opts.yes && process.stdin.isTTY;
+        const rl = interactive
+          ? readline.createInterface({ input: process.stdin, output: process.stderr })
+          : null;
+        const ask = rl
+          ? (q: string) => new Promise<string>((resolve) => rl.question(q, resolve))
+          : undefined;
+        try {
+          const result = await setup(pathArg, {
+            name: opts.name,
+            enable: opts.enable,
+            disable: opts.disable,
+            method: opts.method,
+            ci: opts.ci,
+            yes: opts.yes,
+            ask,
+            log: json ? logToStderr : (line: string) => console.log(line),
+          });
+          if (json) printJson(result);
+          // Optional login (DEP-9): the bridge to `dharta deploy`. Never blocks setup.
+          await offerLogin({
+            force: opts.login,
+            ask,
+            log: json ? logToStderr : (line: string) => console.log(line),
+          });
+        } finally {
+          rl?.close();
+        }
+      },
+    );
+
+  // Git credential helper protocol endpoint, wired by `dharta login`
+  // (credential.<git host>.helper = !dharta git-credential). Hidden:
+  // humans never call it.
+  program
+    .command("git-credential <operation>", { hidden: true })
+    .description("Git credential helper (installed by `dharta login`).")
+    .action(async (operation: string, _opts: unknown, cmd: Command) => {
+      rejectJson(cmd, "dharta git-credential");
+      const chunks: Buffer[] = [];
+      for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk));
+      process.stdout.write(
+        await gitCredential(operation, Buffer.concat(chunks).toString("utf8")),
+      );
+    });
+
+  program
+    .command("audit-log")
+    .description("Export audit events (requires audit_log:export).")
+    .option("--csv", "Print CSV instead of a table")
+    .option("--action <action>", "Filter by audit action")
+    .option("--user-id <id>", "Filter by actor user id")
+    .option("--from <date>", "Filter from date (YYYY-MM-DD)")
+    .option("--to <date>", "Filter to date (YYYY-MM-DD)")
+    .option("--limit <n>", "Maximum rows to return")
+    .action(async (opts: {
+      csv?: boolean;
+      action?: string;
+      userId?: string;
+      from?: string;
+      to?: string;
+      limit?: string;
+    }, cmd: Command) => {
+      validateAuditLogInput(opts);
+      if (opts.csv && isJson(cmd)) {
+        throw new Error("Use either --csv or --json for audit-log, not both.");
+      }
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await auditLogData(ctx, opts));
+      else console.log(await auditLog(ctx, opts));
+    });
+
+  const analyticsCmd = program.command("analytics").description("Show usage and cost analytics.").action(helpOnlyAction("dharta analytics"));
+  const analyticsAction = (view: AnalyticsView) => async (
+    opts: { range?: string; groupBy?: string; from?: string; to?: string; limit?: string },
+    cmd: Command,
+  ) => {
+    normalizeAnalyticsOptions(view, opts);
+    const ctx = await buildContext();
+    if (isJson(cmd)) printJson(await analyticsData(ctx, view, opts));
+    else console.log(await analytics(ctx, view, opts));
+  };
+  for (const view of ["agents", "users", "instances", "sessions", "models"] as const) {
+    analyticsCmd
+      .command(view)
+      .description(`Show ${view} analytics.`)
+      .addOption(
+        choiceOption("--range <range>", "Window: 7d, 30d, or 90d", ENTITY_ANALYTICS_RANGES),
+      )
+      .option("--limit <n>", "Maximum rows")
+      .action(analyticsAction(view));
+  }
+  analyticsCmd
+    .command("cost")
+    .description("Show cost analytics.")
+    .addOption(
+      choiceOption("--range <range>", "Window: mtd, 7d, 30d, 90d, last_month, or custom", COST_ANALYTICS_RANGES),
+    )
+    .addOption(
+      choiceOption("--group-by <field>", "agent, karta, session, user, or model", COST_ANALYTICS_GROUPS),
+    )
+    .option("--from <date>", "Custom start date (YYYY-MM-DD; implies --range custom)")
+    .option("--to <date>", "Custom end date (YYYY-MM-DD; implies --range custom)")
+    .option("--limit <n>", "Maximum rows")
+    .action(analyticsAction("cost"));
+
+  program
+    .command("whoami")
+    .description("Show the currently authenticated principal.")
+    .action(async (_opts: unknown, cmd: Command) => {
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await whoamiData(ctx));
+      else console.log(await whoami(ctx));
+    });
+
+  program
+    .command("api [method] [path]")
+    .description("Call an allowlisted public JSON API endpoint with the active profile.")
+    .option("-F, --field <key=value>", "Add a JSON-coerced field to the request body", collect, [])
+    .option("-f, --raw-field <key=value>", "Add a string field to the request body", collect, [])
+    .option("-H, --header <name:value>", "Add a safe request header", collect, [])
+    .option("--body-stdin", "Read the raw request body from stdin")
+    .action(async (method: string | undefined, path: string | undefined, opts: {
+      field?: string[];
+      rawField?: string[];
+      header?: string[];
+      bodyStdin?: boolean;
+    }, cmd: Command) => {
+      validateApiRequest(method, path, opts);
+      const preparedOpts = await prepareApiOptions(opts);
+      const ctx = await buildContext();
+      const result = await apiCmd(ctx, method, path, preparedOpts);
+      if (isJson(cmd)) printJson(result.body);
+      else {
+        const output = formatApiResult(result);
+        if (output) console.log(output);
+      }
+    });
+
+  const keys = program.command("keys").description("Manage API keys.").action(helpOnlyAction("dharta keys"));
+  keys
+    .command("list")
+    .description("List API keys for the current organization (requires keys:read or keys:write).")
+    .action(async (_opts: unknown, cmd: Command) => {
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await keysListData(ctx));
+      else console.log(await keysList(ctx));
+    });
+  keys
+    .command("create <name>")
+    .description("Mint a new API key.")
+    .addOption(
+      choiceListOption("--scope <scope...>", "operation scopes", CLI_API_KEY_SCOPES)
+        .default([]),
+    )
+    .option("--expires-at <iso>", "Expiry timestamp; required within 90 days for sensitive scopes")
+    .action(async (name: string, opts: { scope: ApiKeyScope[]; expiresAt?: string }, cmd: Command) => {
+      validateKeysCreateInput(name, opts.scope, { expiresAt: opts.expiresAt });
+      const ctx = await buildContext();
+      const keyOpts = { expiresAt: opts.expiresAt };
+      if (isJson(cmd)) printJson(await keysCreateData(ctx, name, opts.scope, keyOpts));
+      else console.log(await keysCreate(ctx, name, opts.scope, keyOpts));
+    });
+  keys
+    .command("rename <id> <name>")
+    .description("Rename an API key by id.")
+    .action(async (id: string, name: string, _opts: unknown, cmd: Command) => {
+      normalizeNonBlank(id, "API key id");
+      normalizeNonBlank(name, "API key name");
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await keysRenameData(ctx, id, name));
+      else console.log(await keysRename(ctx, id, name));
+    });
+  keys
+    .command("revoke <id>")
+    .description("Revoke an API key by id.")
+    .action(async (id: string, _opts: unknown, cmd: Command) => {
+      normalizeNonBlank(id, "API key id");
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await keysRevokeData(ctx, id));
+      else console.log(await keysRevoke(ctx, id));
+    });
+
+  const modelKeys = program.command("model-keys").description("Manage BYOK provider credentials.").action(helpOnlyAction("dharta model-keys"));
+  modelKeys
+    .command("list")
+    .description("List model provider credentials.")
+    .action(async (_opts: unknown, cmd: Command) => {
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await modelKeysListData(ctx));
+      else console.log(await modelKeysList(ctx));
+    });
+  modelKeys
+    .command("create")
+    .description("Store an encrypted model provider credential.")
+    .addArgument(choiceArgument("<provider>", "provider", ["anthropic", "openai", "bedrock", "vertex", "openrouter", "xai", "google"]))
+    .argument("<name>", "connector name")
+    .option("--key <plaintext>", "Provider API key plaintext")
+    .option("--key-stdin", "Read provider API key plaintext from stdin")
+    .addOption(choiceOption("--auth-type <type>", "api_key or oauth_subscription", MODEL_KEY_AUTH_TYPES))
+    .option("--endpoint-url <url>", "Provider endpoint URL override")
+    .addOption(choiceOption("--api-format <format>", "Explicit provider API format", MODEL_API_FORMATS))
+    .action(async (provider: ModelKeyProvider, name: string, opts: {
+      key?: string;
+      keyStdin?: boolean;
+      authType?: string;
+      endpointUrl?: string;
+      apiFormat?: string;
+    }, cmd: Command) => {
+      validateModelKeysCreateOptions(provider, name, opts);
+      const preparedOpts = await prepareModelKeysCreateOptions(provider, name, opts);
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await modelKeysCreateData(ctx, provider, name, preparedOpts));
+      else console.log(await modelKeysCreate(ctx, provider, name, preparedOpts));
+    });
+  modelKeys
+    .command("revoke <id>")
+    .description("Revoke a model provider credential.")
+    .action(async (id: string, _opts: unknown, cmd: Command) => {
+      validateModelKeyId(id);
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await modelKeysRevokeData(ctx, id));
+      else console.log(await modelKeysRevoke(ctx, id));
+    });
+
+  const members = program.command("members").description("Manage organization members.").action(helpOnlyAction("dharta members"));
+  members
+    .command("list")
+    .description("List members and pending invitations.")
+    .action(async (_opts: unknown, cmd: Command) => {
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await membersListData(ctx));
+      else console.log(await membersList(ctx));
+    });
+  members
+    .command("invite <email>")
+    .description("Invite a member.")
+    .addOption(choiceOption("--role <role>", "owner, admin, developer, billing, or viewer", MEMBER_ROLES))
+    .action(async (email: string, opts: { role?: string }, cmd: Command) => {
+      if (opts.role === undefined) {
+        throw new Error("--role is required. Usage: dharta members invite <email> --role <role>");
+      }
+      validateMembersInviteInput(email);
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await membersInviteData(ctx, email, opts.role));
+      else console.log(await membersInvite(ctx, email, opts.role));
+    });
+  members
+    .command("set-role <id>")
+    .description("Change a member role.")
+    .addOption(choiceOption("--role <role>", "owner, admin, developer, billing, or viewer", MEMBER_ROLES))
+    .action(async (id: string, opts: { role?: string }, cmd: Command) => {
+      if (opts.role === undefined) {
+        throw new Error("--role is required. Usage: dharta members set-role <id> --role <role>");
+      }
+      parsePositiveInteger(id, "member id");
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await membersSetRoleData(ctx, id, opts.role));
+      else console.log(await membersSetRole(ctx, id, opts.role));
+    });
+  members
+    .command("remove <id>")
+    .description("Remove a member.")
+    .action(async (id: string, _opts: unknown, cmd: Command) => {
+      parsePositiveInteger(id, "member id");
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await membersRemoveData(ctx, id));
+      else console.log(await membersRemove(ctx, id));
+    });
+
+  const kartas = program.command("kartas").description("Manage durable kartas and virtual employees.").action(helpOnlyAction("dharta kartas"));
+  kartas
+    .command("create <name>")
+    .description("Create a named karta with a stable URL and managed access.")
+    .option("--agent <slug>", "Owning agent slug")
+    .option("--slug <slug>", "Vanity slug beneath the agent URL")
+    .addOption(choiceOption("--access <audience>", "members (specific people), anonymous (anyone with link), or off", DHARTA_ACCESS_AUDIENCES).default("members"))
+    .option("--member <email>", "Organization user to add; repeat for more", collect, [])
+    .addOption(choiceOption("--member-role <role>", "Role for people added with --member", DHARTA_MEMBER_ROLES).default("participant"))
+    .action(async (name: string, opts: { agent?: string; slug?: string; access?: string; member?: string[]; memberRole?: string }, cmd: Command) => {
+      const options = { ...opts, members: opts.member };
+      validateKartaCreateOptions(name, options);
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await kartasCreateData(ctx, name, options));
+      else console.log(await kartasCreate(ctx, name, options));
+    });
+  kartas
+    .command("list")
+    .description("List durable kartas and their stable URLs.")
+    .option("--agent <slug>", "Limit results to one owning agent")
+    .option("--named", "Show only kartas with a name and vanity slug")
+    .option("--archived", "Show archived kartas instead of active ones")
+    .action(async (opts: { agent?: string; named?: boolean; archived?: boolean }, cmd: Command) => {
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await kartasListData(ctx, opts));
+      else console.log(await kartasList(ctx, opts));
+    });
+  kartas
+    .command("show <id>")
+    .description("Show one karta, its stable URL, and how access is managed.")
+    .action(async (id: string, _opts: unknown, cmd: Command) => {
+      normalizeNonBlank(id, "dharta id");
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await kartasShowData(ctx, id));
+      else console.log(await kartasShow(ctx, id));
+    });
+  kartas
+    .command("name <id>")
+    .description("Give an existing karta a name and vanity slug without changing access.")
+    .option("--name <name>", "Display name")
+    .option("--slug <slug>", "Vanity slug beneath the agent URL")
+    .action(async (id: string, opts: { name?: string; slug?: string }, cmd: Command) => {
+      validateKartaNameOptions(opts);
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await kartasNameData(ctx, id, opts));
+      else console.log(await kartasName(ctx, id, opts));
+    });
+  kartas
+    .command("configure <id>")
+    .description("Set a karta name, vanity slug, and stable URL access.")
+    .option("--name <name>", "Display name")
+    .option("--slug <slug>", "Vanity slug beneath the agent URL")
+    .addOption(choiceOption("--access <audience>", "members (specific people), anonymous (anyone with link), or off", DHARTA_ACCESS_AUDIENCES))
+    .action(async (id: string, opts: { name?: string; slug?: string; access?: string }, cmd: Command) => {
+      validateKartaConfigureOptions(opts);
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await kartasConfigureData(ctx, id, opts));
+      else console.log(await kartasConfigure(ctx, id, opts));
+    });
+  kartas
+    .command("archive <id>")
+    .alias("delete")
+    .description("Retire a karta (reversible; its files and history are kept).")
+    .action(async (id: string, _opts: unknown, cmd: Command) => {
+      normalizeNonBlank(id, "dharta id");
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await kartasArchiveData(ctx, id));
+      else console.log(await kartasArchive(ctx, id));
+    });
+  kartas
+    .command("restore <id>")
+    .description("Bring an archived karta back, with its files and history.")
+    .action(async (id: string, _opts: unknown, cmd: Command) => {
+      normalizeNonBlank(id, "dharta id");
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await kartasRestoreData(ctx, id));
+      else console.log(await kartasRestore(ctx, id));
+    });
+  const kartaEnv = kartas
+    .command("env")
+    .description("Configure ONE karta's environment (its own credentials and settings).")
+    .action(helpOnlyAction("dharta kartas env"));
+  kartaEnv
+    .command("list <agent> <karta>")
+    .description("List a karta's environment variables. Secret values are never shown.")
+    .action(async (agent: string, karta: string, _opts: unknown, cmd: Command) => {
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await kartaEnvListData(ctx, agent, karta));
+      else console.log(await kartaEnvList(ctx, agent, karta));
+    });
+  kartaEnv
+    .command("set <agent> <karta> <name> <value>")
+    .description("Set one variable on one dharta.")
+    .option("--plain", "Store as a readable value (default: secret)")
+    .action(async (agent: string, karta: string, name: string, value: string, opts: { plain?: boolean }, cmd: Command) => {
+      const ctx = await buildContext();
+      const options = { secret: opts.plain ? false : undefined };
+      if (isJson(cmd)) printJson(await kartaEnvSetData(ctx, agent, karta, name, value, options));
+      else console.log(await kartaEnvSet(ctx, agent, karta, name, value, options));
+    });
+  kartaEnv
+    .command("unset <agent> <karta> <name>")
+    .description("Remove one variable from one dharta.")
+    .action(async (agent: string, karta: string, name: string, _opts: unknown, cmd: Command) => {
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await kartaEnvUnsetData(ctx, agent, karta, name));
+      else console.log(await kartaEnvUnset(ctx, agent, karta, name));
+    });
+  kartas
+    .command("grant <id> <email>")
+    .description("Add an organization user to a karta with managed access.")
+    .addOption(choiceOption("--role <role>", "viewer, participant, or manager", DHARTA_MEMBER_ROLES).default("participant"))
+    .action(async (id: string, email: string, opts: { role: string }, cmd: Command) => {
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await kartaMembersGrantData(ctx, id, email, opts.role));
+      else console.log(await kartaMembersGrant(ctx, id, email, opts.role));
+    });
+  kartas
+    .command("set-role <id> <membership-id>")
+    .description("Change a person's role on a karta with managed access.")
+    .addOption(choiceOption("--role <role>", "viewer, participant, or manager", DHARTA_MEMBER_ROLES))
+    .action(async (id: string, membershipId: string, opts: { role?: string }, cmd: Command) => {
+      if (opts.role === undefined) {
+        throw new Error("--role is required. Usage: dharta kartas set-role <id> <membership-id> --role <role>");
+      }
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await kartaMembersSetRoleData(ctx, id, membershipId, opts.role));
+      else console.log(await kartaMembersSetRole(ctx, id, membershipId, opts.role));
+    });
+  kartas
+    .command("revoke <id> <membership-id>")
+    .description("Remove a person's access to a dharta.")
+    .action(async (id: string, membershipId: string, _opts: unknown, cmd: Command) => {
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await kartaMembersRevokeData(ctx, id, membershipId));
+      else console.log(await kartaMembersRevoke(ctx, id, membershipId));
+    });
+
+  const embedKeys = program.command("embed-keys").description("Manage publishable widget embed keys.").action(helpOnlyAction("dharta embed-keys"));
+  const embedKeyOpts = (cmd: ReturnType<typeof embedKeys.command>) =>
+    cmd
+      .option("-a, --agent <slug>", "Agent slug (default: the agent in this folder)")
+      .option("-p, --project <slug>", "Alias of --agent")
+      .option("--dir <dir>", "Agent directory (default: current directory)");
+  embedKeyOpts(embedKeys.command("list"))
+    .description("List publishable embed keys for an agent.")
+    .action(async (_opts: { agent?: string; project?: string; dir?: string }, cmd: Command) => {
+      const opts = commandOpts<{ agent?: string; project?: string; dir?: string }>(cmd);
+      const resolved = await resolveAgentOptions(opts);
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await embedKeysListData(ctx, resolved));
+      else console.log(await embedKeysList(ctx, resolved));
+    });
+  embedKeyOpts(embedKeys.command("create <name>"))
+    .description("Create a publishable embed key and reveal its secret once.")
+    .option("--origin <origin...>", "Allowed browser origin; repeat or comma-separate")
+    .action(async (name: string, _opts: { agent?: string; project?: string; dir?: string; origin?: string[] }, cmd: Command) => {
+      const opts = commandOpts<{ agent?: string; project?: string; dir?: string; origin?: string[] }>(cmd);
+      const origins = opts.origin === undefined ? undefined : parseOrigins(opts.origin);
+      validateEmbedKeysCreateInput(name, { origins });
+      const resolved = await resolveAgentOptions({ ...opts, origins });
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await embedKeysCreateData(ctx, name, resolved));
+      else console.log(await embedKeysCreate(ctx, name, resolved));
+    });
+  embedKeyOpts(embedKeys.command("rotate <id>"))
+    .description("Rotate an embed key and reveal the replacement secret once.")
+    .action(async (id: string, _opts: { agent?: string; project?: string; dir?: string }, cmd: Command) => {
+      const opts = commandOpts<{ agent?: string; project?: string; dir?: string }>(cmd);
+      normalizeNonBlank(id, "Embed key id");
+      const resolved = await resolveAgentOptions(opts);
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await embedKeysRotateData(ctx, id, resolved));
+      else console.log(await embedKeysRotate(ctx, id, resolved));
+    });
+  for (const action of ["enable", "disable"] as const) {
+    embedKeyOpts(embedKeys.command(`${action} <id>`))
+      .description(`${action === "enable" ? "Enable" : "Disable"} an embed key.`)
+      .action(async (id: string, _opts: { agent?: string; project?: string; dir?: string }, cmd: Command) => {
+        const opts = commandOpts<{ agent?: string; project?: string; dir?: string }>(cmd);
+        normalizeNonBlank(id, "Embed key id");
+        const resolved = await resolveAgentOptions(opts);
+        const ctx = await buildContext();
+        if (isJson(cmd)) printJson(await embedKeysToggleData(ctx, id, action, resolved));
+        else console.log(await embedKeysToggle(ctx, id, action, resolved));
+      });
+  }
+  embedKeyOpts(embedKeys.command("revoke <id>"))
+    .description("Revoke an embed key permanently.")
+    .action(async (id: string, _opts: { agent?: string; project?: string; dir?: string }, cmd: Command) => {
+      const opts = commandOpts<{ agent?: string; project?: string; dir?: string }>(cmd);
+      normalizeNonBlank(id, "Embed key id");
+      const resolved = await resolveAgentOptions(opts);
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await embedKeysRevokeData(ctx, id, resolved));
+      else console.log(await embedKeysRevoke(ctx, id, resolved));
+    });
+  embedKeyOpts(embedKeys.command("enable-identity <id>"))
+    .description("Enable verified widget identity and reveal the signing secret once (re-run to rotate it).")
+    .action(async (id: string, _opts: { agent?: string; project?: string; dir?: string }, cmd: Command) => {
+      const opts = commandOpts<{ agent?: string; project?: string; dir?: string }>(cmd);
+      normalizeNonBlank(id, "Embed key id");
+      const resolved = await resolveAgentOptions(opts);
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await embedKeysSetIdentityData(ctx, id, resolved));
+      else console.log(await embedKeysSetIdentity(ctx, id, resolved));
+    });
+  embedKeyOpts(embedKeys.command("disable-identity <id>"))
+    .description("Disable verified widget identity for an embed key.")
+    .action(async (id: string, _opts: { agent?: string; project?: string; dir?: string }, cmd: Command) => {
+      const opts = commandOpts<{ agent?: string; project?: string; dir?: string }>(cmd);
+      normalizeNonBlank(id, "Embed key id");
+      const resolved = await resolveAgentOptions(opts);
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await embedKeysClearIdentityData(ctx, id, resolved));
+      else console.log(await embedKeysClearIdentity(ctx, id, resolved));
+    });
+
+  const caps = program.command("caps").description("Manage spend caps and the monthly budget.").action(helpOnlyAction("dharta caps"));
+  const addBudgetSetCommand = (cmd: Command, description = "Set the monthly budget amount.") =>
+    cmd
+      .description(description)
+      .option("--amount <dollars>", "Budget amount in dollars")
+      .option("--hard-stop", "Stop usage when the budget is reached")
+      .option("--soft", "Track spend and alerts without stopping usage")
+      .option("--enable-alerts", "Enable threshold alerts")
+      .option("--disable-alerts", "Disable threshold alerts")
+      .option("--alert-threshold <percent>", "Alert threshold percent")
+      .option("--recipient-user-id <id...>", "Additional alert recipient user id")
+      .action(
+        async (
+          opts: {
+            amount?: string;
+            hardStop?: boolean;
+            soft?: boolean;
+            enableAlerts?: boolean;
+            disableAlerts?: boolean;
+            alertThreshold?: string;
+            recipientUserId?: string[];
+          },
+          cmd: Command,
+        ) => {
+          validateBudgetSetOptions(opts);
+          const ctx = await buildContext();
+          if (isJson(cmd)) printJson(await capsBudgetSetData(ctx, opts));
+          else console.log(await capsBudgetSet(ctx, opts));
+        },
+      );
+  const capsBudgetCmd = caps
+    .command("budget")
+    .description("Show the monthly budget and current spend.")
+    .action(async (_opts: unknown, cmd: Command) => {
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await capsBudgetData(ctx));
+      else console.log(await capsBudget(ctx));
+    });
+  addBudgetSetCommand(capsBudgetCmd.command("set"));
+  addBudgetSetCommand(caps.command("set"), "Set the monthly budget amount (alias of `dharta caps budget set`).");
+  caps
+    .command("instance <id>")
+    .description("Show the spend cap for a durable karta.")
+    .action(async (id: string, _opts: unknown, cmd: Command) => {
+      normalizeNonBlank(id, "instance id");
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await capsInstanceData(ctx, id));
+      else console.log(await capsInstance(ctx, id));
+    });
+  caps
+    .command("instance-set <id>")
+    .description("Set or clear a durable karta spend cap.")
+    .option("--amount <dollars>", "Cap amount in dollars")
+    .option("--clear", "Clear the cap")
+    .action(async (id: string, opts: { amount?: string; clear?: boolean }, cmd: Command) => {
+      normalizeNonBlank(id, "instance id");
+      validateCapSetOptions(opts);
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await capsInstanceSetData(ctx, id, opts));
+      else console.log(await capsInstanceSet(ctx, id, opts));
+    });
+  caps
+    .command("end-user <id>")
+    .description("Show the global spend cap for a verified end-user.")
+    .action(async (id: string, _opts: unknown, cmd: Command) => {
+      normalizeNonBlank(id, "end-user id");
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await capsEndUserData(ctx, id));
+      else console.log(await capsEndUser(ctx, id));
+    });
+  caps
+    .command("end-user-set <id>")
+    .description("Set or clear the global spend cap for a verified end-user.")
+    .option("--amount <dollars>", "Cap amount in dollars")
+    .option("--clear", "Clear the cap")
+    .action(async (id: string, opts: { amount?: string; clear?: boolean }, cmd: Command) => {
+      normalizeNonBlank(id, "end-user id");
+      validateCapSetOptions(opts);
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await capsEndUserSetData(ctx, id, opts));
+      else console.log(await capsEndUserSet(ctx, id, opts));
+    });
+  caps
+    .command("seat <instance> <end-user-id>")
+    .description("Show the per-seat spend cap for an end-user on a durable karta.")
+    .action(async (instance: string, endUserId: string, _opts: unknown, cmd: Command) => {
+      normalizeNonBlank(instance, "instance id");
+      normalizeNonBlank(endUserId, "end-user id");
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await capsSeatData(ctx, instance, endUserId));
+      else console.log(await capsSeat(ctx, instance, endUserId));
+    });
+  caps
+    .command("seat-set <instance> <end-user-id>")
+    .description("Set or clear the per-seat spend cap for an end-user on a durable karta.")
+    .option("--amount <dollars>", "Cap amount in dollars")
+    .option("--clear", "Clear the cap")
+    .action(async (instance: string, endUserId: string, opts: { amount?: string; clear?: boolean }, cmd: Command) => {
+      normalizeNonBlank(instance, "instance id");
+      normalizeNonBlank(endUserId, "end-user id");
+      validateCapSetOptions(opts);
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await capsSeatSetData(ctx, instance, endUserId, opts));
+      else console.log(await capsSeatSet(ctx, instance, endUserId, opts));
+    });
+
+  const appearance = program.command("appearance").description("Get or update an agent's appearance theme.").action(helpOnlyAction("dharta appearance"));
+  const appearanceOpts = (cmd: ReturnType<typeof appearance.command>) =>
+    cmd
+      .option("-a, --agent <slug>", "Agent slug (default: the agent in this folder)")
+      .option("-p, --project <slug>", "Alias of --agent")
+      .option("--dir <dir>", "Agent directory (default: current directory)");
+  appearanceOpts(appearance.command("get"))
+    .description("Print the stored appearance JSON for an agent.")
+    .action(async (_opts: { agent?: string; project?: string; dir?: string }, cmd: Command) => {
+      const opts = commandOpts<{ agent?: string; project?: string; dir?: string }>(cmd);
+      const resolved = await resolveAgentOptions(opts);
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await appearanceGetData(ctx, resolved));
+      else console.log(await appearanceGet(ctx, resolved));
+    });
+  appearanceOpts(appearance.command("set"))
+    .description("Merge appearance JSON from a local file.")
+    .option("--file <file>", "JSON file containing appearance tokens")
+    .action(async (_opts: { agent?: string; project?: string; dir?: string; file?: string }, cmd: Command) => {
+      const opts = commandOpts<{ agent?: string; project?: string; dir?: string; file?: string }>(cmd);
+      await validateAppearanceSetInput(opts);
+      const resolved = await resolveAgentOptions(opts);
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await appearanceSetData(ctx, resolved));
+      else console.log(await appearanceSet(ctx, resolved));
+    });
+
+  const schedules = program.command("schedules").description("Manage recurring agent runs.").action(helpOnlyAction("dharta schedules"));
+  const scheduleOpts = (cmd: ReturnType<typeof schedules.command>) =>
+    cmd
+      .option("-a, --agent <slug>", "Agent slug (default: the agent in this folder)")
+      .option("-p, --project <slug>", "Alias of --agent")
+      .option("--dir <dir>", "Agent directory (default: current directory)");
+  scheduleOpts(schedules.command("list"))
+    .description("List recurring runs for an agent.")
+    .action(async (_opts: { agent?: string; project?: string; dir?: string }, cmd: Command) => {
+      const opts = commandOpts<{ agent?: string; project?: string; dir?: string }>(cmd);
+      const resolved = await resolveAgentOptions(opts);
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await schedulesListData(ctx, resolved));
+      else console.log(await schedulesList(ctx, resolved));
+    });
+  scheduleOpts(schedules.command("create"))
+    .description("Create a recurring run.")
+    .option("--cron <expr>", "Cron expression")
+    .option("--timezone <tz>", "Timezone (default: UTC)")
+    .option("--message <text>", "Initial message")
+    .option("--budget <dollars>", "Run budget in dollars")
+    .option("--budget-cents <cents>", "Run budget in integer cents")
+    .option("--release-version <version>", "Pin runs to a release version")
+    .option("--end-user-id <id>", "End-user id to run as")
+    .option("--run-now", "Queue one run immediately after creating the recurring run")
+    .action(async (
+      _opts: {
+        agent?: string;
+        project?: string;
+        dir?: string;
+        cron?: string;
+        timezone?: string;
+        message?: string;
+        budget?: string;
+        budgetCents?: string;
+        releaseVersion?: string;
+        endUserId?: string;
+        runNow?: boolean;
+      },
+      cmd: Command,
+    ) => {
+      const opts = commandOpts<{
+        agent?: string;
+        project?: string;
+        dir?: string;
+        cron?: string;
+        timezone?: string;
+        message?: string;
+        budget?: string;
+        budgetCents?: string;
+        releaseVersion?: string;
+        endUserId?: string;
+        runNow?: boolean;
+      }>(cmd);
+      validateSchedulesCreateInput(opts);
+      const resolved = await resolveAgentOptions(opts);
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await schedulesCreateData(ctx, resolved));
+      else console.log(await schedulesCreate(ctx, resolved));
+    });
+  for (const action of ["pause", "resume", "run"] as const) {
+    scheduleOpts(schedules.command(`${action} <id>`))
+      .description(`${action === "run" ? "Queue" : action === "pause" ? "Pause" : "Resume"} a recurring run.`)
+      .action(async (id: string, _opts: { agent?: string; project?: string; dir?: string }, cmd: Command) => {
+        const opts = commandOpts<{ agent?: string; project?: string; dir?: string }>(cmd);
+        parsePositiveInteger(normalizeNonBlank(id, "Schedule id"), "Schedule id");
+        const resolved = await resolveAgentOptions(opts);
+        const ctx = await buildContext();
+        if (isJson(cmd)) printJson(await schedulesActionData(ctx, id, action, resolved));
+        else console.log(await schedulesAction(ctx, id, action, resolved));
+      });
+  }
+  scheduleOpts(schedules.command("delete <id>").alias("rm"))
+    .description("Delete a recurring run.")
+    .action(async (id: string, _opts: { agent?: string; project?: string; dir?: string }, cmd: Command) => {
+      const opts = commandOpts<{ agent?: string; project?: string; dir?: string }>(cmd);
+      parsePositiveInteger(normalizeNonBlank(id, "Schedule id"), "Schedule id");
+      const resolved = await resolveAgentOptions(opts);
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await schedulesDeleteData(ctx, id, resolved));
+      else console.log(await schedulesDelete(ctx, id, resolved));
+    });
+
+  const directories = program.command("directories").description("Read agent-scoped kartas, users, and sessions.").action(helpOnlyAction("dharta directories"));
+  const directoryOpts = (cmd: ReturnType<typeof directories.command>) =>
+    cmd
+      .option("-a, --agent <slug>", "Agent slug (default: the agent in this folder)")
+      .option("-p, --project <slug>", "Alias of --agent")
+      .option("--dir <dir>", "Agent directory (default: current directory)")
+      .option("--limit <n>", "Maximum rows to return");
+  directoryOpts(directories.command("instances"))
+    .description("List durable kartas for an agent.")
+    .action(async (_opts: DirectorySelectorOptions, cmd: Command) => {
+      const opts = commandOpts<DirectorySelectorOptions>(cmd);
+      validateDirectoryOptions(opts);
+      const resolved = await resolveAgentOptions(opts);
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await directoryInstancesData(ctx, resolved));
+      else console.log(await directoryInstances(ctx, resolved));
+    });
+  directoryOpts(directories.command("end-users").alias("users"))
+    .description("List verified users for an agent.")
+    .action(async (_opts: DirectorySelectorOptions, cmd: Command) => {
+      const opts = commandOpts<DirectorySelectorOptions>(cmd);
+      validateDirectoryOptions(opts);
+      const resolved = await resolveAgentOptions(opts);
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await directoryEndUsersData(ctx, resolved));
+      else console.log(await directoryEndUsers(ctx, resolved));
+    });
+  directoryOpts(directories.command("sessions"))
+    .description("List sessions for an agent.")
+    .action(async (_opts: DirectorySelectorOptions, cmd: Command) => {
+      const opts = commandOpts<DirectorySelectorOptions>(cmd);
+      validateDirectoryOptions(opts);
+      const resolved = await resolveAgentOptions(opts);
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await directorySessionsData(ctx, resolved));
+      else console.log(await directorySessions(ctx, resolved));
+    });
+
+  const webhooks = program.command("webhooks").description("Manage webhook endpoints.").action(helpOnlyAction("dharta webhooks"));
+  webhooks
+    .command("list")
+    .description("List webhook endpoints.")
+    .action(async (_opts: unknown, cmd: Command) => {
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await webhooksListData(ctx));
+      else console.log(await webhooksList(ctx));
+    });
+  webhooks
+    .command("create <name> <url>")
+    .description("Create a webhook endpoint and reveal its signing secret once.")
+    .option("--event <event...>", "Subscribed event type; repeat or comma-separate")
+    .action(async (name: string, url: string, opts: { event?: string[] }, cmd: Command) => {
+      const resolved = { event: parseEvents(opts.event) };
+      validateWebhooksCreateInput(name, url, resolved);
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await webhooksCreateData(ctx, name, url, resolved));
+      else console.log(await webhooksCreate(ctx, name, url, resolved));
+    });
+  webhooks
+    .command("update <id>")
+    .description("Update a webhook endpoint.")
+    .option("--name <name>", "Endpoint name")
+    .option("--url <url>", "Destination URL")
+    .option("--event <event...>", "Subscribed event type; repeat or comma-separate")
+    .action(async (id: string, opts: { name?: string; url?: string; event?: string[] }, cmd: Command) => {
+      const resolved = { name: opts.name, url: opts.url, event: opts.event ? parseEvents(opts.event) : undefined };
+      validateWebhooksUpdateInput(id, resolved);
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await webhooksUpdateData(ctx, id, resolved));
+      else console.log(await webhooksUpdate(ctx, id, resolved));
+    });
+  webhooks
+    .command("enable <id>")
+    .description("Re-enable a disabled webhook endpoint.")
+    .action(async (id: string, _opts: unknown, cmd: Command) => {
+      normalizeNonBlank(id, "Webhook endpoint id");
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await webhooksEnableData(ctx, id));
+      else console.log(await webhooksEnable(ctx, id));
+    });
+  webhooks
+    .command("delete <id>")
+    .alias("rm")
+    .description("Delete a webhook endpoint.")
+    .action(async (id: string, _opts: unknown, cmd: Command) => {
+      normalizeNonBlank(id, "Webhook endpoint id");
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await webhooksDeleteData(ctx, id));
+      else console.log(await webhooksDelete(ctx, id));
+    });
+
+  program
+    .command("open [target]")
+    .description(
+      `Open an agent page or browser handoff target. Targets: ${OPEN_TARGETS_HELP}.`,
+    )
+    .option("-a, --agent <slug>", "Agent slug (default: the agent in this folder)").option("-p, --project <slug>", "Alias of --agent")
+    .option("--dir <dir>", "Agent directory (default: current directory)")
+    .action(
+      async (
+        target: string | undefined,
+        opts: { agent?: string; project?: string; dir?: string },
+        cmd: Command,
+      ) => {
+        const normalizedTarget = normalizeOpenTarget(target);
+        validateOpenTarget(normalizedTarget);
+        if (isHandoffTarget(normalizedTarget)) {
+          const baseUrl = await resolveBaseUrl();
+          if (isJson(cmd)) printJson(openHandoffData(baseUrl, normalizedTarget));
+          else console.log(await openHandoff(baseUrl, normalizedTarget));
+          return;
+        }
+        const needsAgent = normalizedTarget !== "console" ||
+          opts.agent !== undefined ||
+          opts.project !== undefined ||
+          opts.dir !== undefined;
+        const resolved = needsAgent ? await resolveAgentOptions(opts) : opts;
+        const ctx = await buildContext();
+        // --json prints the URL object and does NOT open the browser.
+        if (isJson(cmd)) printJson(await openData(ctx, normalizedTarget, resolved));
+        else console.log(await openCmd(ctx, normalizedTarget, resolved));
+      },
+    );
+
+  program
+    .command("dev [path]")
+    .description(
+      "Preview your agent locally the way a USER experiences it - behind the same consumer session API production serves (widget parity), with hot reload. Distinct from running `claude` in the folder, which is authoring. [path] (or cwd) selects the agent; in a multi-agent repo it picks the sole one or asks.",
+    )
+    .option("--dir <dir>", "Agent directory (alias for [path]; default: current directory)")
+    .option("-m, --message <text>", "Send one message and exit")
+    .option("--user <id>", "Simulate a verified end user (per-user memory behavior)")
+    .option("--port <port>", "Serve the local agent API on a stable port (for widgets/frontends)")
+    .option("--verbose", "Stream agent-runtime output and parity details")
+    .option("--release <vN>", "Run the exact built tree prod serves (audited archive pull)")
+    .addOption(choiceOption("--env <mode>", "Bind prod env vars instead of .env", ["remote"]))
+    .option("--include-secrets", "With --env remote: fetch secret values (requires env:secrets:read; audited)")
+    .option("-a, --agent <slug>", "Agent for --release/--env (default: the agent here)").option("-p, --project <slug>", "Alias of --agent")
+    .action(
+      async (
+        pathArg: string | undefined,
+        opts: {
+          dir?: string;
+          message?: string;
+          user?: string;
+          port?: string;
+          verbose?: boolean;
+          release?: string;
+          env?: string;
+          includeSecrets?: boolean;
+          agent?: string;
+          project?: string;
+        },
+        cmd: Command,
+      ) => {
+        rejectJson(cmd, "dharta dev");
+        if (pathArg !== undefined && opts.dir !== undefined) {
+          throw new Error("Use either [path] or --dir, not both.");
+        }
+        const dir = pathArg !== undefined
+          ? normalizeNonBlank(pathArg, "path")
+          : opts.dir !== undefined
+            ? normalizeNonBlank(opts.dir, "--dir")
+            : undefined;
+        if (opts.release !== undefined) parseReleaseVersion(opts.release, "--release");
+        if (opts.includeSecrets && opts.env !== "remote") {
+          throw new Error("--include-secrets requires --env remote.");
+        }
+        validateAgentSelectorOptions({ agent: opts.agent, project: opts.project });
+        await devCmd({
+          dir,
+          message: opts.message,
+          user: opts.user,
+          verbose: opts.verbose,
+          port: opts.port ? parsePort(opts.port) : undefined,
+          release: opts.release,
+          envRemote: opts.env === "remote",
+          includeSecrets: opts.includeSecrets,
+          project: opts.agent ?? opts.project,
+        });
+      },
+    );
+
+  registerArtifactCommands(program);
+
+  const sessionsOpts = <T extends Command>(cmd: T): T =>
+    cmd
+      .option("-a, --agent <slug>", "Agent slug (default: the agent in this folder)")
+      .option("-p, --project <slug>", "Alias of --agent")
+      .option("--dir <dir>", "Agent directory (default: current directory)");
+  const sessionsListOpts = <T extends Command>(cmd: T): T =>
+    sessionsOpts(cmd)
+      .option("--limit <n>", "Maximum rows to display");
+  const sessionListSelector = async (cmd: Command, slugArg?: string): Promise<ResolvedAgentOptions<SessionListSelectorOptions>> => {
+    const opts = commandOpts<SessionListSelectorOptions>(cmd);
+    validateSessionsListOptions(opts);
+    return resolveAgentOptions(opts, slugArg);
+  };
+  const sessionsListAction = async (cmd: Command, slugArg?: string) => {
+    const opts = await sessionListSelector(cmd, slugArg);
+    const ctx = await buildContext();
+    if (isJson(cmd)) printJson(await sessionsListData(ctx, opts));
+    else console.log(await sessionsList(ctx, opts));
+  };
+  const sessionsShowAction = async (id: string, cmd: Command, slugArg?: string) => {
+    normalizeNonBlank(id, "Session id");
+    const opts = await resolveAgentOptions(commandOpts<AgentSelectorOptions>(cmd), slugArg);
+    const ctx = await buildContext();
+    if (isJson(cmd)) printJson(await sessionsShowData(ctx, id, opts));
+    else console.log(await sessionsShow(ctx, id, opts));
+  };
+
+  const sessions = program
+    .command("sessions")
+    .description("List transcript sessions for a deployed agent; use `show`/`view` for transcripts.")
+    .action(async (_opts: AgentSelectorOptions, cmd: Command) => sessionsListAction(cmd));
+  sessionsListOpts(sessions);
+  sessionsOpts(sessions
+    .command("show <id>")
+    .alias("view")
+    .description("Render a session transcript (requires the org's transcript-access setting)."))
+    .action(async (id: string, _opts: AgentSelectorOptions, cmd: Command) => sessionsShowAction(id, cmd));
+  sessionsOpts(program
+    .command("session <id>")
+    .description("Render a session transcript; alias of `dharta sessions view`."))
+    .action(async (id: string, _opts: AgentSelectorOptions, cmd: Command) => sessionsShowAction(id, cmd));
+
+  program
+    .command("ps")
+    .description("Sessions active right now: count, age, model, tokens.")
+    .option("-a, --agent <slug>", "Agent slug (default: the agent in this folder)").option("-p, --project <slug>", "Alias of --agent")
+    .option("--dir <dir>", "Agent directory (default: current directory)")
+    .option("--limit <n>", "Maximum rows to display")
+    .action(async (_opts: SessionListSelectorOptions, cmd: Command) => {
+      const opts = commandOpts<SessionListSelectorOptions>(cmd);
+      validateSessionsListOptions(opts);
+      const resolved = await resolveAgentOptions(opts);
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await psData(ctx, resolved));
+      else console.log(await psCmd(ctx, resolved));
+    });
+
+  const files = program
+    .command("files")
+    .description("Read a karta's durable workspace files (owner channel, RFC 0060).")
+    .action(helpOnlyAction("dharta files"));
+  files
+    .command("ls <agent> <karta>")
+    .description("List a karta's durable workspace files (path and size).")
+    .action(async (agent: string, karta: string, _opts: unknown, cmd: Command) => {
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await filesLsData(ctx, agent, karta));
+      else console.log(await filesLs(ctx, agent, karta));
+    });
+  files
+    .command("get <agent> <karta> <path>")
+    .description("Fetch one workspace file; writes to --out, or streams bytes to stdout.")
+    .option("-o, --out <file>", "Write the file's bytes to this path instead of stdout")
+    .action(async (
+      agent: string,
+      karta: string,
+      path: string,
+      opts: { out?: string },
+      cmd: Command,
+    ) => {
+      // Raw bytes, not a single JSON payload — --json has no meaning here.
+      rejectJson(cmd, "dharta files get");
+      const out = opts.out !== undefined ? normalizeNonBlank(opts.out, "--out") : undefined;
+      const ctx = await buildContext();
+      const msg = await filesGet(ctx, agent, karta, path, out);
+      if (msg) console.log(msg);
+    });
+
+  program
+    .command("send <message>")
+    .alias("run")
+    .description("Send a message to a DEPLOYED agent and print its reply (prod smoke test).")
+    .option("-a, --agent <slug>", "Agent slug (default: the agent in this folder)")
+    .option("-p, --project <slug>", "Alias of --agent")
+    .option("--dir <dir>", "Directory to resolve the agent from (default: current directory)")
+    .option("--session-id <id>", "Continue an existing session instead of opening a new one")
+    .action(
+      async (
+        message: string,
+        _opts: { agent?: string; project?: string; dir?: string; sessionId?: string },
+        cmd: Command,
+      ) => {
+        const opts = commandOpts<{ agent?: string; project?: string; dir?: string; sessionId?: string }>(cmd);
+        normalizeNonBlank(message, "message");
+        if (opts.sessionId !== undefined) normalizeNonBlank(opts.sessionId, "Session id");
+        const resolved = await resolveAgentOptions(opts);
+        const ctx = await buildContext();
+        const result = await runCmd(ctx, message, { ...resolved, json: isJson(cmd) });
+        if (isJson(cmd)) printJson(result);
+      },
+    );
+
+  const env = program
+    .command("env")
+    .description("Manage the agent's environment bindings (declare-or-bind).")
+    .action(helpOnlyAction("dharta env"));
+  const projectOpts = (cmd: ReturnType<typeof env.command>) =>
+    cmd
+      .option("-a, --agent <slug>", "Agent slug (default: the agent in this folder)").option("-p, --project <slug>", "Alias of --agent")
+      .option("--dir <dir>", "Agent directory (default: current directory)");
+  projectOpts(env.command("list"))
+    .description("List prod env bindings (values masked; --reveal to show).")
+    .option("--reveal", "Print full values instead of masking them")
+    .action(async (_opts: AgentSelectorOptions & { reveal?: boolean }, cmd: Command) => {
+      const opts = commandOpts<AgentSelectorOptions & { reveal?: boolean }>(cmd);
+      const resolved = await resolveAgentOptions(opts);
+      const ctx = await buildContext();
+      // --json returns raw values (machine-readable, opt-in); the human table
+      // masks by default so a routine `env list` never leaks a token.
+      if (isJson(cmd)) printJson(await envListData(ctx, resolved));
+      else console.log(await envList(ctx, { ...resolved, reveal: opts.reveal === true }));
+    });
+  projectOpts(env.command("set <assignment>"))
+    .description("Bind NAME=value in prod (--secret excludes it from pull).")
+    .option("--secret", "Mark the value secret (cannot be unmarked without deleting)")
+    .action(
+      async (
+        assignment: string,
+        _opts: AgentSelectorOptions & { secret?: boolean },
+        cmd: Command,
+      ) => {
+        const opts = commandOpts<AgentSelectorOptions & { secret?: boolean }>(cmd);
+        validateEnvAssignment(assignment);
+        const resolved = await resolveAgentOptions(opts);
+        const ctx = await buildContext();
+        if (isJson(cmd)) printJson(await envSetData(ctx, assignment, resolved));
+        else console.log(await envSet(ctx, assignment, resolved));
+      },
+    );
+  projectOpts(env.command("unset <name>"))
+    .description("Remove a prod env binding.")
+    .action(async (name: string, _opts: AgentSelectorOptions, cmd: Command) => {
+      const opts = commandOpts<AgentSelectorOptions>(cmd);
+      validateEnvName(name);
+      const resolved = await resolveAgentOptions(opts);
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await envUnsetData(ctx, name, resolved));
+      else console.log(await envUnset(ctx, name, resolved));
+    });
+  projectOpts(env.command("pull"))
+    .description("Hydrate .env from prod values (audited; secrets excluded by default).")
+    .option("--force", "Overwrite an existing .env")
+    .option("--include-secrets", "Also fetch secret-marked values (requires env:secrets:read; audited)")
+    .action(
+      async (
+        _opts: AgentSelectorOptions & { force?: boolean; includeSecrets?: boolean },
+        cmd: Command,
+      ) => {
+        const opts = commandOpts<AgentSelectorOptions & { force?: boolean; includeSecrets?: boolean }>(cmd);
+        await validateEnvPullOptions(opts);
+        const resolved = await resolveAgentOptions(opts);
+        const ctx = await buildContext();
+        if (isJson(cmd)) printJson(await envPullData(ctx, resolved));
+        else console.log(await envPull(ctx, resolved));
+      },
+    );
+  projectOpts(env.command("diff"))
+    .description("Report drift between .env, prod bindings, and dharta.toml [env].")
+    .action(async (_opts: AgentSelectorOptions, cmd: Command) => {
+      const opts = commandOpts<AgentSelectorOptions>(cmd);
+      await validateEnvDiffOptions(opts);
+      const resolved = await resolveAgentOptions(opts);
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await envDiffData(ctx, resolved));
+      else console.log(await envDiff(ctx, resolved));
+    });
+
+  program
+    .command("update")
+    .description("Self-update (standalone installs; npm installs update via npm).")
+    .action(async (_opts: unknown, cmd: Command) => {
+      if (isJson(cmd)) printJson({ message: await update({ log: logToStderr }) });
+      else console.log(await update());
+    });
+
+  program
+    .command("doctor")
+    .description("Diagnose the local setup: PATH shadowing, runtime bootstrap, login state.")
+    .action(async (_opts: unknown, cmd: Command) => {
+      const report = await doctor();
+      if (isJson(cmd)) printJson({ ok: report.ok, checks: report.lines });
+      else console.log(report.lines.join("\n"));
+      if (!report.ok) process.exitCode = 1;
+    });
+
+  program
+    .command("usage")
+    .description("Show usage totals and budget for the current period.")
+    .action(async (_opts: unknown, cmd: Command) => {
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await usageData(ctx));
+      else console.log(await usageCmd(ctx));
+    });
+
+  const agent = program.command("agent").description("Inspect and manage your agents.").action(helpOnlyAction("dharta agent"));
+  agent
+    .command("list")
+    .description("List all agents in your org.")
+    .action(async (_opts: unknown, cmd: Command) => {
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await agentsListData(ctx));
+      else console.log(await agentsList(ctx));
+    });
+  agent
+    .command("show [slug]")
+    .description("Show an agent + its recent releases (the agent in this folder if no slug given).")
+    .option("-a, --agent <slug>", "Agent slug (default: the agent in this folder)")
+    .option("-p, --project <slug>", "Alias of --agent")
+    .option("--dir <dir>", "Directory to resolve the agent from (default: current directory)")
+    .action(async (slug: string | undefined, _opts: { agent?: string; project?: string; dir?: string }, cmd: Command) => {
+      const opts = commandOpts<{ agent?: string; project?: string; dir?: string }>(cmd);
+      const resolvedOpts = await resolveAgentOptions(opts, slug);
+      const ctx = await buildContext();
+      const resolved = resolvedOpts.agent;
+      if (isJson(cmd)) printJson(await agentsShowData(ctx, resolved));
+      else console.log(await agentsShow(ctx, resolved));
+    });
+  const agentSessions = agent
+    .command("sessions [slug]")
+    .description("List transcript sessions for an agent; use `view <id>` for transcripts.")
+    .action(async (slug: string | undefined, _opts: AgentSelectorOptions, cmd: Command) => sessionsListAction(cmd, slug));
+  sessionsListOpts(agentSessions);
+  sessionsOpts(agentSessions
+    .command("show <id> [slug]")
+    .alias("view")
+    .description("Render a session transcript; alias of `dharta sessions show`."))
+    .action(async (id: string, slug: string | undefined, _opts: AgentSelectorOptions, cmd: Command) =>
+      sessionsShowAction(id, cmd, slug),
+    );
+  sessionsOpts(agent
+    .command("session <id> [slug]")
+    .description("Render a session transcript; alias of `dharta sessions view`."))
+    .action(async (id: string, slug: string | undefined, _opts: AgentSelectorOptions, cmd: Command) =>
+      sessionsShowAction(id, cmd, slug),
+    );
+  agent
+    .command("releases [slug]")
+    .description("List an agent's releases.")
+    .option("-a, --agent <slug>", "Agent slug (default: the agent in this folder)")
+    .option("-p, --project <slug>", "Alias of --agent")
+    .option("--dir <dir>", "Directory to resolve the agent from (default: current directory)")
+    .action(async (slug: string | undefined, _opts: { agent?: string; project?: string; dir?: string }, cmd: Command) => {
+      const opts = commandOpts<{ agent?: string; project?: string; dir?: string }>(cmd);
+      const resolvedOpts = await resolveAgentOptions(opts, slug);
+      const ctx = await buildContext();
+      const resolved = resolvedOpts.agent;
+      if (isJson(cmd)) printJson(await agentsReleasesData(ctx, resolved));
+      else console.log(await agentsReleases(ctx, resolved));
+    });
+  agent
+    .command("activate <version> [slug]")
+    .description("Activate an existing production release.")
+    .option("-a, --agent <slug>", "Agent slug (default: the agent in this folder)")
+    .option("-p, --project <slug>", "Alias of --agent")
+    .option("--dir <dir>", "Directory to resolve the agent from (default: current directory)")
+    .action(async (version: string, slug: string | undefined, _opts: { agent?: string; project?: string; dir?: string }, cmd: Command) => {
+      const opts = commandOpts<{ agent?: string; project?: string; dir?: string }>(cmd);
+      parseVersion(version);
+      const resolvedOpts = await resolveAgentOptions(opts, slug);
+      const ctx = await buildContext();
+      const resolved = resolvedOpts.agent;
+      if (isJson(cmd)) printJson(await agentsActivateReleaseData(ctx, resolved, version));
+      else console.log(await agentsActivateRelease(ctx, resolved, version));
+    });
+  agent
+    .command("serving <state> [slug]")
+    .description(`Resume or pause serving for an agent. ${STATE_HELP}`)
+    .option("-a, --agent <slug>", "Agent slug (default: the agent in this folder)")
+    .option("-p, --project <slug>", "Alias of --agent")
+    .option("--dir <dir>", "Directory to resolve the agent from (default: current directory)")
+    .action(async (state: string, slug: string | undefined, _opts: { agent?: string; project?: string; dir?: string }, cmd: Command) => {
+      const opts = commandOpts<{ agent?: string; project?: string; dir?: string }>(cmd);
+      const enabled = parseOnOff(state, "state");
+      const resolvedOpts = await resolveAgentOptions(opts, slug);
+      const ctx = await buildContext();
+      const resolved = resolvedOpts.agent;
+      if (isJson(cmd)) printJson(await agentsServingSetData(ctx, resolved, enabled));
+      else console.log(await agentsServingSet(ctx, resolved, enabled));
+    });
+  agent
+    .command("dashboard-edits <state> [slug]")
+    .description(`Enable or disable browser-console edits for an agent. ${STATE_HELP}`)
+    .option("-a, --agent <slug>", "Agent slug (default: the agent in this folder)")
+    .option("-p, --project <slug>", "Alias of --agent")
+    .option("--dir <dir>", "Directory to resolve the agent from (default: current directory)")
+    .action(async (state: string, slug: string | undefined, _opts: { agent?: string; project?: string; dir?: string }, cmd: Command) => {
+      const opts = commandOpts<{ agent?: string; project?: string; dir?: string }>(cmd);
+      const enabled = parseOnOff(state, "state");
+      const resolvedOpts = await resolveAgentOptions(opts, slug);
+      const ctx = await buildContext();
+      const resolved = resolvedOpts.agent;
+      if (isJson(cmd)) printJson(await agentsDashboardEditsSetData(ctx, resolved, enabled));
+      else console.log(await agentsDashboardEditsSet(ctx, resolved, enabled));
+    });
+  agent
+    .command("model [slug]")
+    .description("Set an agent model override.")
+    .option("-a, --agent <slug>", "Agent slug (default: the agent in this folder)")
+    .option("-p, --project <slug>", "Alias of --agent")
+    .option("--dir <dir>", "Directory to resolve the agent from (default: current directory)")
+    .addOption(choiceOption("--source <source>", "inherit or platform; omit when using --connector-id", AGENT_MODEL_SOURCES))
+    .option("--connector-id <id>", "Numeric BYOK connector id from `dharta model-keys list`; omit --source")
+    .option("--model <model>", "Provider model id")
+    .option("--temperature <number>", "Sampling temperature from 0 to 2")
+    .option("--clear-temperature", "Inherit temperature")
+    .option("--top-p <number>", "Nucleus sampling probability above 0 and at most 1")
+    .option("--clear-top-p", "Inherit top-p")
+    .option("--max-output-tokens <number>", "Positive output token limit")
+    .option("--clear-max-output-tokens", "Inherit the output token limit")
+    .addOption(choiceOption("--reasoning-effort <level>", "Reasoning effort", ["low", "medium", "high"]))
+    .option("--clear-reasoning-effort", "Inherit reasoning effort")
+    .action(async (
+      slug: string | undefined,
+      _opts: AgentModelSetOptions & { agent?: string; project?: string; dir?: string },
+      cmd: Command,
+    ) => {
+      const opts = commandOpts<AgentModelSetOptions & { agent?: string; project?: string; dir?: string }>(cmd);
+      validateAgentModelSetOptions(opts);
+      const resolvedOpts = await resolveAgentOptions(opts, slug);
+      const ctx = await buildContext();
+      const resolved = resolvedOpts.agent;
+      if (isJson(cmd)) printJson(await agentsModelSetData(ctx, resolved, opts));
+      else console.log(await agentsModelSet(ctx, resolved, opts));
+    });
+  agent
+    .command("workspace-inspectable <state> [slug]")
+    .description(`Enable or disable durable workspace inspection for an agent. ${STATE_HELP}`)
+    .option("-a, --agent <slug>", "Agent slug (default: the agent in this folder)")
+    .option("-p, --project <slug>", "Alias of --agent")
+    .option("--dir <dir>", "Agent directory (default: current directory)")
+    .action(async (
+      state: string,
+      slugArg: string | undefined,
+      _opts: { agent?: string; project?: string; dir?: string },
+      cmd: Command,
+    ) => {
+      const opts = commandOpts<{ agent?: string; project?: string; dir?: string }>(cmd);
+      const enabled = parseOnOff(state, "state");
+      const resolvedOpts = await resolveAgentOptions(opts, slugArg);
+      const ctx = await buildContext();
+      const resolved = resolvedOpts.agent;
+      if (isJson(cmd)) printJson(await agentsWorkspaceInspectableSetData(ctx, resolved, enabled));
+      else console.log(await agentsWorkspaceInspectableSet(ctx, resolved, enabled));
+    });
+  const workspaceAccess = agent
+    .command("workspace-access")
+    .description("Show or set an agent's workspace access grants (RFC 0060).");
+  workspaceAccess
+    .command("show [slug]")
+    .description("Show the audience x channel workspace access grant matrix.")
+    .option("-a, --agent <slug>", "Agent slug (default: the agent in this folder)")
+    .option("-p, --project <slug>", "Alias of --agent")
+    .option("--dir <dir>", "Agent directory (default: current directory)")
+    .action(async (
+      slugArg: string | undefined,
+      _opts: { agent?: string; project?: string; dir?: string },
+      cmd: Command,
+    ) => {
+      const opts = commandOpts<{ agent?: string; project?: string; dir?: string }>(cmd);
+      const resolvedOpts = await resolveAgentOptions(opts, slugArg);
+      const ctx = await buildContext();
+      const resolved = resolvedOpts.agent;
+      if (isJson(cmd)) printJson(await agentsWorkspaceAccessShowData(ctx, resolved));
+      else console.log(await agentsWorkspaceAccessShow(ctx, resolved));
+    });
+  workspaceAccess
+    .command("set <grant> [slug]")
+    .description(
+      "Grant or revoke one access path (<path>=<on|off>). Paths: owners.git, owners.api, users.widget, users.agent_definition. e.g. dharta agent workspace-access set users.widget=on",
+    )
+    .option("-a, --agent <slug>", "Agent slug (default: the agent in this folder)")
+    .option("-p, --project <slug>", "Alias of --agent")
+    .option("--dir <dir>", "Agent directory (default: current directory)")
+    .action(async (
+      grant: string,
+      slugArg: string | undefined,
+      _opts: { agent?: string; project?: string; dir?: string },
+      cmd: Command,
+    ) => {
+      const opts = commandOpts<{ agent?: string; project?: string; dir?: string }>(cmd);
+      const patch = parseWorkspaceAccessAssignments([grant]);
+      const resolvedOpts = await resolveAgentOptions(opts, slugArg);
+      const ctx = await buildContext();
+      const resolved = resolvedOpts.agent;
+      if (isJson(cmd)) printJson(await agentsWorkspaceAccessSetData(ctx, resolved, patch));
+      else console.log(await agentsWorkspaceAccessSet(ctx, resolved, patch));
+    });
+  agent
+    .command("delete [slug]")
+    .description("Archive an agent.")
+    .option("-a, --agent <slug>", "Agent slug (default: the agent in this folder)")
+    .option("-p, --project <slug>", "Alias of --agent")
+    .option("--dir <dir>", "Agent directory (default: current directory)")
+    .action(async (slugArg: string | undefined, _opts: { agent?: string; project?: string; dir?: string }, cmd: Command) => {
+      const opts = commandOpts<{ agent?: string; project?: string; dir?: string }>(cmd);
+      const resolvedOpts = await resolveAgentOptions(opts, slugArg);
+      const ctx = await buildContext();
+      const resolved = resolvedOpts.agent;
+      if (isJson(cmd)) printJson(await agentsDeleteData(ctx, resolved));
+      else console.log(await agentsDelete(ctx, resolved));
+    });
+
+  program
+    .command("deploy [slug]")
+    .description(
+      "Deploy exactly one agent: the dharta.toml at/above --dir (default: cwd). Its deploy_method selects git or folder; --mode is a one-run override.",
+    )
+    .option("--dir <dir>", "Agent directory, or a subdirectory inside it (default: cwd)")
+    .option(
+      "--reconcile-source",
+      "git only: intentionally align Dharta's hosted source branch to local HEAD after inspecting divergent history",
+    )
+    .addOption(
+      choiceOption(
+        "--mode <mode>",
+        "one-run override: git (agent-targeted push) or folder (selected-folder upload). Default: deploy_method in dharta.toml.",
+        ["git", "folder"],
+      ),
+    )
+    .action(
+      async (
+        slug: string | undefined,
+        opts: { dir?: string; mode?: "git" | "folder"; reconcileSource?: boolean },
+        cmd: Command,
+      ) => {
+        const rawMode = opts.mode;
+        if (slug !== undefined) validateAgentSlug(slug, "agent slug");
+        const dir = normalizeNonBlank(opts.dir ?? ".", "--dir");
+        validateDeployDir(dir);
+        // Resolve the effective mode here only to enforce the JSON contract.
+        // deploy() receives only an explicit override so it remains the one
+        // owner of target/config resolution and can narrate legacy inference.
+        const mode = rawMode ?? (await inferMode(dir));
+        if (opts.reconcileSource && mode !== "git") {
+          throw new Error(
+            "--reconcile-source is only valid for git deploys. " +
+              "Remove it, or use `--mode git` to reconcile Dharta's hosted source branch.",
+          );
+        }
+        // git mode's output is the live push sideband, not a payload.
+        const json = mode === "folder" && isJson(cmd);
+        if (mode === "git" && isJson(cmd)) {
+          throw new Error(
+            "--json is only supported for `dharta deploy --mode folder`; git deploy streams git push output. Run `dharta deploy` without --json or pass `--mode folder`.",
+          );
+        }
+        const ctx = await buildContext();
+        const result = await deploy(ctx, slug, {
+          dir,
+          mode: rawMode,
+          reconcileSource: opts.reconcileSource,
+          log: json ? logToStderr : undefined,
+        });
+        if (json) printJson(result);
+      },
+    );
+
+  program
+    .command("status")
+    .description(
+      "Show every agent in this repo (resolved from the git root) and its live release on the active profile.",
+    )
+    .option("--dir <dir>", "Directory to scan (default: cwd; the whole repo when inside one)")
+    .addOption(new Option("-a, --agent <slug>").hideHelp())
+    .addOption(new Option("-p, --project <slug>").hideHelp())
+    .action(async (opts: { dir?: string; agent?: string; project?: string }, cmd: Command) => {
+      if (opts.agent !== undefined || opts.project !== undefined) {
+        const slug = opts.agent ?? opts.project ?? "";
+        if (slug.trim()) validateAgentSlug(slug, opts.agent !== undefined ? "--agent" : "--project");
+        throw new Error("`dharta status` is repo-wide. Use `dharta agent show <slug>` for one remote agent, or `dharta status --dir <path>` for a local repo.");
+      }
+      validateAgentSelectorOptions(opts);
+      let ctx: Awaited<ReturnType<typeof buildContext>> | null = null;
+      let authMessage: string | undefined;
+      try {
+        ctx = await buildContext();
+      } catch (err) {
+        if (!isNotLoggedInError(err)) throw err;
+        authMessage = err instanceof Error ? err.message : String(err);
+      }
+      if (isJson(cmd)) printJson(await statusData(ctx, { dir: opts.dir, authMessage }));
+      else console.log(await status(ctx, { dir: opts.dir, authMessage }));
+    });
+
+  program
+    .command("rollback [slug]")
+    .description("Roll back to a previous release (requires releases:write).")
+    .option("--to <version>", "target release, e.g. v3 or 3")
+    .option("-a, --agent <slug>", "Agent slug (default: the agent in this folder)").option("-p, --project <slug>", "Alias of --agent")
+    .option("--dir <dir>", "Agent directory (default: current directory)")
+    .action(
+      async (
+        slug: string | undefined,
+        _opts: { to?: string; agent?: string; project?: string; dir?: string },
+        cmd: Command,
+      ) => {
+        const opts = commandOpts<{ to?: string; agent?: string; project?: string; dir?: string }>(cmd);
+        const v = parseRollbackTarget(opts.to);
+        const resolvedOpts = await resolveAgentOptions(opts, slug);
+        const ctx = await buildContext();
+        const resolved = resolvedOpts.agent;
+        if (isJson(cmd)) printJson(await rollbackData(ctx, resolved, v));
+        else console.log(await rollback(ctx, resolved, v));
+      },
+    );
+
+  program
+    .command("logs [slug]")
+    .description("Stream or poll agent logs (slug inferred from this folder if omitted).")
+    .option("--tail", "Stream logs as they arrive (SSE if available)")
+    .option("--since <iso>", "Only show logs after this timestamp (polling fallback)")
+    .option("-a, --agent <slug>", "Agent slug (default: the agent in this folder)").option("-p, --project <slug>", "Alias of --agent")
+    .option("--dir <dir>", "Agent directory (default: current directory)")
+    .action(
+      async (
+        slug: string | undefined,
+        _opts: { tail?: boolean; since?: string; agent?: string; project?: string; dir?: string },
+        cmd: Command,
+      ) => {
+        const opts = commandOpts<{ tail?: boolean; since?: string; agent?: string; project?: string; dir?: string }>(cmd);
+        rejectJson(cmd, "dharta logs");
+        validateLogsOptions(opts);
+        const resolvedOpts = await resolveAgentOptions(opts, slug);
+        const ctx = await buildContext();
+        const resolved = resolvedOpts.agent;
+        const emitted = await logsTail(
+          ctx,
+          resolved,
+          { tail: opts.tail, since: opts.since },
+          (line) => process.stdout.write(line + "\n"),
+        );
+        if (!opts.tail && emitted === 0) {
+          const window = opts.since?.trim() ? `since ${opts.since.trim()}` : "in the last minute";
+          console.log(`No log entries for ${resolved} ${window}.`);
+        }
+      },
+    );
+
+  program
+    .command("completion")
+    .description("Print a shell completion script (pipe it into your shell's setup).")
+    .addArgument(choiceArgument("<shell>", "target shell", ["bash", "zsh"]))
+    .action((shell: string, _opts: unknown, cmd: Command) => {
+      rejectJson(cmd, "dharta completion");
+      console.log(shell === "zsh" ? zshCompletion(program) : bashCompletion(program));
+    });
+
+  // RFC 0013 §3: --json on every command. Registered on every node of
+  // the command tree so the outermost scan consumes the flag and
+  // isJson() reads it back through optsWithGlobals(). Stream/protocol
+  // commands and help-only command groups keep a hidden parser option
+  // because they reject --json.
+  for (const cmd of allCommands(program)) {
+    if (hidesJsonHelp(cmd)) {
+      cmd.addOption(new Option("--json", "Print the result as JSON (machine-readable)").hideHelp());
+    } else {
+      cmd.option("--json", jsonHelpDescription(cmd));
+    }
+  }
+  installMissingArgumentChoiceHints(program);
+  installTopLevelUnknownCommandGuard(program);
+
+  return program;
+}
+
+function isNotLoggedInError(err: unknown): boolean {
+  return err instanceof Error && /^Not logged in\./.test(err.message);
+}
+
+export async function main(argv: string[]): Promise<void> {
+  await buildProgram().parseAsync(argv);
+}
+
+function allCommands(root: Command): Command[] {
+  const out: Command[] = [];
+  const visit = (cmd: Command): void => {
+    out.push(cmd);
+    for (const sub of cmd.commands) visit(sub as Command);
+  };
+  visit(root);
+  return out;
+}
+
+function hidesJsonHelp(cmd: Command): boolean {
+  return [
+    "dharta",
+    "dharta auth",
+    "dharta analytics",
+    "dharta keys",
+    "dharta model-keys",
+    "dharta members",
+    "dharta embed-keys",
+    "dharta caps",
+    "dharta appearance",
+    "dharta schedules",
+    "dharta directories",
+    "dharta webhooks",
+    "dharta env",
+    "dharta agent",
+    "dharta git-credential",
+    "dharta dev",
+    "dharta logs",
+    "dharta completion",
+  ].includes(commandPath(cmd));
+}
+
+function jsonHelpDescription(cmd: Command): string {
+  if (commandPath(cmd) === "dharta deploy") {
+    return "Print JSON for --mode folder uploads; git mode streams git push output";
+  }
+  return "Print the result as JSON (machine-readable)";
+}
+
+function installTopLevelUnknownCommandGuard(program: Command): void {
+  const originalParseAsync = program.parseAsync.bind(program);
+  program.parseAsync = async (argv?: readonly string[], options?: Parameters<Command["parseAsync"]>[1]) => {
+    rejectUnknownTopLevelCommand(program, argv, options);
+    return originalParseAsync(argv as string[] | undefined, options);
+  };
+
+  const originalParse = program.parse.bind(program);
+  program.parse = (argv?: readonly string[], options?: Parameters<Command["parse"]>[1]) => {
+    rejectUnknownTopLevelCommand(program, argv, options);
+    return originalParse(argv as string[] | undefined, options);
+  };
+}
+
+const HELP_ONLY_COMMAND_PATHS = new Set([
+  "dharta",
+  "dharta auth",
+  "dharta analytics",
+  "dharta keys",
+  "dharta model-keys",
+  "dharta members",
+  "dharta embed-keys",
+  "dharta caps",
+  "dharta caps budget",
+  "dharta appearance",
+  "dharta schedules",
+  "dharta directories",
+  "dharta webhooks",
+  "dharta env",
+  "dharta agent",
+]);
+
+function rejectUnknownTopLevelCommand(
+  program: Command,
+  argv?: readonly string[],
+  options?: Parameters<Command["parse"]>[1],
+): void {
+  const args = argv ? [...argv].slice(options?.from === "user" ? 0 : 2) : process.argv.slice(2);
+  let cursor: Command = program;
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index] ?? "";
+    if (token === "--") return;
+    if (token.startsWith("-")) {
+      const option = commandOption(cursor, token);
+      if (!option) return;
+      if (!token.includes("=") && optionTakesValue(option)) index += 1;
+      continue;
+    }
+    const path = commandPath(cursor);
+    if (!HELP_ONLY_COMMAND_PATHS.has(path)) return;
+
+    const visible = cursor.commands.filter((cmd) => !(cmd as unknown as { _hidden?: boolean })._hidden);
+    const child = visible.find((cmd) => cmd.name() === token || cmd.aliases().includes(token));
+    if (child) {
+      cursor = child as Command;
+      continue;
+    }
+
+    const suggestion = closestCommand(token, commandSuggestionTokens(cursor));
+    cursor.error(
+      `error: unknown command '${token}'${path === "dharta" ? "" : ` for ${path}`}. ` +
+        `Run \`${path} --help\` for available commands.` +
+        (suggestion ? ` Did you mean \`${suggestion}\`?` : ""),
+    );
+  }
+}
+
+function commandOption(cmd: Command, token: string): Command["options"][number] | undefined {
+  const flag = token.includes("=") ? token.slice(0, token.indexOf("=")) : token;
+  return cmd.options.find((option) => option.long === flag || option.short === flag);
+}
+
+function optionTakesValue(option: Command["options"][number]): boolean {
+  return Boolean(
+    (option as unknown as { required?: boolean; optional?: boolean }).required ||
+      (option as unknown as { required?: boolean; optional?: boolean }).optional,
+  );
+}
+
+function collect(value: string, previous: string[]): string[] {
+  previous.push(value);
+  return previous;
+}
+
+function installMissingArgumentChoiceHints(root: Command): void {
+  for (const cmd of allCommands(root)) {
+    const missingArgument = (cmd as unknown as { missingArgument?: (name: string) => void }).missingArgument;
+    if (!missingArgument) continue;
+    (cmd as unknown as { missingArgument: (name: string) => void }).missingArgument = (name: string): void => {
+      const arg = cmd.registeredArguments.find((candidate) => candidate.name() === name);
+      const choices = arg?.argChoices ?? [];
+      const choicesHint = choices.length > 0 ? ` Allowed choices are ${choices.join(", ")}.` : "";
+      cmd.error(
+        `error: missing required argument '${name}'.${choicesHint} Usage: ${formatCommandUsage(cmd)}`,
+        { code: "commander.missingArgument" },
+      );
+    };
+  }
+}
+
+function formatCommandUsage(cmd: Command): string {
+  return `${commandPath(cmd)} ${cmd.usage()}`.trim();
+}
+
+function choiceOption<const T extends readonly string[]>(flags: string, description: string, allowed: T): Option {
+  return new Option(flags, description).choices([...allowed]).argParser(choiceValue(allowed));
+}
+
+function choiceListOption<const T extends readonly string[]>(flags: string, description: string, allowed: T): Option {
+  let sawExplicitValue = false;
+  const parseChoice = choiceValue(allowed);
+  return new Option(flags, description)
+    .choices([...allowed])
+    .argParser((value: string, previous: T[number][] = []) => {
+      const explicitValues = sawExplicitValue ? previous : [];
+      sawExplicitValue = true;
+      const values = value.split(/[,\s]+/).map((part) => part.trim()).filter(Boolean);
+      if (values.length === 0) throw new InvalidArgumentError(`Allowed choices are ${allowed.join(", ")}.`);
+      return [...explicitValues, ...values.map(parseChoice)];
+    });
+}
+
+function choiceArgument<const T extends readonly string[]>(name: string, description: string, allowed: T): Argument {
+  return new Argument(name, description).choices([...allowed]).argParser(choiceValue(allowed));
+}
+
+function choiceValue<const T extends readonly string[]>(allowed: T): (value: string) => T[number] {
+  return (value: string): T[number] => {
+    const normalized = value.trim();
+    if ((allowed as readonly string[]).includes(normalized)) return normalized as T[number];
+    const suggestion = closestChoice(normalized, allowed);
+    throw new InvalidArgumentError(
+      `Allowed choices are ${allowed.join(", ")}.` +
+        (suggestion ? ` Did you mean ${suggestion}?` : ""),
+    );
+  };
+}
+
+function parseOnOff(value: string, name: string): boolean {
+  const normalized = value.trim().toLowerCase();
+  if (["on", "true", "enabled", "enable", "resume", "resumed"].includes(normalized)) return true;
+  if (["off", "false", "disabled", "disable", "pause", "paused"].includes(normalized)) return false;
+  const suggestion = closestChoice(normalized, ["on", "off", "enabled", "disabled", "true", "false"]);
+  throw new Error(
+    `${name} must be on/off, enabled/disabled, or true/false.` +
+      (suggestion ? ` Did you mean ${suggestion}?` : ""),
+  );
+}
+
+export async function readStdin(): Promise<string> {
+  if (process.stdin.isTTY) {
+    // Reading a TTY would block silently until Ctrl-D — fail with the
+    // usage instead (gh parity: --with-token requires piped input).
+    throw new Error(
+      "No piped input. Usage: echo $DHARTA_API_KEY | dharta login --with-token",
+    );
+  }
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk));
+  const token = Buffer.concat(chunks).toString("utf8").trim();
+  if (!token) {
+    throw new Error("No token on stdin. Usage: echo $DHARTA_API_KEY | dharta login --with-token");
+  }
+  return token;
+}
+
+function parseVersion(input: string): number {
+  normalizeNonBlank(input, "version");
+  try {
+    return parseReleaseVersion(input, "version");
+  } catch {
+    throw new Error(`Invalid version: ${input.trim()}. Use e.g. v3 or 3.`);
+  }
+}
+
+function parseRollbackTarget(input: string | undefined): number {
+  if (input === undefined) {
+    throw new Error("Pass --to <version>. Usage: dharta rollback [slug] --to v3");
+  }
+  return parseVersion(input);
+}
+
+function parsePort(input: string): number {
+  const normalized = input.trim();
+  if (!normalized) throw new Error("--port cannot be blank.");
+  if (!/^[1-9]\d*$/.test(normalized)) {
+    throw new Error(`--port must be an integer between 1 and 65535.`);
+  }
+  const port = Number(normalized);
+  if (port > 65535) {
+    throw new Error(`--port must be an integer between 1 and 65535.`);
+  }
+  return port;
+}
+
+// Only run when invoked as a bin — vitest imports this module without
+// driving it. argv[1] is realpath'd because the installed bin is a
+// SYMLINK (npm link / npm i -g puts <prefix>/bin/dharta -> dist/cli.js):
+// a filename regex on argv[1] never matches the symlink name, so the
+// CLI would exit 0 silently for every global invocation.
+const invokedAsBin = (() => {
+  if (typeof process === "undefined" || !process.argv[1]) return false;
+  try {
+    return realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+})();
+if (invokedAsBin) {
+  main(process.argv).catch((err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`dharta: ${msg}\n`);
+    process.exit(1);
+  });
+}