@dharta/cli 0.6.77

package/dist/cli.js

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