@dharta/cli 0.6.77 → 0.6.78

package/src/cli.ts

@@ -3,9 +3,14 @@ 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 { API_KEY_SCOPES, type ApiKeyScope, type ModelConnectionProvider } from "@dharta/sdk";
 import { buildContext } from "./context.js";
-import { resolveBaseUrl } from "./config.js";
+import {
+  requestedProfileName,
+  resolveBaseUrl,
+  setRequestedIdempotencyKey,
+  setRequestedProfile,
+} from "./config.js";
 import { inferAgentSlug, validateAgentSelectorOptions, validateAgentSlug } from "./agent.js";
 import { login } from "./commands/login.js";
 import {
@@ -28,28 +33,62 @@ import {
   type AnalyticsView,
 } from "./commands/analytics.js";
 import {
+  keysBulk,
+  keysBulkData,
   keysCreate,
   keysCreateData,
+  keysDisable,
+  keysDisableData,
+  keysEnable,
+  keysEnableData,
   keysList,
   keysListData,
   keysRename,
   keysRenameData,
   keysRevoke,
   keysRevokeData,
+  keysRotate,
+  keysRotateData,
+  KEY_BULK_ACTIONS,
+  KEY_ROTATION_GRACE_PERIODS,
+  validateKeysBulkInput,
   validateKeysCreateInput,
+  validateKeysRotateInput,
 } from "./commands/keys.js";
 import {
-  modelKeysCreate,
-  modelKeysCreateData,
-  modelKeysList,
-  modelKeysListData,
-  modelKeysRevoke,
-  modelKeysRevokeData,
-  prepareModelKeysCreateOptions,
+  modelConnectionsConfigureModels,
+  modelConnectionsConfigureModelsData,
+  modelConnectionsCreate,
+  modelConnectionsCreateData,
+  modelConnectionsList,
+  modelConnectionsListData,
+  modelConnectionsModels,
+  modelConnectionsModelsData,
+  modelConnectionsModelsWritesOffers,
+  modelConnectionsRevoke,
+  modelConnectionsRevokeData,
+  modelConnectionsRotate,
+  modelConnectionsRotateData,
+  prepareModelConnectionsCreateOptions,
+  prepareModelConnectionsModelsOptions,
+  prepareModelConnectionsRotateOptions,
   MODEL_API_FORMATS,
-  validateModelKeyId,
-  validateModelKeysCreateOptions,
-} from "./commands/model-keys.js";
+  type ModelConnectionModelsOptions,
+  type ModelConnectionRotateOptions,
+  validateModelConnectionReference,
+  validateModelConnectionsCreateOptions,
+  validateModelConnectionsModelsOptions,
+  validateModelConnectionsRotateOptions,
+} from "./commands/model-connections.js";
+import {
+  type OrgModelSetOptions,
+  ORG_ENDPOINT_KINDS,
+  orgModelSet,
+  orgModelSetData,
+  orgModelShow,
+  orgModelShowData,
+  validateOrgModelSetOptions,
+} from "./commands/organization.js";
 import {
   membersInvite,
   membersInviteData,
@@ -57,10 +96,24 @@ import {
   membersListData,
   membersRemove,
   membersRemoveData,
+  membersResendInvitation,
+  membersResendInvitationData,
+  membersRevokeInvitation,
+  membersRevokeInvitationData,
   membersSetRole,
   membersSetRoleData,
   validateMembersInviteInput,
 } from "./commands/members.js";
+import {
+  orgRename,
+  orgRenameData,
+  orgSupportAccess,
+  orgSupportAccessData,
+  orgTranscriptAccess,
+  orgTranscriptAccessData,
+  normalizeOrganizationName,
+} from "./commands/org.js";
+import { reposDisconnectGithub, reposDisconnectGithubData } from "./commands/repos.js";
 import {
   kartaMembersGrant,
   kartaMembersGrantData,
@@ -88,21 +141,41 @@ import {
   kartaEnvSetData,
   kartaEnvUnset,
   kartaEnvUnsetData,
+  kartaShare,
+  kartaShareData,
+  kartaUnshare,
+  kartaUnshareData,
   validateKartaCreateOptions,
   validateKartaConfigureOptions,
   validateKartaNameOptions,
 } from "./commands/kartas.js";
 import { usage as usageCmd, usageData } from "./commands/usage.js";
 import {
+  type AgentCreateFromTemplateOptions,
+  type AgentCreateOptions,
   type AgentModelSetOptions,
   agentsActivateRelease,
   agentsActivateReleaseData,
+  agentsCreate,
+  agentsCreateData,
+  agentsCreateFromTemplate,
+  agentsCreateFromTemplateData,
   agentsDashboardEditsSet,
   agentsDashboardEditsSetData,
   agentsDelete,
   agentsDeleteData,
+  agentsDurableWorkspaceSet,
+  agentsDurableWorkspaceSetData,
+  agentsGithubRepos,
+  agentsGithubReposData,
   agentsList,
   agentsListData,
+  agentsRedeploy,
+  agentsRedeployData,
+  agentsRename,
+  agentsRenameData,
+  agentsRetryRelease,
+  agentsRetryReleaseData,
   agentsModelSet,
   agentsModelSetData,
   agentsReleases,
@@ -118,6 +191,8 @@ import {
   agentsWorkspaceAccessSet,
   agentsWorkspaceAccessSetData,
   parseWorkspaceAccessAssignments,
+  validateAgentCreateFromTemplateInput,
+  validateAgentCreateInput,
   validateAgentModelSetOptions,
 } from "./commands/agents.js";
 import {
@@ -185,6 +260,58 @@ import {
   directorySessionsData,
   validateDirectoryOptions,
 } from "./commands/directories.js";
+import {
+  type AnalyticsSaveOptions,
+  type AssignOptions,
+  type ClassifyOptions,
+  type ExportCreateOptions,
+  type OperationCreateOptions,
+  type RunbookOptions,
+  type SnoozeOptions,
+  type ViewWriteOptions,
+  FLEET_ENTITY_TYPES,
+  FLEET_SELECTION_MODES,
+  FLEET_SNOOZE_DURATIONS,
+  FLEET_VIEW_VISIBILITIES,
+  fleetAnalyticsSave,
+  fleetAnalyticsSaveData,
+  fleetAnalyticsUnpin,
+  fleetAnalyticsUnpinData,
+  fleetExportCreate,
+  fleetExportCreateData,
+  fleetFinding,
+  fleetFindingAssign,
+  fleetFindingAssignData,
+  fleetFindingClassify,
+  fleetFindingClassifyData,
+  fleetFindingData,
+  fleetFindingSnooze,
+  fleetFindingSnoozeData,
+  fleetFindingUpdate,
+  fleetFindingUpdateData,
+  fleetOperationCancel,
+  fleetOperationCancelData,
+  fleetOperationConfirm,
+  fleetOperationConfirmData,
+  fleetOperationCreate,
+  fleetOperationCreateData,
+  fleetOperationRetry,
+  fleetOperationRetryData,
+  fleetRollout,
+  fleetRolloutData,
+  fleetRolloutRollback,
+  fleetRolloutRollbackData,
+  fleetViewCreate,
+  fleetViewCreateData,
+  fleetViewDelete,
+  fleetViewDeleteData,
+  fleetViewFavorite,
+  fleetViewFavoriteData,
+  fleetViewUnfavorite,
+  fleetViewUnfavoriteData,
+  fleetViewUpdate,
+  fleetViewUpdateData,
+} from "./commands/fleet.js";
 import {
   parseEvents,
   webhooksCreate,
@@ -195,6 +322,8 @@ import {
   webhooksEnableData,
   webhooksList,
   webhooksListData,
+  webhooksTest,
+  webhooksTestData,
   webhooksUpdate,
   webhooksUpdateData,
   validateWebhooksCreateInput,
@@ -211,6 +340,8 @@ 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 { registerGenuiCommands } from "./commands/genui.js";
+import { flushJsonPayload, isJson, printJson, resetJsonPayload } from "./output.js";
 import {
   isHandoffTarget,
   open as openCmd,
@@ -251,13 +382,15 @@ 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 { visibleSubcommands } from "./command-tree.js";
+import { CliUsageError, exitCodeForError, isCommanderError, isNotAuthenticatedError } from "./exit-codes.js";
+import { armJqFilter } from "./jq.js";
 import { closestChoice, normalizeHttpUrl, normalizeNonBlank, parsePositiveInteger, parseReleaseVersion } from "./validators.js";
+import { DEV_MODEL_AUTH_VALUES, MODEL_CONNECTION_PROVIDERS, type DevModelAuth } from "./model-auth.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.";
 
@@ -275,29 +408,6 @@ 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;
 }
@@ -306,7 +416,7 @@ function validatePositionalAgentSelector(slug: string | undefined, opts: Pick<Ag
   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.");
+    throw new CliUsageError("Use either the positional agent slug or --agent/--project, not both.");
   }
 }
 
@@ -341,11 +451,75 @@ async function resolveAgentOptions<T extends AgentSelectorOptions>(
 }
 
 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.`,
-    );
-  }
+  if (!isJson(cmd)) return;
+  // --jq is rejected wherever --json is, and for the same reason: there is no
+  // payload to filter. Name the flag the user actually passed.
+  const flag = cmd.optsWithGlobals().jq !== undefined ? "--jq" : "--json";
+  throw new CliUsageError(
+    `${flag} is not supported for \`${name}\` - its output is not a single payload. Run it without ${flag}.`,
+  );
+}
+
+// A command group prints help and issues no request, so an Idempotency-Key on
+// one is a mistake with nowhere to land. Read-only LEAF commands are not
+// rejected: see the P9 entry in the RFC 0048 implementation log for why.
+function rejectIdempotencyKey(cmd: Command, name: string): void {
+  if (cmd.optsWithGlobals().idempotencyKey === undefined) return;
+  throw new CliUsageError(
+    `--idempotency-key is not supported for \`${name}\` - it prints help and sends no request. ` +
+      "Put it on the command that performs the mutation.",
+  );
+}
+
+// `--idempotency-key` names an `Idempotency-Key` for a write to the Dharta API.
+// These commands perform no mutation the key could protect, so accepting one
+// would silently ignore it, which is precisely the outcome a caller reaching for
+// the flag is trying to avoid.
+//
+// Several of them DO talk to Dharta, and the message must not claim otherwise:
+//
+//  - `login` runs before a credential exists. Its device-flow POSTs carry no
+//    key and the server installs no idempotency filter on them, and it then
+//    reads `/me` to learn who the new key belongs to. Reads and unprotected
+//    POSTs, no mutation.
+//  - `create` fetches `/agent_templates` and writes the result to disk.
+//  - `setup` writes files, and with `--login` it runs the login flow above.
+//  - `auth token` and `auth logout` read and rewrite the local profile.
+//  - `genui` builds a bundle, `artifact` spawns a local helper.
+//  - `doctor` and `update` talk to the package registry, never to Dharta.
+//  - `completion` prints a shell script.
+//
+// Read-only Dharta commands (`ps`, `usage`, `webhooks list`) perform no mutation
+// either and are deliberately NOT refused. They are steps in a run that writes,
+// the header rides along and is ignored server-side, and a script that sets one
+// flag for a whole pipeline should not have to special-case them. The commands
+// below are not that: a caller who puts the key on `dharta login` is expressing
+// an intent it can never honour, so saying so beats accepting it.
+const NON_MUTATING_COMMAND_PATHS = [
+  "dharta login",
+  "dharta auth token",
+  "dharta auth logout",
+  "dharta create",
+  "dharta setup",
+  "dharta genui",
+  "dharta artifact",
+  "dharta doctor",
+  "dharta update",
+  "dharta completion",
+];
+
+export function isNonMutatingCommandPath(path: string): boolean {
+  return NON_MUTATING_COMMAND_PATHS.some((entry) => path === entry || path.startsWith(`${entry} `));
+}
+
+function rejectNonMutatingIdempotencyKey(cmd: Command, key: string | undefined): void {
+  if (key === undefined) return;
+  const path = commandPath(cmd);
+  if (!isNonMutatingCommandPath(path)) return;
+  throw new CliUsageError(
+    `--idempotency-key is not supported for \`${path}\` - it performs no mutation the key could protect. ` +
+      "The flag applies to commands that write to the Dharta API.",
+  );
 }
 
 function helpOnlyAction(name: string) {
@@ -363,6 +537,7 @@ function helpOnlyAction(name: string) {
       );
     }
     rejectJson(cmd, name);
+    rejectIdempotencyKey(cmd, name);
     cmd.outputHelp();
   };
 }
@@ -385,27 +560,14 @@ function closestCommand(input: string, commands: string[]): string | null {
 
 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()]),
