@dharta/cli 0.6.77 → 0.6.78

package/dist/cli.js

@@ -5,7 +5,7 @@ import * as readline from "node:readline";
 import { Argument, Command, InvalidArgumentError, Option } from "commander";
 import { API_KEY_SCOPES } 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 { authLogout, authLogoutData, authStatus, authStatusData, authToken, } from "./commands/auth.js";
@@ -13,18 +13,22 @@ 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, } 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 { 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 { modelConnectionsConfigureModels, modelConnectionsConfigureModelsData, modelConnectionsCreate, modelConnectionsCreateData, modelConnectionsList, modelConnectionsListData, modelConnectionsModels, modelConnectionsModelsData, modelConnectionsModelsWritesOffers, modelConnectionsRevoke, modelConnectionsRevokeData, modelConnectionsRotate, modelConnectionsRotateData, prepareModelConnectionsCreateOptions, prepareModelConnectionsModelsOptions, prepareModelConnectionsRotateOptions, MODEL_API_FORMATS, validateModelConnectionReference, validateModelConnectionsCreateOptions, validateModelConnectionsModelsOptions, validateModelConnectionsRotateOptions, } from "./commands/model-connections.js";
+import { ORG_ENDPOINT_KINDS, orgModelSet, orgModelSetData, orgModelShow, orgModelShowData, validateOrgModelSetOptions, } from "./commands/organization.js";
+import { membersInvite, membersInviteData, membersList, 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, kartaMembersRevoke, kartaMembersRevokeData, kartaMembersSetRole, kartaMembersSetRoleData, kartasArchive, kartasArchiveData, kartasConfigure, kartasConfigureData, kartasRestore, kartasRestoreData, kartasCreate, kartasCreateData, kartasList, kartasListData, kartasName, kartasNameData, kartasShow, kartasShowData, kartaEnvList, kartaEnvListData, kartaEnvSet, kartaEnvSetData, kartaEnvUnset, kartaEnvUnsetData, kartaShare, kartaShareData, kartaUnshare, kartaUnshareData, validateKartaCreateOptions, validateKartaConfigureOptions, validateKartaNameOptions, } from "./commands/kartas.js";
 import { usage as usageCmd, usageData } from "./commands/usage.js";
-import { 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 { 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, agentsReleasesData, agentsShow, agentsShowData, agentsServingSet, agentsServingSetData, agentsWorkspaceInspectableSet, agentsWorkspaceInspectableSetData, agentsWorkspaceAccessShow, agentsWorkspaceAccessShowData, agentsWorkspaceAccessSet, agentsWorkspaceAccessSetData, parseWorkspaceAccessAssignments, validateAgentCreateFromTemplateInput, validateAgentCreateInput, 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 { 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, webhooksCreateData, webhooksDelete, webhooksDeleteData, webhooksEnable, webhooksEnableData, webhooksList, webhooksListData, webhooksTest, webhooksTestData, 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";
@@ -36,6 +40,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, 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";
@@ -43,35 +49,16 @@ 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 } from "./model-auth.js";
 const MEMBER_ROLES = ["owner", "admin", "developer", "billing", "viewer"];
 const DHARTA_ACCESS_AUDIENCES = ["members", "anonymous", "off"];
 const DHARTA_MEMBER_ROLES = ["viewer", "participant", "manager"];
-const MODEL_KEY_AUTH_TYPES = ["api_key", "oauth_subscription"];
-const AGENT_MODEL_SOURCES = ["inherit", "platform"];
 const CLI_API_KEY_SCOPES = API_KEY_SCOPES;
 const STATE_HELP = "State values: on/off, enabled/disabled, true/false.";
-// --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) {
-    return Boolean(cmd.optsWithGlobals().json);
-}
-function printJson(payload) {
-    console.log(JSON.stringify(payload, null, 2));
-}
 function commandOpts(cmd) {
     return cmd.optsWithGlobals();
 }
@@ -80,7 +67,7 @@ function validatePositionalAgentSelector(slug, opts) {
         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.");
     }
 }
 function validateCreateInput(pathArg, opts) {
@@ -104,9 +91,69 @@ async function resolveAgentOptions(opts, positionalSlug) {
     return { ...opts, agent, project: undefined };
 }
 function rejectJson(cmd, name) {
-    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, name) {
+    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) {
+    return NON_MUTATING_COMMAND_PATHS.some((entry) => path === entry || path.startsWith(`${entry} `));
+}
+function rejectNonMutatingIdempotencyKey(cmd, key) {
+    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) {
     return (...args) => {
@@ -121,6 +168,7 @@ function helpOnlyAction(name) {
                 (suggestion ? ` Did you mean \`${suggestion}\`?` : ""));
         }
         rejectJson(cmd, name);
+        rejectIdempotencyKey(cmd, name);
         cmd.outputHelp();
     };
 }
@@ -138,23 +186,12 @@ function closestCommand(input, commands) {
     return closestChoice(input, commands);
 }
 function commandSuggestionTokens(cmd) {
-    return Array.from(new Set(cmd.commands
-        .filter((child) => !child._hidden)
-        .flatMap((child) => [child.name(), ...child.aliases()])));
+    return Array.from(new Set(visibleSubcommands(cmd).flatMap((child) => [child.name(), ...child.aliases()])));
 }
 export function buildProgram() {
     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
@@ -163,51 +200,8 @@ export function buildProgram() {
         .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",
+        "Run `dharta <command> --help` for details. Docs: https://docs.dharta.ai",
     ].join("\n"))
         .action(helpOnlyAction("dharta"));
     program
@@ -216,19 +210,17 @@ export function buildProgram() {
         .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, cmd) => {
         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.
@@ -269,13 +261,14 @@ export function buildProgram() {
     });
     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, cmd) => {
+        .description("Remove the stored credential (the key stays revocable on the dashboard). Removes the default profile unless --profile names another.")
+        .action(async (_opts, cmd) => {
+        // The global --profile names the profile this removes.
+        const profile = requestedProfileName();
         if (isJson(cmd))
-            printJson(await authLogoutData(opts.profile));
+            printJson(await authLogoutData(profile));
         else
-            console.log(await authLogout(opts.profile));
+            console.log(await authLogout(profile));
     });
     program
         .command("create [path]")
@@ -311,7 +304,7 @@ export function buildProgram() {
         .action(async (pathArg, opts, cmd) => {
         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
@@ -369,7 +362,7 @@ export function buildProgram() {
         .action(async (opts, cmd) => {
         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))
@@ -415,7 +408,8 @@ export function buildProgram() {
     });
     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, [])
@@ -482,46 +476,210 @@ export function buildProgram() {
         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, opts, cmd) => {
+        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, _opts, cmd) => {
+        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, _opts, cmd) => {
+        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, ids, _opts, cmd) => {
+        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, cmd) => {
         const ctx = await buildContext();
         if (isJson(cmd))
-            printJson(await modelKeysListData(ctx));
+            printJson(await modelConnectionsListData(ctx));
         else
-            console.log(await modelKeysList(ctx));
+            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, name, opts, cmd) => {
-        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 modelKeysCreateData(ctx, provider, name, preparedOpts));
+            printJson(await modelConnectionsCreateData(ctx, provider, name, preparedOpts));
         else
-            console.log(await modelKeysCreate(ctx, provider, name, preparedOpts));
+            console.log(await modelConnectionsCreate(ctx, provider, name, preparedOpts));
     });
-    modelKeys
-        .command("revoke <id>")
+    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, opts, cmd) => {
+        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, opts, cmd) => {
+        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 modelConnectionsConfigureModelsData(ctx, reference, preparedOpts));
+        else
+            console.log(await modelConnectionsConfigureModels(ctx, reference, preparedOpts));
+    });
+    modelConnections
+        .command("revoke <id|slug>")
         .description("Revoke a model provider credential.")
