@dharta/cli 0.6.77 → 0.6.78

package/src/commands/analytics.ts

@@ -1,6 +1,7 @@
 import type { CliContext } from "../context.js";
 import { table } from "../output.js";
 import { closestChoice, normalizeDateOnly, parsePositiveInteger } from "../validators.js";
+import { CliUsageError } from "../exit-codes.js";
 
 export type AnalyticsView = "agents" | "users" | "instances" | "sessions" | "models" | "cost";
 
@@ -64,7 +65,7 @@ export function normalizeAnalyticsOptions(view: AnalyticsView, opts: AnalyticsOp
     if (normalized.range === undefined) {
       normalized.range = "custom";
     } else if (normalized.range !== "custom") {
-      throw new Error("--from/--to require --range custom.");
+      throw new CliUsageError("--from/--to require --range custom.");
     }
   }
 
@@ -72,17 +73,17 @@ export function normalizeAnalyticsOptions(view: AnalyticsView, opts: AnalyticsOp
     const allowed = view === "cost" ? COST_ANALYTICS_RANGES : ENTITY_ANALYTICS_RANGES;
     if (!(allowed as readonly string[]).includes(normalized.range)) {
       const suggestion = closestChoice(normalized.range, allowed);
-      throw new Error(
+      throw new CliUsageError(
         `--range must be one of: ${allowed.join(", ")}.` +
           (suggestion ? ` Did you mean ${suggestion}?` : ""),
       );
     }
   }
   if (normalized.groupBy !== undefined) {
-    if (view !== "cost") throw new Error("--group-by is only supported for analytics cost.");
+    if (view !== "cost") throw new CliUsageError("--group-by is only supported for analytics cost.");
     if (!(COST_ANALYTICS_GROUPS as readonly string[]).includes(normalized.groupBy)) {
       const suggestion = closestChoice(normalized.groupBy, COST_ANALYTICS_GROUPS);
-      throw new Error(
+      throw new CliUsageError(
         `--group-by must be one of: ${COST_ANALYTICS_GROUPS.join(", ")}.` +
           (suggestion ? ` Did you mean ${suggestion}?` : ""),
       );
@@ -96,7 +97,7 @@ export function normalizeAnalyticsOptions(view: AnalyticsView, opts: AnalyticsOp
 
 function normalizeRequiredFilter(value: string, flag: string): string {
   const normalized = value.trim();
-  if (!normalized) throw new Error(`${flag} cannot be blank.`);
+  if (!normalized) throw new CliUsageError(`${flag} cannot be blank.`);
   return normalized;
 }
 

package/src/commands/api.ts

@@ -1,77 +1,21 @@
 import type { CliContext } from "../context.js";
-import { randomUUID } from "node:crypto";
 import { cliFormatError } from "../api-error.js";
+import { CliUsageError } from "../exit-codes.js";
 import { closestChoice } from "../validators.js";
 
 const METHOD_NAMES = ["GET", "POST", "PUT", "PATCH", "DELETE"] as const;
 const METHODS = new Set<string>(METHOD_NAMES);
 
-const READ_ALLOWLIST: Array<RegExp> = [
-  /^\/me(?:[?#]|$)/,
-  /^\/version(?:[?#]|$)/,
-  /^\/agent_templates(?:[?#]|$)/,
-  /^\/api\/billing(?:[?#]|$)/,
-  /^\/api\/usage(?:[?#]|$)/,
-  /^\/api\/analytics\/(?:agents|users|instances|sessions|models|cost)(?:[?#]|$)/,
-  /^\/api\/audit_events(?:\.csv)?(?:[?#]|$)/,
-  /^\/api\/members(?:[?#]|$)/,
-  /^\/api\/kartas(?:[?#]|$)/,
-  /^\/api\/kartas\/[^/?#]+(?:[?#]|$)/,
-  /^\/api\/agents(?:[?#]|$)/,
-  /^\/api\/agents\/[a-z0-9][a-z0-9-]{0,62}(?:[?#]|$)/,
-  /^\/api\/agents\/[a-z0-9][a-z0-9-]{0,62}\/invocations(?:[?#]|$)/,
-  /^\/api\/agents\/[a-z0-9][a-z0-9-]{0,62}\/logs(?:[?#]|$)/,
-  /^\/api\/agents\/[a-z0-9][a-z0-9-]{0,62}\/env(?:[?#]|$)/,
-  /^\/api\/agents\/[a-z0-9][a-z0-9-]{0,62}\/releases(?:[?#]|$)/,
-  /^\/api\/agents\/[a-z0-9][a-z0-9-]{0,62}\/appearance(?:[?#]|$)/,
-  /^\/api\/agents\/[a-z0-9][a-z0-9-]{0,62}\/schedules(?:[?#]|$)/,
-  /^\/api\/agents\/[a-z0-9][a-z0-9-]{0,62}\/directories\/(?:instances|end_users|sessions)(?:[?#]|$)/,
-  /^\/api\/agents\/[a-z0-9][a-z0-9-]{0,62}\/embed_keys(?:[?#]|$)/,
-  /^\/api\/limits\/budget(?:[?#]|$)/,
-  /^\/api\/limits\/instances\/[^/?#]+\/(?:cap|seat_cap)(?:[?#]|$)/,
-  /^\/api\/limits\/end_users\/[^/?#]+\/cap(?:[?#]|$)/,
-  /^\/api\/webhook_endpoints(?:[?#]|$)/,
-  /^\/api_keys(?:[?#]|$)/,
-  /^\/model_keys(?:[?#]|$)/,
-];
-
-interface WriteAllowlistEntry {
-  methods: readonly string[];
-  pattern: RegExp;
-}
-
-const WRITE_ALLOWLIST: WriteAllowlistEntry[] = [
-  { methods: ["PATCH"], pattern: /^\/api\/kartas\/[^/?#]+(?:[?#]|$)/ },
-  { methods: ["POST"], pattern: /^\/api\/kartas\/[^/?#]+\/members(?:[?#]|$)/ },
-  { methods: ["PATCH", "DELETE"], pattern: /^\/api\/kartas\/[^/?#]+\/members\/[^/?#]+(?:[?#]|$)/ },
-  { methods: ["POST"], pattern: /^\/api\/agents\/[a-z0-9][a-z0-9-]{0,62}\/embed_keys(?:[?#]|$)/ },
-  { methods: ["PATCH", "DELETE"], pattern: /^\/api\/agents\/[a-z0-9][a-z0-9-]{0,62}\/embed_keys\/[^/?#]+(?:[?#]|$)/ },
-  { methods: ["POST"], pattern: /^\/api\/agents\/[a-z0-9][a-z0-9-]{0,62}\/embed_keys\/[^/?#]+\/(?:rotate|disable|enable)(?:[?#]|$)/ },
-  { methods: ["PATCH"], pattern: /^\/api\/agents\/[a-z0-9][a-z0-9-]{0,62}\/appearance(?:[?#]|$)/ },
-  { methods: ["PUT", "DELETE"], pattern: /^\/api\/agents\/[a-z0-9][a-z0-9-]{0,62}\/env\/[^/?#]+(?:[?#]|$)/ },
-  { methods: ["POST"], pattern: /^\/api\/agents\/[a-z0-9][a-z0-9-]{0,62}\/env\/pull(?:[?#]|$)/ },
-  { methods: ["PATCH"], pattern: /^\/api\/agents\/[a-z0-9][a-z0-9-]{0,62}\/(?:serving|dashboard_edits|model)(?:[?#]|$)/ },
-  { methods: ["PATCH"], pattern: /^\/api\/agents\/[a-z0-9][a-z0-9-]{0,62}\/workspace_inspectable(?:[?#]|$)/ },
-  { methods: ["DELETE"], pattern: /^\/api\/agents\/[a-z0-9][a-z0-9-]{0,62}(?:[?#]|$)/ },
-  { methods: ["POST"], pattern: /^\/api\/members\/invitations(?:[?#]|$)/ },
-  { methods: ["PATCH", "DELETE"], pattern: /^\/api\/members\/[^/?#]+(?:[?#]|$)/ },
-  { methods: ["POST"], pattern: /^\/api\/agents\/[a-z0-9][a-z0-9-]{0,62}\/schedules(?:[?#]|$)/ },
-  { methods: ["DELETE"], pattern: /^\/api\/agents\/[a-z0-9][a-z0-9-]{0,62}\/schedules\/[^/?#]+(?:[?#]|$)/ },
-  { methods: ["POST"], pattern: /^\/api\/agents\/[a-z0-9][a-z0-9-]{0,62}\/schedules\/[^/?#]+\/(?:pause|resume|run)(?:[?#]|$)/ },
-  { methods: ["POST"], pattern: /^\/api\/agents\/[a-z0-9][a-z0-9-]{0,62}\/releases\/v?\d+\/activate(?:[?#]|$)/ },
-  { methods: ["POST"], pattern: /^\/api\/agents\/[a-z0-9][a-z0-9-]{0,62}\/rollback(?:[?#]|$)/ },
-  { methods: ["POST"], pattern: /^\/api\/agents\/[a-z0-9][a-z0-9-]{0,62}\/workspace_tokens(?:[?#]|$)/ },
-  { methods: ["PATCH"], pattern: /^\/api\/limits\/budget(?:[?#]|$)/ },
-  { methods: ["PATCH"], pattern: /^\/api\/limits\/instances\/[^/?#]+\/(?:cap|seat_cap)(?:[?#]|$)/ },
-  { methods: ["PATCH"], pattern: /^\/api\/limits\/end_users\/[^/?#]+\/cap(?:[?#]|$)/ },
-  { methods: ["POST"], pattern: /^\/api\/webhook_endpoints(?:[?#]|$)/ },
-  { methods: ["PATCH", "DELETE"], pattern: /^\/api\/webhook_endpoints\/[^/?#]+(?:[?#]|$)/ },
-  { methods: ["POST"], pattern: /^\/api\/webhook_endpoints\/[^/?#]+\/enable(?:[?#]|$)/ },
-  { methods: ["POST"], pattern: /^\/api_keys(?:[?#]|$)/ },
-  { methods: ["PATCH", "DELETE"], pattern: /^\/api_keys\/[^/?#]+(?:[?#]|$)/ },
-  { methods: ["POST"], pattern: /^\/model_keys(?:[?#]|$)/ },
-  { methods: ["DELETE"], pattern: /^\/model_keys\/[^/?#]+(?:[?#]|$)/ },
-];
+// Prefix-only reachability (RFC 0048 D1, founder decision 2026-08-31). The CLI
+// used to carry a hand-maintained read/write allowlist, which meant every new
+// public endpoint was unreachable until someone remembered to add a regex here
+// - a second, always-stale copy of the server's route table. The server's
+// scope model is the authorization boundary; this list only keeps the
+// passthrough pointed at the public JSON API instead of, say, a Devise HTML
+// form. Matching is by exact first path segment, so `/apix` and `/me2` are
+// rejected while `/me?fields=x` is allowed.
+const ALLOWED_PREFIXES = ["/api/", "/me", "/version", "/api_keys", "/model_connections", "/agent_templates"] as const;
+const ALLOWED_FIRST_SEGMENTS = new Set(ALLOWED_PREFIXES.map((prefix) => prefix.replace(/^\/|\/$/g, "")));
 
 export interface ApiOptions {
   field?: string[];
@@ -86,12 +30,17 @@ export async function api(ctx: CliContext, methodOrPath: string | undefined, pat
 
   const headers = parseHeaders(opts.header ?? []);
   const body = await buildBody(opts);
+  // `HttpClient.raw` sends no Accept of its own, so fetch defaults to `*/*`.
+  // The /api_keys and /model_connections routes are mounted behind a JSON
+  // constraint and fall through to the console HTML controller without this,
+  // which reads as a mystifying redirect to the sign-in page. A caller who
+  // names their own Accept keeps it.
+  if (!hasHeader(headers, "accept")) {
+    headers.Accept = "application/json";
+  }
   if (body !== undefined && !hasHeader(headers, "content-type")) {
     headers["Content-Type"] = "application/json";
   }
-  if (method !== "GET" && !hasHeader(headers, "idempotency-key")) {
-    headers["Idempotency-Key"] = randomUUID();
-  }
   const res = await ctx.http.raw(path, { method, headers, body });
   const text = await res.text();
   const parsed = parseMaybeJson(text);
@@ -110,9 +59,9 @@ export async function api(ctx: CliContext, methodOrPath: string | undefined, pat
 export function validateApiRequest(methodOrPath: string | undefined, pathArg: string | undefined, opts: ApiOptions) {
   const { method, path } = normalizeTarget(methodOrPath, pathArg, hasFields(opts));
   if (method === "GET" && hasFields(opts)) {
-    throw new Error("GET requests cannot include --field, --raw-field, or --body-stdin. Use POST, PUT, or PATCH for request bodies.");
+    throw new CliUsageError("GET requests cannot include --field, --raw-field, or --body-stdin. Use POST, PUT, or PATCH for request bodies.");
   }
-  assertAllowlisted(method, path);
+  assertAllowedPrefix(method, path);
   parseHeaders(opts.header ?? []);
   validateBodyFields(opts);
   return { method, path };
@@ -123,7 +72,7 @@ export async function prepareApiOptions(opts: ApiOptions, read: () => Promise<st
   validateBodyFields(opts);
   if (!opts.bodyStdin) return opts;
   const body = await read();
-  if (body.length === 0) throw new Error("--body-stdin was set, but stdin was empty.");
+  if (body.length === 0) throw new CliUsageError("--body-stdin was set, but stdin was empty.");
   return { ...opts, body, bodyStdin: false };
 }
 
@@ -136,21 +85,21 @@ function normalizeTarget(methodOrPath: string | undefined, pathArg: string | und
   const first = methodOrPath?.trim();
   const second = pathArg?.trim();
   if (!first) {
-    throw new Error("Usage: dharta api [METHOD] /path");
+    throw new CliUsageError("Usage: dharta api [METHOD] /path");
   }
 
   let method: string;
   let path: string;
   const maybeMethod = first.toUpperCase();
   if (METHODS.has(maybeMethod) && !second) {
-    throw new Error("Usage: dharta api [METHOD] /path");
+    throw new CliUsageError("Usage: dharta api [METHOD] /path");
   }
   if (METHODS.has(maybeMethod)) {
     method = maybeMethod;
     path = second as string;
   } else if (second) {
     const suggestion = closestChoice(maybeMethod, METHOD_NAMES);
-    throw new Error(
+    throw new CliUsageError(
       `Unknown API method ${maybeMethod}. Allowed methods: ${METHOD_NAMES.join(", ")}.` +
         (suggestion ? ` Did you mean ${suggestion}?` : ""),
     );
@@ -160,26 +109,58 @@ function normalizeTarget(methodOrPath: string | undefined, pathArg: string | und
   }
 
   if (!path.startsWith("/")) {
-    throw new Error("API path must start with '/', e.g. /me or /api/agents/support-bot");
+    throw new CliUsageError("API path must start with '/', e.g. /me or /api/agents/support-bot");
   }
   if (/^\/\//.test(path) || /^[a-z][a-z0-9+.-]*:\/\//i.test(path)) {
-    throw new Error("API path must be relative to the Dharta API host.");
+    throw new CliUsageError("API path must be relative to the Dharta API host.");
   }
   return { method, path };
 }
 
-function assertAllowlisted(method: string, path: string): void {
-  if (method === "GET" && READ_ALLOWLIST.some((pattern) => pattern.test(path))) return;
-  if (method !== "GET" && WRITE_ALLOWLIST.some((entry) => entry.methods.includes(method) && entry.pattern.test(path))) return;
+function assertAllowedPrefix(method: string, path: string): void {
+  // Check the path the SERVER will see, not the one that was typed.
+  // HttpClient.raw concatenates baseUrl + path and fetch resolves the result
+  // with the WHATWG URL parser, which collapses dot segments and treats a
+  // backslash as a separator: `/api/../users/sign_in`, `/api/%2e%2e/users`,
+  // and `/api\..\users` all arrive as paths the prefix list does not allow.
+  const normalized = normalizedPathname(path);
+  const typed = path.split(/[?#]/)[0];
+  if (normalized !== typed) {
+    throw new CliUsageError(
+      `API path '${typed}' is not the path that would be requested ('${normalized}'). ` +
+        "Write the literal path; '..', '.', and '\\' are not part of any Dharta API route.",
+    );
+  }
+  if (hasAllowedPrefix(normalized)) return;
 
   const suggestion = apiRouteSuggestion(path);
-  throw new Error(
-    "`dharta api` only allows documented public read endpoints and curated scoped writes. " +
-      "Use the matching `karta <command>` for unsupported writes." +
+  throw new CliUsageError(
+    `\`dharta api\` reaches the public JSON API only. Allowed path prefixes: ${ALLOWED_PREFIXES.join(", ")}.` +
       (suggestion ? ` Did you mean ${method} ${suggestion}?` : ""),
   );
 }
 
+// The pathname fetch would resolve this to. The base is a placeholder: only
+// the path matters, and the caller has already rejected absolute and
+// protocol-relative inputs.
+function normalizedPathname(path: string): string {
+  try {
+    return new URL(path, "http://placeholder").pathname;
+  } catch {
+    throw new CliUsageError(`API path '${path}' is not a valid URL path.`);
+  }
+}
+
+function hasAllowedPrefix(path: string): boolean {
+  const segments = path.split("/");
+  const first = segments[1] ?? "";
+  if (!ALLOWED_FIRST_SEGMENTS.has(first)) return false;
+  // `/api` is a namespace, never a route of its own, so it needs a second
+  // segment. The other prefixes name real endpoints.
+  if (first === "api") return (segments[2] ?? "") !== "";
+  return true;
+}
+
 function apiRouteSuggestion(path: string): string | null {
   const replacements: Array<[RegExp, string]> = [
     [/^\/analytics(?=\/|[?#]|$)/, "/api/analytics"],
@@ -205,7 +186,7 @@ function hasStructuredFields(opts: ApiOptions): boolean {
 
 function validateBodyFields(opts: ApiOptions): void {
   if (opts.bodyStdin && hasStructuredFields(opts)) {
-    throw new Error("Use either --body-stdin or --field/--raw-field, not both.");
+    throw new CliUsageError("Use either --body-stdin or --field/--raw-field, not both.");
   }
   for (const raw of opts.field ?? []) splitAssignment(raw, "--field");
   for (const raw of opts.rawField ?? []) splitAssignment(raw, "--raw-field");
@@ -232,13 +213,13 @@ function parseHeaders(input: string[]): Record<string, string> {
   const headers: Record<string, string> = {};
   for (const raw of input) {
     const idx = raw.indexOf(":");
-    if (idx <= 0) throw new Error(`Invalid --header '${raw}'. Use 'Name: value'.`);
+    if (idx <= 0) throw new CliUsageError(`Invalid --header '${raw}'. Use 'Name: value'.`);
     const key = raw.slice(0, idx).trim();
     const value = raw.slice(idx + 1).trim();
-    if (!key || !value) throw new Error(`Invalid --header '${raw}'. Use 'Name: value'.`);
+    if (!key || !value) throw new CliUsageError(`Invalid --header '${raw}'. Use 'Name: value'.`);
     const lower = key.toLowerCase();
     if (lower === "authorization" || lower === "host" || lower.startsWith("x-forwarded-")) {
-      throw new Error(`Unsafe --header '${key}' cannot be overridden. The CLI manages auth and connection headers.`);
+      throw new CliUsageError(`Unsafe --header '${key}' cannot be overridden. The CLI manages auth and connection headers.`);
     }
     headers[key] = value;
   }
@@ -253,9 +234,9 @@ function hasHeader(headers: Record<string, string>, name: string): boolean {
 
 function splitAssignment(raw: string, flag: string): [string, string] {
   const idx = raw.indexOf("=");
-  if (idx <= 0) throw new Error(`Invalid ${flag} '${raw}'. Use key=value.`);
+  if (idx <= 0) throw new CliUsageError(`Invalid ${flag} '${raw}'. Use key=value.`);
   const key = raw.slice(0, idx).trim();
-  if (!key) throw new Error(`Invalid ${flag} '${raw}'. Use key=value.`);
+  if (!key) throw new CliUsageError(`Invalid ${flag} '${raw}'. Use key=value.`);
   return [key, raw.slice(idx + 1)];
 }
 
@@ -285,13 +266,13 @@ function parseMaybeJson(text: string): unknown {
 
 async function readStdin(): Promise<string> {
   if (process.stdin.isTTY) {
-    throw new Error(
+    throw new CliUsageError(
       "No piped input. Usage: echo '{\"name\":\"Example\"}' | dharta api POST /api/agents/support-bot/embed_keys --body-stdin",
     );
   }
   const chunks: Buffer[] = [];
   for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk));
   const text = Buffer.concat(chunks).toString("utf8");
-  if (text.length === 0) throw new Error("--body-stdin was set, but stdin was empty.");
+  if (text.length === 0) throw new CliUsageError("--body-stdin was set, but stdin was empty.");
   return text;
 }

package/src/commands/appearance.ts

@@ -1,8 +1,8 @@
-import { randomUUID } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { inferAgentSlug, type AgentInferOptions } from "../agent.js";
 import type { CliContext } from "../context.js";
 import { normalizeNonBlank } from "../validators.js";
+import { CliUsageError } from "../exit-codes.js";
 
 export interface AppearanceEnvelope {
   agent: {
@@ -32,13 +32,12 @@ export async function appearanceGet(ctx: CliContext, opts: AgentInferOptions): P
 
 export async function appearanceSetData(ctx: CliContext, opts: AppearanceOptions): Promise<AppearanceEnvelope> {
   await validateAppearanceSetInput(opts);
-  if (!opts.file) throw new Error("Pass --file <file>. Usage: dharta appearance set --file appearance.json");
+  if (!opts.file) throw new CliUsageError("Pass --file <file>. Usage: dharta appearance set --file appearance.json");
   const slug = await inferAgentSlug(opts);
   const appearance = await readAppearanceFile(opts.file);
   return ctx.http.request<AppearanceEnvelope>({
     method: "PATCH",
     path: `/api/agents/${encodeURIComponent(slug)}/appearance`,
-    headers: { "Idempotency-Key": randomUUID() },
     body: { appearance },
   });
 }
@@ -49,7 +48,7 @@ export async function appearanceSet(ctx: CliContext, opts: AppearanceOptions): P
 }
 
 export async function validateAppearanceSetInput(opts: AppearanceOptions): Promise<void> {
-  if (!opts.file) throw new Error("Pass --file <file>. Usage: dharta appearance set --file appearance.json");
+  if (!opts.file) throw new CliUsageError("Pass --file <file>. Usage: dharta appearance set --file appearance.json");
   await readAppearanceFile(opts.file);
 }
 
@@ -69,11 +68,11 @@ async function readAppearanceFile(file: string): Promise<Record<string, unknown>
   try {
     parsed = JSON.parse(text);
   } catch {
-    throw new Error(`--file ${normalized} must contain valid JSON.`);
+    throw new CliUsageError(`--file ${normalized} must contain valid JSON.`);
   }
 
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    throw new Error(`--file ${normalized} must contain a JSON object.`);
+    throw new CliUsageError(`--file ${normalized} must contain a JSON object.`);
   }
   return parsed as Record<string, unknown>;
 }

package/src/commands/artifact.ts

@@ -2,6 +2,7 @@ import { resolveRuntime, spawnRuntime } from "../runtime.js";
 import { promises as fs } from "node:fs";
 import * as path from "node:path";
 import type { Command } from "commander";
+import { CliUsageError } from "../exit-codes.js";
 
 export async function artifact(args: string[]): Promise<void> {
   if (args[0] !== "run") {
@@ -154,7 +155,7 @@ export function registerArtifactCommands(program: Command): void {
     .option("--id <id>", "Stable schema-2 Artifact ID")
     .action(async (opts: { key?: string; id?: string }) => {
       if ((!opts.key && !opts.id) || (opts.key && opts.id)) {
-        throw new Error(
+        throw new CliUsageError(
           "Exactly one of --key or --id is required. See `dharta artifact remove --help`.",
         );
       }
@@ -234,7 +235,7 @@ type ArtifactPutCliOptions = {
 
 async function runPut(opts: ArtifactPutCliOptions): Promise<void> {
   if (!opts.title) {
-    throw new Error("--title is required. See `dharta artifact put --help`.");
+    throw new CliUsageError("--title is required. See `dharta artifact put --help`.");
   }
   const requestedAgentPolicy = Boolean(
     opts.agentAuthority.length
@@ -253,13 +254,13 @@ async function runPut(opts: ArtifactPutCliOptions): Promise<void> {
       || opts.provenance || opts.continuation.length
   );
   if (v2 && legacy) {
-    throw new Error(
+    throw new CliUsageError(
       "Legacy and schema-2 Artifact options cannot be mixed. See `dharta artifact put --help`.",
     );
   }
   if (v2) {
     if (!opts.id || !opts.root || Boolean(opts.entry) === Boolean(opts.run)) {
-      throw new Error(
+      throw new CliUsageError(
         "Schema-2 Artifacts require --id, --root, and exactly one of --entry or --run. "
         + "See `dharta artifact put --help`.",
       );
@@ -277,7 +278,7 @@ async function runPut(opts: ArtifactPutCliOptions): Promise<void> {
         .map(([name]) => name)
       : [];
     if (missingAgentPolicy.length > 0) {
-      throw new Error(
+      throw new CliUsageError(
         `Agent activation requires a complete policy; missing ${missingAgentPolicy.join(", ")}. `
         + "See `dharta artifact put --help`.",
       );
@@ -305,7 +306,7 @@ async function runPut(opts: ArtifactPutCliOptions): Promise<void> {
     }));
   }
   if (!opts.key || !opts.kind || !opts.entrypoint) {
-    throw new Error(
+    throw new CliUsageError(
       "Artifacts require --key, --kind, and --entrypoint. "
       + "See `dharta artifact put --help`.",
     );

package/src/commands/audit-log.ts

@@ -2,6 +2,7 @@ import type { CliContext } from "../context.js";
 import { cliFormatRawError } from "../api-error.js";
 import { fmtTs, table } from "../output.js";
 import { parsePositiveInteger, validateDateOnly } from "../validators.js";
+import { CliUsageError } from "../exit-codes.js";
 
 interface AuditLogResponse {
   data: AuditLogEvent[];
@@ -106,7 +107,7 @@ function normalizeAuditLogOptions(opts: AuditLogOptions): AuditLogOptions {
 function normalizeOptionalFilter(value: string | undefined, flag: string): string | undefined {
   if (value === undefined) return undefined;
   const normalized = value.trim();
-  if (normalized.length === 0) throw new Error(`${flag} cannot be blank.`);
+  if (normalized.length === 0) throw new CliUsageError(`${flag} cannot be blank.`);
   return normalized;
 }
 

package/src/commands/auth.ts

@@ -4,12 +4,16 @@ import { HttpClient } from "@dharta/sdk";
 import { cliFormatError, cliFormatNetworkError } from "../api-error.js";
 import {
   configPath,
+  explicitProfileName,
   loadConfig,
+  profileNotFoundError,
   removeProfile,
+  requestedProfileName,
   DEFAULT_BASE_URL,
 } from "../config.js";
 import { normalizeNonBlank } from "../validators.js";
 import { formatApiKeyExpiry, formatScopes } from "./scopes.js";
+import { CliUsageError } from "../exit-codes.js";
 
 // GET /me — the control plane's key-introspection endpoint.
 export interface Me {
@@ -142,14 +146,26 @@ function formatCause(error: unknown): string {
   return error instanceof Error && error.message ? error.message : String(error);
 }
 
-// Print the active token for piping (gh auth token parity). Environment
-// override wins, matching every other command.
+// Print the active token for piping (gh auth token parity). An ambient
+// DHARTA_API_KEY wins, matching every other command, unless --profile was
+// passed.
 export async function authToken(): Promise<string> {
+  // Same precedence as buildContext: an explicit --profile is a deliberate act
+  // and outranks an ambient key, so `dharta --profile ci auth token` cannot
+  // print a credential from another organization.
   const envKey = process.env.DHARTA_API_KEY;
-  if (envKey) return envKey;
+  if (envKey && explicitProfileName() === undefined) return envKey;
   const cfg = await loadConfig();
-  const profile = cfg?.profiles[cfg.default_profile];
+  // The global --profile picks which stored credential this prints, so
+  // `dharta --profile ci auth token` pipes the ci key, not the default one.
+  const requested = requestedProfileName();
+  const name = requested ?? cfg?.default_profile;
+  const profile = name === undefined ? undefined : cfg?.profiles[name];
   if (!profile) {
+    // A profile the user named and that is not stored is a usage error, the
+    // same as everywhere else. Only "nothing is stored at all" is a
+    // not-authenticated case.
+    if (requested !== undefined) throw profileNotFoundError(requested);
     throw new Error("Not logged in. Run `dharta login` to sign in via your browser.");
   }
   return profile.api_key;
@@ -163,6 +179,7 @@ export async function authLogoutData(
   const requestedName = profileName === undefined ? undefined : normalizeNonBlank(profileName, "--profile");
   const cfg = await loadConfig();
   if (!cfg) {
+    if (requestedName !== undefined) throw profileNotFoundError(requestedName);
     throw new Error(
       "Not logged in - nothing to remove. `dharta auth status` shows what is stored.",
     );
@@ -170,7 +187,10 @@ export async function authLogoutData(
   const name = requestedName ?? cfg.default_profile;
   const removed = await removeProfile(name);
   if (!removed) {
-    throw new Error(
+    // Naming a profile that is not there is a usage error, and it reads the
+    // same as it does on every other command.
+    if (requestedName !== undefined) throw profileNotFoundError(name);
+    throw new CliUsageError(
       `No profile named '${name}' in ${configPath()}. Run \`dharta auth status\` to list profiles.`,
     );
   }

package/src/commands/caps.ts

@@ -1,6 +1,6 @@
-import { randomUUID } from "node:crypto";
 import type { CliContext } from "../context.js";
 import { parseDollarAmountToCents } from "../money.js";
+import { CliUsageError } from "../exit-codes.js";
 
 export interface Budget {
   period: string;
@@ -108,7 +108,6 @@ export async function capsBudgetSetData(ctx: CliContext, opts: BudgetSetOptions)
   return ctx.http.request<BudgetEnvelope>({
     method: "PATCH",
     path: "/api/limits/budget",
-    headers: { "Idempotency-Key": randomUUID() },
     body,
   });
 }
@@ -134,7 +133,6 @@ export async function capsInstanceSetData(ctx: CliContext, instance: string, opt
   return ctx.http.request<InstanceCapEnvelope>({
     method: "PATCH",
     path: `/api/limits/instances/${encodeURIComponent(normalizedInstance)}/cap`,
-    headers: { "Idempotency-Key": randomUUID() },
     body: capBody(opts),
   });
 }
@@ -161,7 +159,6 @@ export async function capsEndUserSetData(ctx: CliContext, endUserId: string, opt
   return ctx.http.request<EndUserCapEnvelope>({
     method: "PATCH",
     path: `/api/limits/end_users/${encodeURIComponent(normalizedEndUserId)}/cap`,
-    headers: { "Idempotency-Key": randomUUID() },
     body: capBody(opts),
   });
 }
@@ -193,7 +190,6 @@ export async function capsSeatSetData(ctx: CliContext, instance: string, endUser
   return ctx.http.request<SeatCapEnvelope>({
     method: "PATCH",
     path: `/api/limits/instances/${encodeURIComponent(normalizedInstance)}/seat_cap`,
-    headers: { "Idempotency-Key": randomUUID() },
     body: { ...capBody(opts), end_user_id: normalizedEndUserId },
   });
 }
@@ -207,7 +203,7 @@ export async function capsSeatSet(ctx: CliContext, instance: string, endUserId:
 
 function dollarsToCents(value: string | undefined): number {
   if (value === undefined) {
-    throw new Error("Pass --amount <dollars>. Usage: dharta caps budget set --amount 250");
+    throw new CliUsageError("Pass --amount <dollars>. Usage: dharta caps budget set --amount 250");
   }
   return parseDollarAmountToCents(value, "--amount");
 }
@@ -229,34 +225,34 @@ export function validateCapSetOptions(opts: CapSetOptions): void {
 }
 
 function capBody(opts: CapSetOptions): Record<string, unknown> {
-  if (opts.clear && opts.amount) throw new Error("Use either --amount or --clear, not both.");
+  if (opts.clear && opts.amount) throw new CliUsageError("Use either --amount or --clear, not both.");
   if (opts.clear) return { clear: true };
-  if (!opts.amount) throw new Error("Pass --amount <dollars> or --clear.");
+  if (!opts.amount) throw new CliUsageError("Pass --amount <dollars> or --clear.");
   return { cap_cents: dollarsToCents(opts.amount) };
 }
 
 function parseWholeNumberInRange(value: string, flag: string, min: number, max: number): number {
   const normalized = value.trim();
-  if (!/^\d+$/.test(normalized)) throw new Error(`${flag} must be a whole number.`);
+  if (!/^\d+$/.test(normalized)) throw new CliUsageError(`${flag} must be a whole number.`);
   const parsed = Number(normalized);
   if (!Number.isSafeInteger(parsed) || parsed < min || parsed > max) {
-    throw new Error(`${flag} must be a whole number from ${min} to ${max}.`);
+    throw new CliUsageError(`${flag} must be a whole number from ${min} to ${max}.`);
   }
   return parsed;
 }
 
 function parsePositiveWholeNumber(value: string, flag: string): number {
   const normalized = value.trim();
-  if (!/^\d+$/.test(normalized)) throw new Error(`${flag} must be a whole number.`);
+  if (!/^\d+$/.test(normalized)) throw new CliUsageError(`${flag} must be a whole number.`);
   const parsed = Number(normalized);
   if (!Number.isSafeInteger(parsed) || parsed <= 0) {
-    throw new Error(`${flag} must be a positive whole number.`);
+    throw new CliUsageError(`${flag} must be a positive whole number.`);
   }
   return parsed;
 }
 
 function stopUsageOption(opts: BudgetSetOptions): boolean | undefined {
-  if (opts.hardStop && opts.soft) throw new Error("Use either --hard-stop or --soft, not both.");
+  if (opts.hardStop && opts.soft) throw new CliUsageError("Use either --hard-stop or --soft, not both.");
   if (opts.hardStop) return true;
   if (opts.soft) return false;
   return undefined;
@@ -264,7 +260,7 @@ function stopUsageOption(opts: BudgetSetOptions): boolean | undefined {
 
 function alertsOption(opts: BudgetSetOptions): boolean | undefined {
   if (opts.enableAlerts && opts.disableAlerts) {
-    throw new Error("Use either --enable-alerts or --disable-alerts, not both.");
+    throw new CliUsageError("Use either --enable-alerts or --disable-alerts, not both.");
   }
   if (opts.enableAlerts) return true;
   if (opts.disableAlerts) return false;
@@ -296,7 +292,7 @@ function capSetMessage(label: string, cap: EntityCap | null, changed: boolean |
 function normalizeRequired(value: string, label: string): string {
   const normalized = value.trim();
   if (!normalized) {
-    throw new Error(`${label} cannot be blank.`);
+    throw new CliUsageError(`${label} cannot be blank.`);
   }
   return normalized;
 }