-    ),
+    new Set(visibleSubcommands(cmd).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.",
@@ -419,52 +581,9 @@ export function buildProgram(): Command {
     .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",
+        "Run `dharta <command> --help` for details. Docs: https://docs.dharta.ai",
       ].join("\n"),
     )
     .action(helpOnlyAction("dharta"));
@@ -477,25 +596,23 @@ export function buildProgram(): Command {
     .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,
+          // The global --profile names the profile this login writes.
+          profile: requestedProfileName(),
           apiKey: opts.withToken ? await readStdin() : undefined,
           // In JSON mode the device-flow narration (code, approve URL)
           // still has to reach the human - on stderr.
@@ -536,11 +653,14 @@ export function buildProgram(): Command {
     });
   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));
+    .description(
+      "Remove the stored credential (the key stays revocable on the dashboard). Removes the default profile unless --profile names another.",
+    )
+    .action(async (_opts: unknown, cmd: Command) => {
+      // The global --profile names the profile this removes.
+      const profile = requestedProfileName();
+      if (isJson(cmd)) printJson(await authLogoutData(profile));
+      else console.log(await authLogout(profile));
     });
 
   program
@@ -598,7 +718,7 @@ export function buildProgram(): 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`.");
+          throw new CliUsageError("--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
@@ -665,7 +785,7 @@ export function buildProgram(): Command {
     }, cmd: Command) => {
       validateAuditLogInput(opts);
       if (opts.csv && isJson(cmd)) {
-        throw new Error("Use either --csv or --json for audit-log, not both.");
+        throw new CliUsageError("Use either --csv or --json for audit-log, not both.");
       }
       const ctx = await buildContext();
       if (isJson(cmd)) printJson(await auditLogData(ctx, opts));
@@ -717,7 +837,10 @@ export function buildProgram(): Command {
 
   program
     .command("api [method] [path]")
-    .description("Call an allowlisted public JSON API endpoint with the active profile.")
+    .description(
+      "Call any public JSON API endpoint with the active profile. Unstable escape hatch: the curated commands are the stable contract, and this passthrough follows the API. " +
+        "Reachable paths start with /api/, /me, /version, /api_keys, /model_connections, or /agent_templates; what the request may do is decided server-side by the key's scopes.",
+    )
     .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, [])
@@ -782,47 +905,195 @@ export function buildProgram(): Command {
       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
+  keys
+    .command("rotate <id>")
+    .description("Replace a key with a new one carrying the same scopes, then retire the original.")
+    .addOption(
+      choiceOption(
+        "--grace-period <window>",
+        "How long the rotated key keeps working (default 24h)",
+        KEY_ROTATION_GRACE_PERIODS,
+      ),
+    )
+    .action(async (id: string, opts: { gracePeriod?: string }, cmd: Command) => {
+      validateKeysRotateInput(id, opts);
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await keysRotateData(ctx, id, opts));
+      else console.log(await keysRotate(ctx, id, opts));
+    });
+  keys
+    .command("disable <id>")
+    .description("Suspend an API key without revoking it.")
+    .action(async (id: string, _opts: unknown, cmd: Command) => {
+      normalizeNonBlank(id, "API key id");
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await keysDisableData(ctx, id));
+      else console.log(await keysDisable(ctx, id));
+    });
+  keys
+    .command("enable <id>")
+    .description("Return a disabled API key to service.")
+    .action(async (id: string, _opts: unknown, cmd: Command) => {
+      normalizeNonBlank(id, "API key id");
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await keysEnableData(ctx, id));
+      else console.log(await keysEnable(ctx, id));
+    });
+  keys
+    .command("bulk")
+    .description("Apply one state change to several API keys atomically.")
+    .addArgument(choiceArgument("<action>", "state change to apply", KEY_BULK_ACTIONS))
+    .argument("<id...>", "API key ids")
+    .action(async (action: string, ids: string[], _opts: unknown, cmd: Command) => {
+      validateKeysBulkInput(action, ids);
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await keysBulkData(ctx, action, ids));
+      else console.log(await keysBulk(ctx, action, ids));
+    });
+
+  const models = program
+    .command("models")
+    .description("Manage model configuration and authentication.")
+    .action(helpOnlyAction("dharta models"));
+  const modelConnections = models
+    .command("auth")
+    .description("Manage model provider connections.")
+    .action(helpOnlyAction("dharta models auth"));
+  modelConnections
     .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));
+      if (isJson(cmd)) printJson(await modelConnectionsListData(ctx));
+      else console.log(await modelConnectionsList(ctx));
     });
-  modelKeys
+  modelConnections
     .command("create")
     .description("Store an encrypted model provider credential.")
-    .addArgument(choiceArgument("<provider>", "provider", ["anthropic", "openai", "bedrock", "vertex", "openrouter", "xai", "google"]))
+    .addArgument(choiceArgument("<provider>", "provider", MODEL_CONNECTION_PROVIDERS))
     .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("--slug <slug>", "Connector slug used by --connector and model references (default: derived from the name)")
     .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: {
+    .action(async (provider: ModelConnectionProvider, name: string, opts: {
       key?: string;
       keyStdin?: boolean;
-      authType?: string;
+      slug?: string;
       endpointUrl?: string;
       apiFormat?: string;
     }, cmd: Command) => {
-      validateModelKeysCreateOptions(provider, name, opts);
-      const preparedOpts = await prepareModelKeysCreateOptions(provider, name, opts);
+      validateModelConnectionsCreateOptions(provider, name, opts);
+      const preparedOpts = await prepareModelConnectionsCreateOptions(provider, name, opts);
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await modelConnectionsCreateData(ctx, provider, name, preparedOpts));
+      else console.log(await modelConnectionsCreate(ctx, provider, name, preparedOpts));
+    });
+  modelConnections
+    .command("rotate <id|slug>")
+    .description("Replace a connector's stored credential, keeping its slug and every selection that names it.")
+    .option("--key <plaintext>", "New provider API key plaintext")
+    .option("--key-stdin", "Read the new provider API key plaintext from stdin")
+    .option("--name <name>", "Rename the connector while rotating it")
+    .action(async (reference: string, opts: ModelConnectionRotateOptions, cmd: Command) => {
+      validateModelConnectionsRotateOptions(reference, opts);
+      const preparedOpts = await prepareModelConnectionsRotateOptions(reference, opts);
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await modelConnectionsRotateData(ctx, reference, preparedOpts));
+      else console.log(await modelConnectionsRotate(ctx, reference, preparedOpts));
+    });
+  modelConnections
+    .command("models <id|slug>")
+    .description("Show the models a connector serves, or replace its enabled set and default.")
+    .option("--enable <models>", "Comma-separated model ids to enable; this replaces the whole enabled set")
+    .option("--enable-stdin", "Read the model ids to enable from stdin")
+    .option("--default <model>", "Connector default model; must be in the enabled set")
+    .option("--clear-default", "Leave the connector with no default model")
+    .action(async (reference: string, opts: ModelConnectionModelsOptions, cmd: Command) => {
+      validateModelConnectionsModelsOptions(reference, opts);
+      if (!modelConnectionsModelsWritesOffers(opts)) {
+        validateModelConnectionReference(reference);
+        const readCtx = await buildContext();
+        if (isJson(cmd)) printJson(await modelConnectionsModelsData(readCtx, reference));
+        else console.log(await modelConnectionsModels(readCtx, reference));
+        return;
+      }
+      const preparedOpts = await prepareModelConnectionsModelsOptions(reference, opts);
       const ctx = await buildContext();
-      if (isJson(cmd)) printJson(await modelKeysCreateData(ctx, provider, name, preparedOpts));
-      else console.log(await modelKeysCreate(ctx, provider, name, preparedOpts));
+      if (isJson(cmd)) printJson(await modelConnectionsConfigureModelsData(ctx, reference, preparedOpts));
+      else console.log(await modelConnectionsConfigureModels(ctx, reference, preparedOpts));
     });
-  modelKeys
-    .command("revoke <id>")
+  modelConnections
+    .command("revoke <id|slug>")
     .description("Revoke a model provider credential.")
-    .action(async (id: string, _opts: unknown, cmd: Command) => {
-      validateModelKeyId(id);
+    .action(async (reference: string, _opts: unknown, cmd: Command) => {
+      validateModelConnectionReference(reference);
       const ctx = await buildContext();
-      if (isJson(cmd)) printJson(await modelKeysRevokeData(ctx, id));
-      else console.log(await modelKeysRevoke(ctx, id));
+      if (isJson(cmd)) printJson(await modelConnectionsRevokeData(ctx, reference));
+      else console.log(await modelConnectionsRevoke(ctx, reference));
+    });
+
+  const org = program
+    .command("org")
+    .description("Manage organization settings.")
+    .action(helpOnlyAction("dharta org"));
+  const orgModel = org
+    .command("model")
+    .description("Show the organization connector order, model reference, parameters, and what they resolve to.")
+    .action(async (_opts: unknown, cmd: Command) => {
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await orgModelShowData(ctx));
+      else console.log(await orgModelShow(ctx));
+    });
+  orgModel
+    .command("set")
+    .description("Update the organization connector order, model reference, endpoint override, and portable model parameters.")
+    .option("--connector <slugs>", "Ordered connector slugs from `dharta models auth list`, or an empty string to unset")
+    .option("--model-ref <reference>", "Model reference: <model>, connector:<slug>/<model>, or an empty string to unset")
+    .option("--endpoint-url <url>", "Public HTTPS endpoint to call instead of the provider's standard API, or an empty string to clear")
+    .addOption(choiceOption("--endpoint-kind <kind>", "Wire protocol for --endpoint-url", ORG_ENDPOINT_KINDS))
+    .option("--temperature <number>", "Sampling temperature from 0 to 2")
+    .option("--clear-temperature", "Clear the organization temperature")
+    .option("--top-p <number>", "Nucleus sampling probability above 0 and at most 1")
+    .option("--clear-top-p", "Clear the organization top-p")
+    .option("--max-output-tokens <number>", "Positive output token limit")
+    .option("--clear-max-output-tokens", "Clear the organization output token limit")
+    .addOption(choiceOption("--reasoning-effort <level>", "Reasoning effort", ["low", "medium", "high"]))
+    .option("--clear-reasoning-effort", "Clear the organization reasoning effort")
+    .action(async (opts: OrgModelSetOptions, cmd: Command) => {
+      validateOrgModelSetOptions(opts);
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await orgModelSetData(ctx, opts));
+      else console.log(await orgModelSet(ctx, opts));
+    });
+
+  org
+    .command("rename <name>")
+    .description("Change the organization display name. The slug never changes.")
+    .action(async (name: string, _opts: unknown, cmd: Command) => {
+      normalizeOrganizationName(name);
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await orgRenameData(ctx, name));
+      else console.log(await orgRename(ctx, name));
+    });
+  org
+    .command("support-access <state>")
+    .description(`Allow or block Dharta support access to session content. ${STATE_HELP}`)
+    .action(async (state: string, _opts: unknown, cmd: Command) => {
+      const allowed = parseOnOff(state, "state");
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await orgSupportAccessData(ctx, allowed));
+      else console.log(await orgSupportAccess(ctx, allowed));
+    });
+  org
+    .command("transcript-access <state>")
+    .description(`Allow or block API keys from reading end-user transcripts. ${STATE_HELP}`)
+    .action(async (state: string, _opts: unknown, cmd: Command) => {
+      const enabled = parseOnOff(state, "state");
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await orgTranscriptAccessData(ctx, enabled));
+      else console.log(await orgTranscriptAccess(ctx, enabled));
     });
 
   const members = program.command("members").description("Manage organization members.").action(helpOnlyAction("dharta members"));
@@ -840,7 +1111,7 @@ export function buildProgram(): Command {
     .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>");
+        throw new CliUsageError("--role is required. Usage: dharta members invite <email> --role <role>");
       }
       validateMembersInviteInput(email);
       const ctx = await buildContext();
@@ -853,7 +1124,7 @@ export function buildProgram(): Command {
     .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>");
+        throw new CliUsageError("--role is required. Usage: dharta members set-role <id> --role <role>");
       }
       parsePositiveInteger(id, "member id");
       const ctx = await buildContext();
@@ -869,6 +1140,35 @@ export function buildProgram(): Command {
       if (isJson(cmd)) printJson(await membersRemoveData(ctx, id));
       else console.log(await membersRemove(ctx, id));
     });
+  members
+    .command("revoke-invitation <id>")
+    .description("Revoke a pending invitation.")
+    .action(async (id: string, _opts: unknown, cmd: Command) => {
+      parsePositiveInteger(id, "invitation id");
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await membersRevokeInvitationData(ctx, id));
+      else console.log(await membersRevokeInvitation(ctx, id));
+    });
+  members
+    .command("resend-invitation <id>")
+    .description("Re-send a pending invitation, keeping the original link.")
+    .action(async (id: string, _opts: unknown, cmd: Command) => {
+      parsePositiveInteger(id, "invitation id");
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await membersResendInvitationData(ctx, id));
+      else console.log(await membersResendInvitation(ctx, id));
+    });
+
+  const repos = program.command("repos").description("Manage hosted source repositories.").action(helpOnlyAction("dharta repos"));
+  repos
+    .command("disconnect-github <slug>")
+    .description("Stop a GitHub repository from producing releases. Live releases are untouched.")
+    .action(async (slug: string, _opts: unknown, cmd: Command) => {
+      validateAgentSlug(slug, "source repo slug");
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await reposDisconnectGithubData(ctx, slug));
+      else console.log(await reposDisconnectGithub(ctx, slug));
+    });
 
   const kartas = program.command("kartas").description("Manage durable kartas and virtual employees.").action(helpOnlyAction("dharta kartas"));
   kartas
@@ -993,12 +1293,31 @@ export function buildProgram(): Command {
     .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>");
+        throw new CliUsageError("--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("share <id>")
+    .description("Mint a no-sign-in link to a karta and reveal it once.")
+    .action(async (id: string, _opts: unknown, cmd: Command) => {
+      normalizeNonBlank(id, "karta id");
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await kartaShareData(ctx, id));
+      else console.log(await kartaShare(ctx, id));
+    });
+  kartas
+    .command("unshare <id> <share-id>")
+    .description("Revoke a karta share link.")
+    .action(async (id: string, shareId: string, _opts: unknown, cmd: Command) => {
+      normalizeNonBlank(id, "karta id");
+      normalizeNonBlank(shareId, "share id");
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await kartaUnshareData(ctx, id, shareId));
+      else console.log(await kartaUnshare(ctx, id, shareId));
+    });
   kartas
     .command("revoke <id> <membership-id>")
     .description("Remove a person's access to a dharta.")
@@ -1210,7 +1529,7 @@ export function buildProgram(): Command {
       else console.log(await appearanceGet(ctx, resolved));
     });
   appearanceOpts(appearance.command("set"))
-    .description("Merge appearance JSON from a local file.")
+    .description("Merge appearance JSON from a local file. A token set to null in the file is cleared and falls back to the preset.")
     .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);
@@ -1342,6 +1661,232 @@ export function buildProgram(): Command {
       else console.log(await directorySessions(ctx, resolved));
     });
 
+  // `fleet` mirrors the fleet console's write side. Reads live under
+  // `directories` and `analytics`; everything here changes something.
+  const fleet = program.command("fleet").description("Run fleet-wide changes, triage, and exports.").action(helpOnlyAction("dharta fleet"));
+
+  const fleetOperations = fleet.command("operations").description("Preview and apply bulk fleet changes.").action(helpOnlyAction("dharta fleet operations"));
+  fleetOperations
+    .command("create")
+    .description("Freeze a selection into a draft operation. Nothing is applied until you confirm it.")
+    .option("--action <key>", "Action to run, for example set_lifecycle or pause_serving")
+    .option("--entity-type <type>", `Entity type (${FLEET_ENTITY_TYPES.join(", ")})`)
+    .option("--selection-mode <mode>", `How targets are chosen (${FLEET_SELECTION_MODES.join(", ")})`)
+    .option("--id <id...>", "Target row id; repeat for more")
+    .option("--saved-view <id>", "Take the targets from a saved view")
+    .option("--filter <query>", "Take the targets from a catalog filter")
+    .option("--param <key=value...>", "Action parameter; repeat for more")
+    .action(async (opts: OperationCreateOptions, cmd: Command) => {
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await fleetOperationCreateData(ctx, opts));
+      else console.log(await fleetOperationCreate(ctx, opts));
+    });
+  fleetOperations
+    .command("confirm <id>")
+    .description("Apply a draft operation. Needs fleet:operations:write.")
+    .option("--phrase <phrase>", "The confirmation phrase the draft returned")
+    .action(async (id: string, opts: { phrase?: string }, cmd: Command) => {
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await fleetOperationConfirmData(ctx, id, opts.phrase));
+      else console.log(await fleetOperationConfirm(ctx, id, opts.phrase));
+    });
+  fleetOperations
+    .command("cancel <id>")
+    .description("Stop an operation's remaining targets. Needs fleet:operations:write.")
+    .action(async (id: string, _opts: unknown, cmd: Command) => {
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await fleetOperationCancelData(ctx, id));
+      else console.log(await fleetOperationCancel(ctx, id));
+    });
+  fleetOperations
+    .command("retry <id>")
+    .description("Requeue only the failed targets. Needs fleet:operations:write.")
+    .action(async (id: string, _opts: unknown, cmd: Command) => {
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await fleetOperationRetryData(ctx, id));
+      else console.log(await fleetOperationRetry(ctx, id));
+    });
+
+  const fleetRollouts = fleet.command("rollouts").description("Drive a staged release rollout.").action(helpOnlyAction("dharta fleet rollouts"));
+  // Every rollout verb needs fleet:operations:write, not just the two the
+  // console gates with a step-up: pausing or resuming a release mid-flight
+  // moves live releases the same way advancing it does.
+  for (const [verb, description] of [
+    ["advance", "Move the rollout to its next ring. Needs fleet:operations:write."],
+    ["pause", "Hold the rollout where it is. Needs fleet:operations:write."],
+    ["resume", "Resume a paused rollout. Needs fleet:operations:write."],
+    [
+      "evaluate",
+      "Run the health evaluation now instead of waiting for the window. Needs fleet:operations:write.",
+    ],
+  ] as const) {
+    fleetRollouts
+      .command(`${verb} <id>`)
+      .description(description)
+      .action(async (id: string, _opts: unknown, cmd: Command) => {
+        const ctx = await buildContext();
+        if (isJson(cmd)) printJson(await fleetRolloutData(ctx, verb, id));
+        else console.log(await fleetRollout(ctx, verb, id));
+      });
+  }
+  fleetRollouts
+    .command("rollback <id>")
+    .description("Revert every target to the previous release. Needs fleet:operations:write.")
+    .action(async (id: string, _opts: unknown, cmd: Command) => {
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await fleetRolloutRollbackData(ctx, id));
+      else console.log(await fleetRolloutRollback(ctx, id));
+    });
+
+  const fleetFindings = fleet.command("findings").description("Triage anomaly findings.").action(helpOnlyAction("dharta fleet findings"));
+  for (const [verb, description] of [
+    ["acknowledge", "Take ownership of a finding."],
+    ["resolve", "Close a finding."],
+    ["reopen", "Reopen a resolved or snoozed finding."],
+    ["promote", "Raise a finding to an incident."],
+  ] as const) {
+    fleetFindings
+      .command(`${verb} <id>`)
+      .description(description)
+      .action(async (id: string, _opts: unknown, cmd: Command) => {
+        const ctx = await buildContext();
+        if (isJson(cmd)) printJson(await fleetFindingData(ctx, verb, id));
+        else console.log(await fleetFinding(ctx, verb, id));
+      });
+  }
+  fleetFindings
+    .command("snooze <id>")
+    .description("Hide a finding until the window is up.")
+    .option("--duration <window>", `Snooze window (${FLEET_SNOOZE_DURATIONS.join(", ")})`)
+    .action(async (id: string, opts: SnoozeOptions, cmd: Command) => {
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await fleetFindingSnoozeData(ctx, id, opts));
+      else console.log(await fleetFindingSnooze(ctx, id, opts));
+    });
+  fleetFindings
+    .command("classify <id>")
+    .description("Record what a finding turned out to be.")
+    .option("--as <classification>", "Classification to record")
+    .action(async (id: string, opts: ClassifyOptions, cmd: Command) => {
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await fleetFindingClassifyData(ctx, id, opts));
+      else console.log(await fleetFindingClassify(ctx, id, opts));
+    });
+  fleetFindings
+    .command("assign <id>")
+    .description("Assign a finding to a member, or clear the owner.")
+    .option("--membership-id <id>", "Organization membership id to assign")
+    .option("--unassign", "Clear the current owner")
+    .action(async (id: string, opts: AssignOptions, cmd: Command) => {
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await fleetFindingAssignData(ctx, id, opts));
+      else console.log(await fleetFindingAssign(ctx, id, opts));
+    });
+  fleetFindings
+    .command("update <id>")
+    .description("Set or clear a finding's runbook link.")
+    .option("--runbook-url <url>", "Runbook URL; pass an empty string to clear")
+    .action(async (id: string, opts: RunbookOptions, cmd: Command) => {
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await fleetFindingUpdateData(ctx, id, opts));
+      else console.log(await fleetFindingUpdate(ctx, id, opts));
+    });
+
+  const fleetViews = fleet.command("views").description("Manage saved fleet views.").action(helpOnlyAction("dharta fleet views"));
+  const viewWriteOpts = (cmd: ReturnType<typeof fleetViews.command>) =>
+    cmd
+      .option("--entity-type <type>", "Entity type the view lists")
+      .option("--name <name>", "View name")
+      .option("--definition <json>", "Filters, columns and sort, as a JSON object")
+      .option("--description <text>", "What the view is for")
+      .option("--visibility <level>", `Who can see it (${FLEET_VIEW_VISIBILITIES.join(", ")})`)
+      .option("--team-id <id>", "Owning team, for team visibility")
+      .option("--organization-default", "Make it the organization's default view");
+  viewWriteOpts(fleetViews.command("create"))
+    .description("Create a saved view.")
+    .action(async (opts: ViewWriteOptions, cmd: Command) => {
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await fleetViewCreateData(ctx, opts));
+      else console.log(await fleetViewCreate(ctx, opts));
+    });
+  viewWriteOpts(fleetViews.command("update <id>"))
+    .description("Change a saved view.")
+    .action(async (id: string, opts: ViewWriteOptions, cmd: Command) => {
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await fleetViewUpdateData(ctx, id, opts));
+      else console.log(await fleetViewUpdate(ctx, id, opts));
+    });
+  fleetViews
+    .command("delete <id>")
+    .alias("rm")
+    .description("Delete a saved view.")
+    .action(async (id: string, _opts: unknown, cmd: Command) => {
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await fleetViewDeleteData(ctx, id));
+      else console.log(await fleetViewDelete(ctx, id));
+    });
+  fleetViews
+    .command("favorite <id>")
+    .description("Favorite a saved view for the key's owner.")
+    .action(async (id: string, _opts: unknown, cmd: Command) => {
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await fleetViewFavoriteData(ctx, id));
+      else console.log(await fleetViewFavorite(ctx, id));
+    });
+  fleetViews
+    .command("unfavorite <id>")
+    .description("Remove a saved view from the key owner's favorites.")
+    .action(async (id: string, _opts: unknown, cmd: Command) => {
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await fleetViewUnfavoriteData(ctx, id));
+      else console.log(await fleetViewUnfavorite(ctx, id));
+    });
+
+  const fleetAnalytics = fleet.command("analytics").description("Save and unpin Analytics charts.").action(helpOnlyAction("dharta fleet analytics"));
+  fleetAnalytics
+    .command("save")
+    .description("Save an explorer chart and pin it to your Analytics list.")
+    .option("--name <name>", "Chart name")
+    .option("--metric <metric>", "Metric to chart. Defaults to turns.")
+    .option("--description <text>", "What the chart shows")
+    .option("--range <range>", "Time range, for example 30d")
+    .option("--starts-at <timestamp>", "Custom range start")
+    .option("--ends-at <timestamp>", "Custom range end")
+    .option("--scope-kind <kind>", "Scope the chart to a kind of row")
+    .option("--scope-ids <ids>", "Comma-separated scope ids")
+    .option("--bucket <bucket>", "Time bucket, for example day")
+    .option("--aggregation <aggregation>", "How values are combined")
+    .option("--comparison <comparison>", "Comparison series to draw")
+    .option("--comparison-saved-view <id>", "Saved cohort to compare against")
+    .option("--breakdown <field...>", "Break the series down by a field; repeat for more")
+    .option("--event <type...>", "Event type to include; repeat for more")
+    .option("--filter <key=value...>", "Filter; repeat for more")
+    .action(async (opts: AnalyticsSaveOptions, cmd: Command) => {
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await fleetAnalyticsSaveData(ctx, opts));
+      else console.log(await fleetAnalyticsSave(ctx, opts));
+    });
+  fleetAnalytics
+    .command("unpin <id>")
+    .description("Remove a chart from your Analytics list. The saved view survives.")
+    .action(async (id: string, _opts: unknown, cmd: Command) => {
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await fleetAnalyticsUnpinData(ctx, id));
+      else console.log(await fleetAnalyticsUnpin(ctx, id));
+    });
+
+  const fleetExports = fleet.command("exports").description("Export catalog rows as CSV.").action(helpOnlyAction("dharta fleet exports"));
+  fleetExports
+    .command("create")
+    .description("Write the named rows to stdout as CSV.")
+    .option("--entity-type <type>", `Entity type (${FLEET_ENTITY_TYPES.join(", ")})`)
+    .option("--id <id...>", "Row id to export; repeat for more")
+    .action(async (opts: ExportCreateOptions, cmd: Command) => {
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await fleetExportCreateData(ctx, opts));
+      else console.log(await fleetExportCreate(ctx, opts));
+    });
+
   const webhooks = program.command("webhooks").description("Manage webhook endpoints.").action(helpOnlyAction("dharta webhooks"));
   webhooks
     .command("list")
@@ -1384,6 +1929,15 @@ export function buildProgram(): Command {
       if (isJson(cmd)) printJson(await webhooksEnableData(ctx, id));
       else console.log(await webhooksEnable(ctx, id));
     });
+  webhooks
+    .command("test <id>")
+    .description("Send one test event through the real delivery path.")
+    .action(async (id: string, _opts: unknown, cmd: Command) => {
+      normalizeNonBlank(id, "Webhook endpoint id");
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await webhooksTestData(ctx, id));
+      else console.log(await webhooksTest(ctx, id));
+    });
   webhooks
     .command("delete <id>")
     .alias("rm")
@@ -1438,6 +1992,7 @@ export function buildProgram(): Command {
     .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")
+    .addOption(choiceOption("--model-auth <method>", "Anthropic authentication: api-key or claude", DEV_MODEL_AUTH_VALUES))
     .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)")
@@ -1451,6 +2006,7 @@ export function buildProgram(): Command {
           user?: string;
           port?: string;
           verbose?: boolean;
+          modelAuth?: DevModelAuth;
           release?: string;
           env?: string;
           includeSecrets?: boolean;
@@ -1461,7 +2017,7 @@ export function buildProgram(): Command {
       ) => {
         rejectJson(cmd, "dharta dev");
         if (pathArg !== undefined && opts.dir !== undefined) {
-          throw new Error("Use either [path] or --dir, not both.");
+          throw new CliUsageError("Use either [path] or --dir, not both.");
         }
         const dir = pathArg !== undefined
           ? normalizeNonBlank(pathArg, "path")
@@ -1470,7 +2026,7 @@ export function buildProgram(): Command {
             : undefined;
         if (opts.release !== undefined) parseReleaseVersion(opts.release, "--release");
         if (opts.includeSecrets && opts.env !== "remote") {
-          throw new Error("--include-secrets requires --env remote.");
+          throw new CliUsageError("--include-secrets requires --env remote.");
         }
         validateAgentSelectorOptions({ agent: opts.agent, project: opts.project });
         await devCmd({
@@ -1478,6 +2034,7 @@ export function buildProgram(): Command {
           message: opts.message,
           user: opts.user,
           verbose: opts.verbose,
+          modelAuth: opts.modelAuth,
           port: opts.port ? parsePort(opts.port) : undefined,
           release: opts.release,
           envRemote: opts.env === "remote",
@@ -1488,6 +2045,7 @@ export function buildProgram(): Command {
     );
 
   registerArtifactCommands(program);
+  registerGenuiCommands(program);
 
   const sessionsOpts = <T extends Command>(cmd: T): T =>
     cmd
@@ -1809,9 +2367,8 @@ export function buildProgram(): Command {
     .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("--connector <slugs>", "Ordered connection slugs from `dharta models auth list`; use karta for the platform connection or an empty string to inherit")
+    .option("--model-ref <reference>", "Model reference: <model>, connector:<slug>/<model>, or an empty string for the connector default")
     .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")
@@ -1896,6 +2453,132 @@ export function buildProgram(): Command {
       if (isJson(cmd)) printJson(await agentsWorkspaceAccessSetData(ctx, resolved, patch));
       else console.log(await agentsWorkspaceAccessSet(ctx, resolved, patch));
     });
+  agent
+    .command("rename <name> [slug]")
+    .description("Change an agent's display name; the slug stays as it is.")
+    .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 (
+      name: string,
+      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 agentsRenameData(ctx, resolved, name));
+      else console.log(await agentsRename(ctx, resolved, name));
+    });
+  agent
+    .command("durable-workspace <state> [slug]")
+    .description(
+      `Enable or disable the durable workspace for an agent's kartas - a cost setting, since durable storage is billed per GB. ${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 agentsDurableWorkspaceSetData(ctx, resolved, enabled));
+      else console.log(await agentsDurableWorkspaceSet(ctx, resolved, enabled));
+    });
+  agent
+    .command("create [name]")
+    .description(
+      "Create a hosted agent, or link an installed GitHub repository as its source with --github-repo. `dharta create` scaffolds locally instead.",
+    )
+    .option("--slug <slug>", "Agent or source-repo slug (default: derived from the name or repository)")
+    .option(
+      "--github-repo <repo>",
+      "Installed GitHub repository to link as the source of truth, by id or owner/name (see `dharta agent github-repos`)",
+    )
+    .option("--branch <branch>", "Deploy branch for the linked repository; needs --github-repo")
+    .action(async (name: string | undefined, _opts: AgentCreateOptions, cmd: Command) => {
+      const opts = commandOpts<AgentCreateOptions>(cmd);
+      validateAgentCreateInput(name, opts);
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await agentsCreateData(ctx, name, opts));
+      else console.log(await agentsCreate(ctx, name, opts));
+    });
+  agent
+    .command("github-repos")
+    .description("List the GitHub repositories the Dharta App is installed on, with the ids `--github-repo` takes.")
+    .action(async (_opts: Record<string, never>, cmd: Command) => {
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await agentsGithubReposData(ctx));
+      else console.log(await agentsGithubRepos(ctx));
+    });
+  agent
+    .command("create-from-template <template> <name>")
+    .description(
+      "Create a hosted agent from a built-in template and publish its first release. `dharta create` scaffolds locally instead.",
+    )
+    .option("--slug <slug>", "Agent slug (default: derived from the name)")
+    .option("--description <text>", "Short description")
+    .option("--harness <type>", "Harness slug (default: Dharta's curated default)")
+    .option("--harness-version <version>", "Harness version; needs --harness")
+    .action(async (
+      template: string,
+      name: string,
+      _opts: AgentCreateFromTemplateOptions,
+      cmd: Command,
+    ) => {
+      const opts = commandOpts<AgentCreateFromTemplateOptions>(cmd);
+      validateAgentCreateFromTemplateInput(template, name, opts);
+      const ctx = await buildContext();
+      if (isJson(cmd)) printJson(await agentsCreateFromTemplateData(ctx, template, name, opts));
+      else console.log(await agentsCreateFromTemplate(ctx, template, name, opts));
+    });
+  agent
+    .command("redeploy [slug]")
+    .description("Re-sync a GitHub-connected agent and rebuild it from deploy-branch HEAD.")
+    .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 agentsRedeployData(ctx, resolved));
+      else console.log(await agentsRedeploy(ctx, resolved));
+    });
+  agent
+    .command("retry <version> [slug]")
+    .description("Retry a failed browser-created release; it republishes as the next version.")
+    .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 (
+      version: string,
+      slugArg: 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, slugArg);
+      const ctx = await buildContext();
+      const resolved = resolvedOpts.agent;
+      if (isJson(cmd)) printJson(await agentsRetryReleaseData(ctx, resolved, version));
+      else console.log(await agentsRetryRelease(ctx, resolved, version));
+    });
   agent
     .command("delete [slug]")
     .description("Archive an agent.")