-        .action(async (id, _opts, cmd) => {
-        validateModelKeyId(id);
+        .action(async (reference, _opts, cmd) => {
+        validateModelConnectionReference(reference);
+        const ctx = await buildContext();
+        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, cmd) => {
+        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, cmd) => {
+        validateOrgModelSetOptions(opts);
         const ctx = await buildContext();
         if (isJson(cmd))
-            printJson(await modelKeysRevokeData(ctx, id));
+            printJson(await orgModelSetData(ctx, opts));
         else
-            console.log(await modelKeysRevoke(ctx, id));
+            console.log(await orgModelSet(ctx, opts));
+    });
+    org
+        .command("rename <name>")
+        .description("Change the organization display name. The slug never changes.")
+        .action(async (name, _opts, cmd) => {
+        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, _opts, cmd) => {
+        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, _opts, cmd) => {
+        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"));
     members
@@ -540,7 +698,7 @@ export function buildProgram() {
         .addOption(choiceOption("--role <role>", "owner, admin, developer, billing, or viewer", MEMBER_ROLES))
         .action(async (email, opts, cmd) => {
         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();
@@ -555,7 +713,7 @@ export function buildProgram() {
         .addOption(choiceOption("--role <role>", "owner, admin, developer, billing, or viewer", MEMBER_ROLES))
         .action(async (id, opts, cmd) => {
         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();
@@ -575,6 +733,40 @@ export function buildProgram() {
         else
             console.log(await membersRemove(ctx, id));
     });
+    members
+        .command("revoke-invitation <id>")
+        .description("Revoke a pending invitation.")
+        .action(async (id, _opts, cmd) => {
+        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, _opts, cmd) => {
+        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, _opts, cmd) => {
+        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
         .command("create <name>")
@@ -720,7 +912,7 @@ export function buildProgram() {
         .addOption(choiceOption("--role <role>", "viewer, participant, or manager", DHARTA_MEMBER_ROLES))
         .action(async (id, membershipId, opts, cmd) => {
         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))
@@ -728,6 +920,29 @@ export function buildProgram() {
         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, _opts, cmd) => {
+        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, shareId, _opts, cmd) => {
+        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.")
@@ -954,7 +1169,7 @@ export function buildProgram() {
             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, cmd) => {
         const opts = commandOpts(cmd);
@@ -1070,6 +1285,262 @@ export function buildProgram() {
         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, cmd) => {
+        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, opts, cmd) => {
+        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, _opts, cmd) => {
+        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, _opts, cmd) => {
+        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.",
+        ],
+    ]) {
+        fleetRollouts
+            .command(`${verb} <id>`)
+            .description(description)
+            .action(async (id, _opts, cmd) => {
+            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, _opts, cmd) => {
+        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."],
+    ]) {
+        fleetFindings
+            .command(`${verb} <id>`)
+            .description(description)
+            .action(async (id, _opts, cmd) => {
+            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, opts, cmd) => {
+        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, opts, cmd) => {
+        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, opts, cmd) => {
+        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, opts, cmd) => {
+        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) => 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, cmd) => {
+        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, opts, cmd) => {
+        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, _opts, cmd) => {
+        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, _opts, cmd) => {
+        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, _opts, cmd) => {
+        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, cmd) => {
+        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, _opts, cmd) => {
+        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, cmd) => {
+        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")
@@ -1120,6 +1591,17 @@ export function buildProgram() {
         else
             console.log(await webhooksEnable(ctx, id));
     });
+    webhooks
+        .command("test <id>")
+        .description("Send one test event through the real delivery path.")
+        .action(async (id, _opts, cmd) => {
+        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")
@@ -1168,6 +1650,7 @@ export function buildProgram() {
         .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)")
@@ -1175,7 +1658,7 @@ export function buildProgram() {
         .action(async (pathArg, opts, cmd) => {
         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")
@@ -1185,7 +1668,7 @@ export function buildProgram() {
         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({
@@ -1193,6 +1676,7 @@ export function buildProgram() {
             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",
@@ -1201,6 +1685,7 @@ export function buildProgram() {
         });
     });
     registerArtifactCommands(program);
+    registerGenuiCommands(program);
     const sessionsOpts = (cmd) => cmd
         .option("-a, --agent <slug>", "Agent slug (default: the agent in this folder)")
         .option("-p, --project <slug>", "Alias of --agent")
@@ -1522,9 +2007,8 @@ export function buildProgram() {
         .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")
@@ -1597,6 +2081,113 @@ export function buildProgram() {
         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, slugArg, _opts, cmd) => {
+        const opts = commandOpts(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, slugArg, _opts, cmd) => {
+        const opts = commandOpts(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, _opts, cmd) => {
+        const opts = commandOpts(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, cmd) => {
+        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, name, _opts, cmd) => {
+        const opts = commandOpts(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, _opts, cmd) => {
+        const opts = commandOpts(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, slugArg, _opts, cmd) => {
+        const opts = commandOpts(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.")
@@ -1630,13 +2221,13 @@ export function buildProgram() {
         // 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. " +
+            throw new CliUsageError("--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`.");
+            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`.");
         }
         const ctx = await buildContext();
         const result = await deploy(ctx, slug, {
@@ -1659,7 +2250,7 @@ export function buildProgram() {
             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 = null;
@@ -1668,7 +2259,7 @@ export function buildProgram() {
             ctx = await buildContext();
         }
         catch (err) {
-            if (!isNotLoggedInError(err))
+            if (!isNotAuthenticatedError(err))
                 throw err;
             authMessage = err instanceof Error ? err.message : String(err);
         }
@@ -1728,23 +2319,138 @@ export function buildProgram() {
     // 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);
+        rejectNonMutatingIdempotencyKey(actionCommand, opts.idempotencyKey);
+        setRequestedIdempotencyKey(opts.idempotencyKey);
+        resetJsonPayload();
+        // Compile the filter before the action runs, so a typo costs nothing.
+        await armJqFilter(opts.jq);
+    });
+    // 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) {
-    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"]],
+];
+function assignTopLevelHelpGroups(program) {
+    const order = new Map();
+    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.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) {
+    for (const cmd of allCommands(program))
+        cmd.exitOverride();
 }
 export async function main(argv) {
     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, write = (line) => process.stderr.write(line)) {
+    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) {
+    const seconds = err?.retryAfterSeconds;
+    if (typeof seconds !== "number" || !Number.isFinite(seconds) || seconds < 0)
+        return "";
+    return ` Retry after ${seconds} seconds.`;
+}
 function allCommands(root) {
     const out = [];
     const visit = (cmd) => {
@@ -1761,8 +2467,11 @@ function hidesJsonHelp(cmd) {
         "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",
@@ -1771,6 +2480,7 @@ function hidesJsonHelp(cmd) {
         "dharta webhooks",
         "dharta env",
         "dharta agent",
+        "dharta genui",
         "dharta git-credential",
         "dharta dev",
         "dharta logs",
@@ -1800,8 +2510,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",
@@ -1811,6 +2524,7 @@ const HELP_ONLY_COMMAND_PATHS = new Set([
     "dharta webhooks",
     "dharta env",
     "dharta agent",
+    "dharta genui",
 ]);
 function rejectUnknownTopLevelCommand(program, argv, options) {
     const args = argv ? [...argv].slice(options?.from === "user" ? 0 : 2) : process.argv.slice(2);
@@ -1830,8 +2544,7 @@ function rejectUnknownTopLevelCommand(program, argv, options) {
         const path = commandPath(cursor);
         if (!HELP_ONLY_COMMAND_PATHS.has(path))
             return;
-        const visible = cursor.commands.filter((cmd) => !cmd._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;
             continue;
@@ -1907,21 +2620,21 @@ function parseOnOff(value, name) {
     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.` +
+    throw new CliUsageError(`${name} must be on/off, enabled/disabled, or true/false.` +
         (suggestion ? ` Did you mean ${suggestion}?` : ""));
 }
 export async function readStdin() {
     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");
+        throw new CliUsageError("No piped input. Usage: echo $DHARTA_API_KEY | dharta login --with-token");
     }
     const chunks = [];
     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;
 }
@@ -1931,25 +2644,25 @@ function parseVersion(input) {
         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) {
     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) {
     const normalized = input.trim();
     if (!normalized)
-        throw new Error("--port cannot be blank.");
+        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;
 }
@@ -1970,9 +2683,7 @@ 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));
     });
 }
 //# sourceMappingURL=cli.js.map