@@ -1943,7 +2626,7 @@ export function buildProgram(): Command {
         // owner of target/config resolution and can narrate legacy inference.
         const mode = rawMode ?? (await inferMode(dir));
         if (opts.reconcileSource && mode !== "git") {
-          throw new Error(
+          throw new CliUsageError(
             "--reconcile-source is only valid for git deploys. " +
               "Remove it, or use `--mode git` to reconcile Dharta's hosted source branch.",
           );
@@ -1951,7 +2634,7 @@ export function buildProgram(): Command {
         // 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(
+          throw new CliUsageError(
             "--json is only supported for `dharta deploy --mode folder`; git deploy streams git push output. Run `dharta deploy` without --json or pass `--mode folder`.",
           );
         }
@@ -1978,7 +2661,7 @@ export function buildProgram(): 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.");
+        throw new CliUsageError("`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;
@@ -1986,7 +2669,7 @@ export function buildProgram(): Command {
       try {
         ctx = await buildContext();
       } catch (err) {
-        if (!isNotLoggedInError(err)) throw err;
+        if (!isNotAuthenticatedError(err)) throw err;
         authMessage = err instanceof Error ? err.message : String(err);
       }
       if (isJson(cmd)) printJson(await statusData(ctx, { dir: opts.dir, authMessage }));
@@ -2062,26 +2745,151 @@ export function buildProgram(): Command {
   // commands and help-only command groups keep a hidden parser option
   // because they reject --json.
   for (const cmd of allCommands(program)) {
+    const jq = new Option("--jq <expr>", "Filter the JSON result through jq (implies --json)");
     if (hidesJsonHelp(cmd)) {
       cmd.addOption(new Option("--json", "Print the result as JSON (machine-readable)").hideHelp());
+      cmd.addOption(jq.hideHelp());
     } else {
       cmd.option("--json", jsonHelpDescription(cmd));
+      cmd.addOption(jq);
     }
+    // --profile rides the same mechanic: registered on every node so the flag
+    // parses wherever it appears on the line, read back through
+    // optsWithGlobals(). Hidden on the pure command groups, which only print
+    // help and never resolve a credential.
+    const profile = new Option(
+      "--profile <name>",
+      "Profile in ~/.dharta/config.toml to use (env: DHARTA_PROFILE)",
+    );
+    if (HELP_ONLY_COMMAND_PATHS.has(commandPath(cmd)) && cmd.parent !== null) profile.hideHelp();
+    cmd.addOption(profile);
+    // --idempotency-key rides the same mechanic for the same reason: it has to
+    // parse wherever it sits on the line, and one flag has to reach every
+    // request the run makes. Hidden on the help-only groups, which issue none.
+    const idempotencyKey = new Option(
+      "--idempotency-key <key>",
+      "Send this Idempotency-Key on every request the command makes",
+    );
+    if (HELP_ONLY_COMMAND_PATHS.has(commandPath(cmd)) && cmd.parent !== null) idempotencyKey.hideHelp();
+    cmd.addOption(idempotencyKey);
   }
+
+  // One place decides the active profile for the whole run. preAction hooks are
+  // inherited by every subcommand, so this fires exactly once, before the
+  // action, with the flag resolved from wherever it sat on the command line.
+  program.hook("preAction", async (_thisCommand, actionCommand) => {
+    const opts = actionCommand.optsWithGlobals();
+    setRequestedProfile(opts.profile as string | undefined);
+    rejectNonMutatingIdempotencyKey(actionCommand, opts.idempotencyKey as string | undefined);
+    setRequestedIdempotencyKey(opts.idempotencyKey as string | undefined);
+    resetJsonPayload();
+    // Compile the filter before the action runs, so a typo costs nothing.
+    await armJqFilter(opts.jq as string | undefined);
+  });
+
+  // The filtered payload is written after the action resolves. postAction runs
+  // for every entry point (parseAsync from the bin, or straight from a test),
+  // and does not run when the action threw - which is right, because a failed
+  // command has no payload to filter.
+  program.hook("postAction", async () => {
+    await flushJsonPayload();
+  });
+  assignTopLevelHelpGroups(program);
   installMissingArgumentChoiceHints(program);
   installTopLevelUnknownCommandGuard(program);
+  installExitOverride(program);
 
   return program;
 }
 
-function isNotLoggedInError(err: unknown): boolean {
-  return err instanceof Error && /^Not logged in\./.test(err.message);
+// The root help used to carry a hand-written, hand-ordered list of commands in
+// addHelpText, with commander's own list suppressed - two surfaces to keep in
+// step, and the list drifted (`files` and `artifact` were never in it).
+// Commander 15 groups natively, so the groups are declared here, on the tree,
+// and both `dharta --help` and the generated docs reference read them from it.
+export const TOP_LEVEL_HELP_GROUPS = [
+  ["Setup and auth", ["login", "auth", "whoami", "create", "setup"]],
+  ["Local and deploy", ["dev", "deploy", "status", "rollback", "logs"]],
+  ["Runtime operations", ["open", "sessions", "session", "ps", "send", "files", "artifact", "schedules"]],
+  ["Agent configuration", ["agent", "env", "appearance", "genui"]],
+  [
+    "Management",
+    [
+      "usage",
+      "analytics",
+      "directories",
+      "fleet",
+      "kartas",
+      "caps",
+      "embed-keys",
+      "webhooks",
+      "audit-log",
+      "keys",
+      "models",
+      "org",
+      "members",
+      "repos",
+      "api",
+    ],
+  ],
+  ["Utilities", ["doctor", "update", "completion"]],
+] as const satisfies ReadonlyArray<readonly [string, readonly string[]]>;
+
+function assignTopLevelHelpGroups(program: Command): void {
+  const order = new Map<string, number>();
+  for (const [group, names] of TOP_LEVEL_HELP_GROUPS) {
+    for (const name of names) {
+      const cmd = program.commands.find((candidate) => candidate.name() === name);
+      if (!cmd) {
+        throw new Error(`Help group '${group}' names '${name}', which is not a top-level command.`);
+      }
+      cmd.helpGroup(`${group}:`);
+      order.set(name, order.size);
+    }
+  }
+  // Commander discovers group headings in registration order, so the array
+  // itself has to be in group order for the help to read top to bottom.
+  // Ungrouped (hidden) commands keep their place at the end. The array is
+  // typed readonly but is the live list commander renders from, so sorting it
+  // is the ordering hook - there is no public setter.
+  (program.commands as Command[]).sort(
+    (a, b) => (order.get(a.name()) ?? Number.MAX_SAFE_INTEGER) - (order.get(b.name()) ?? Number.MAX_SAFE_INTEGER),
+  );
+}
+
+// Commander calls process.exit(1) itself for a bad flag, which flattens every
+// usage mistake into the same code as a failed API call. exitOverride makes it
+// throw instead, so the single catch in the bin block maps it to EXIT_USAGE.
+// The setting is per-command, not inherited, so every node gets it.
+function installExitOverride(program: Command): void {
+  for (const cmd of allCommands(program)) cmd.exitOverride();
 }
 
 export async function main(argv: string[]): Promise<void> {
   await buildProgram().parseAsync(argv);
 }
 
+// The single place a failure turns into an exit status. Returns the code so
+// the bin block can `process.exit` with it; commander has already printed its
+// own message, so only CLI-raised errors are narrated here.
+export function reportCliFailure(err: unknown, write: (line: string) => void = (line) => process.stderr.write(line)): number {
+  const code = exitCodeForError(err);
+  if (!isCommanderError(err)) {
+    const msg = err instanceof Error ? err.message : String(err);
+    write(`dharta: ${msg}${retryAdvice(err)}\n`);
+  }
+  return code;
+}
+
+// A rate-limited response carries how long to wait in `Retry-After`, and the
+// server's own message never repeats it. Without this the user is told they
+// were throttled and left to guess for how long.
+function retryAdvice(err: unknown): string {
+  const seconds = (err as { retryAfterSeconds?: unknown })?.retryAfterSeconds;
+  if (typeof seconds !== "number" || !Number.isFinite(seconds) || seconds < 0) return "";
+  return ` Retry after ${seconds} seconds.`;
+}
+
 function allCommands(root: Command): Command[] {
   const out: Command[] = [];
   const visit = (cmd: Command): void => {
@@ -2098,8 +2906,11 @@ function hidesJsonHelp(cmd: Command): boolean {
     "dharta auth",
     "dharta analytics",
     "dharta keys",
-    "dharta model-keys",
+    "dharta models",
+    "dharta models auth",
+    "dharta org",
     "dharta members",
+    "dharta repos",
     "dharta embed-keys",
     "dharta caps",
     "dharta appearance",
@@ -2108,6 +2919,7 @@ function hidesJsonHelp(cmd: Command): boolean {
     "dharta webhooks",
     "dharta env",
     "dharta agent",
+    "dharta genui",
     "dharta git-credential",
     "dharta dev",
     "dharta logs",
@@ -2141,8 +2953,11 @@ const HELP_ONLY_COMMAND_PATHS = new Set([
   "dharta auth",
   "dharta analytics",
   "dharta keys",
-  "dharta model-keys",
+  "dharta models",
+  "dharta models auth",
+  "dharta org",
   "dharta members",
+  "dharta repos",
   "dharta embed-keys",
   "dharta caps",
   "dharta caps budget",
@@ -2152,6 +2967,7 @@ const HELP_ONLY_COMMAND_PATHS = new Set([
   "dharta webhooks",
   "dharta env",
   "dharta agent",
+  "dharta genui",
 ]);
 
 function rejectUnknownTopLevelCommand(
@@ -2173,8 +2989,9 @@ function rejectUnknownTopLevelCommand(
     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));
+    const child = visibleSubcommands(cursor).find(
+      (cmd) => cmd.name() === token || cmd.aliases().includes(token),
+    );
     if (child) {
       cursor = child as Command;
       continue;
@@ -2265,7 +3082,7 @@ function parseOnOff(value: string, name: string): boolean {
   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(
+  throw new CliUsageError(
     `${name} must be on/off, enabled/disabled, or true/false.` +
       (suggestion ? ` Did you mean ${suggestion}?` : ""),
   );
@@ -2275,7 +3092,7 @@ 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(
+    throw new CliUsageError(
       "No piped input. Usage: echo $DHARTA_API_KEY | dharta login --with-token",
     );
   }
@@ -2283,7 +3100,7 @@ export async function readStdin(): Promise<string> {
   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");
+    throw new CliUsageError("No token on stdin. Usage: echo $DHARTA_API_KEY | dharta login --with-token");
   }
   return token;
 }
@@ -2293,26 +3110,26 @@ function parseVersion(input: string): number {
   try {
     return parseReleaseVersion(input, "version");
   } catch {
-    throw new Error(`Invalid version: ${input.trim()}. Use e.g. v3 or 3.`);
+    throw new CliUsageError(`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");
+    throw new CliUsageError("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 (!normalized) throw new CliUsageError("--port cannot be blank.");
   if (!/^[1-9]\d*$/.test(normalized)) {
-    throw new Error(`--port must be an integer between 1 and 65535.`);
+    throw new CliUsageError(`--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.`);
+    throw new CliUsageError(`--port must be an integer between 1 and 65535.`);
   }
   return port;
 }
@@ -2332,8 +3149,6 @@ const invokedAsBin = (() => {
 })();
 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);
+    process.exit(reportCliFailure(err));
   });
 }