@dharta/cli 0.6.77

package/src/commands/analytics.ts

@@ -0,0 +1,181 @@
+import type { CliContext } from "../context.js";
+import { table } from "../output.js";
+import { closestChoice, normalizeDateOnly, parsePositiveInteger } from "../validators.js";
+
+export type AnalyticsView = "agents" | "users" | "instances" | "sessions" | "models" | "cost";
+
+export const ENTITY_ANALYTICS_RANGES = ["7d", "30d", "90d"] as const;
+export const COST_ANALYTICS_RANGES = ["mtd", "7d", "30d", "90d", "last_month", "custom"] as const;
+export const COST_ANALYTICS_GROUPS = ["agent", "karta", "session", "user", "model"] as const;
+
+export interface AnalyticsOptions {
+  range?: string;
+  groupBy?: string;
+  from?: string;
+  to?: string;
+  limit?: string;
+}
+
+interface AnalyticsResponse {
+  view: string;
+  range: string;
+  from: string;
+  to: string;
+  summary?: Record<string, unknown>;
+  totals?: Record<string, unknown>;
+  data: Array<Record<string, unknown>>;
+}
+
+export async function analyticsData(ctx: CliContext, view: AnalyticsView, opts: AnalyticsOptions = {}): Promise<AnalyticsResponse> {
+  const normalized = normalizeAnalyticsOptions(view, opts);
+  const params = new URLSearchParams();
+  if (normalized.range) params.set("range", normalized.range);
+  if (normalized.groupBy) params.set("group_by", normalized.groupBy);
+  if (normalized.from) params.set("from", normalized.from);
+  if (normalized.to) params.set("to", normalized.to);
+  if (normalized.limit) params.set("limit", normalized.limit);
+  const qs = params.toString();
+  return ctx.http.request<AnalyticsResponse>({ path: `/api/analytics/${view}${qs ? `?${qs}` : ""}` });
+}
+
+export async function analytics(ctx: CliContext, view: AnalyticsView, opts: AnalyticsOptions = {}): Promise<string> {
+  const res = await analyticsData(ctx, view, opts);
+  const lines = [`${title(view)} (${res.from} to ${res.to})`];
+  const summary = res.totals ?? res.summary;
+  if (summary) {
+    for (const [key, value] of Object.entries(summary)) {
+      lines.push(`${formatSummaryKey(key)}: ${formatSummaryValue(key, value)}`);
+    }
+  }
+  if (res.data.length === 0) return lines.join("\n");
+  lines.push("");
+  lines.push(table(res.data.map((row) => compactRow(view, row))));
+  return lines.join("\n");
+}
+
+export function normalizeAnalyticsOptions(view: AnalyticsView, opts: AnalyticsOptions): AnalyticsOptions {
+  const normalized: AnalyticsOptions = { ...opts };
+  if (normalized.range !== undefined) normalized.range = normalizeRequiredFilter(normalized.range, "--range");
+  if (normalized.groupBy !== undefined) normalized.groupBy = normalizeRequiredFilter(normalized.groupBy, "--group-by");
+  if (normalized.from !== undefined) normalized.from = normalizeDateOnly(normalized.from, "--from");
+  if (normalized.to !== undefined) normalized.to = normalizeDateOnly(normalized.to, "--to");
+  if (normalized.limit !== undefined) normalized.limit = normalizeRequiredFilter(normalized.limit, "--limit");
+  if (view === "cost" && (normalized.from !== undefined || normalized.to !== undefined)) {
+    if (normalized.range === undefined) {
+      normalized.range = "custom";
+    } else if (normalized.range !== "custom") {
+      throw new Error("--from/--to require --range custom.");
+    }
+  }
+
+  if (normalized.range) {
+    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(
+        `--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 (!(COST_ANALYTICS_GROUPS as readonly string[]).includes(normalized.groupBy)) {
+      const suggestion = closestChoice(normalized.groupBy, COST_ANALYTICS_GROUPS);
+      throw new Error(
+        `--group-by must be one of: ${COST_ANALYTICS_GROUPS.join(", ")}.` +
+          (suggestion ? ` Did you mean ${suggestion}?` : ""),
+      );
+    }
+  }
+  if (normalized.limit !== undefined) {
+    parsePositiveInteger(normalized.limit, "--limit");
+  }
+  return normalized;
+}
+
+function normalizeRequiredFilter(value: string, flag: string): string {
+  const normalized = value.trim();
+  if (!normalized) throw new Error(`${flag} cannot be blank.`);
+  return normalized;
+}
+
+function title(view: AnalyticsView): string {
+  if (view === "cost") return "Analytics cost";
+  return `Analytics ${view}`;
+}
+
+function formatSummaryKey(key: string): string {
+  if (key.endsWith("_micros")) return key.slice(0, -"_micros".length);
+  if (key.endsWith("_pct")) return key.slice(0, -"_pct".length);
+  return key;
+}
+
+function formatSummaryValue(key: string, value: unknown): string {
+  if (key.endsWith("_micros")) return formatMicros(value);
+  if (key.endsWith("_pct")) return formatPercent(value);
+  return String(value);
+}
+
+function compactRow(view: AnalyticsView, row: Record<string, unknown>): Record<string, string> {
+  if (view === "cost") {
+    return {
+      label: String(row.label ?? row.id ?? ""),
+      tokens: String(row.tokens ?? 0),
+      total: formatMicros(row.total_micros),
+      share: formatPercent(row.share_pct),
+    };
+  }
+  if (view === "agents") {
+    return {
+      slug: String(row.slug ?? ""),
+      tokens: String(row.tokens ?? 0),
+      sessions: String(row.sessions_count ?? 0),
+      spend: formatMicros(row.spend_micros),
+    };
+  }
+  if (view === "sessions") {
+    return {
+      id: String(row.id ?? ""),
+      agent: String(row.agent_slug ?? ""),
+      turns: String(row.turns ?? 0),
+      tokens: String(row.tokens ?? row.input_tokens ?? 0),
+      spend: formatMicros(row.spend_micros ?? row.cost_micros),
+    };
+  }
+  if (view === "models") {
+    return {
+      model: String(row.id ?? row.model ?? ""),
+      tokens: String(row.tokens ?? 0),
+      sessions: String(row.sessions_count ?? 0),
+      spend: formatMicros(row.spend_micros ?? row.cost_micros),
+    };
+  }
+  if (view === "instances") {
+    return {
+      id: String(row.id ?? ""),
+      agent: String(row.agent_slug ?? ""),
+      tokens: String(row.tokens ?? row.input_tokens ?? 0),
+      sessions: String(row.sessions_count ?? 0),
+      spend: formatMicros(row.spend_micros ?? row.cost_micros),
+    };
+  }
+  return {
+    id: String(row.id ?? ""),
+    tokens: String(row.tokens ?? row.input_tokens ?? 0),
+    sessions: String(row.sessions_count ?? 0),
+    spend: formatMicros(row.spend_micros ?? row.cost_micros),
+  };
+}
+
+function formatMicros(value: unknown): string {
+  const micros = Number(value ?? 0);
+  if (!Number.isFinite(micros)) return "$0.0000";
+  return `$${(micros / 100_000_000).toFixed(4)}`;
+}
+
+function formatPercent(value: unknown): string {
+  const percent = Number(value ?? 0);
+  if (!Number.isFinite(percent)) return "0%";
+  return `${percent}%`;
+}

package/src/commands/api.ts

@@ -0,0 +1,297 @@
+import type { CliContext } from "../context.js";
+import { randomUUID } from "node:crypto";
+import { cliFormatError } from "../api-error.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\/[^/?#]+(?:[?#]|$)/ },
+];
+
+export interface ApiOptions {
+  field?: string[];
+  rawField?: string[];
+  header?: string[];
+  bodyStdin?: boolean;
+  body?: string;
+}
+
+export async function api(ctx: CliContext, methodOrPath: string | undefined, pathArg: string | undefined, opts: ApiOptions) {
+  const { method, path } = validateApiRequest(methodOrPath, pathArg, opts);
+
+  const headers = parseHeaders(opts.header ?? []);
+  const body = await buildBody(opts);
+  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);
+
+  if (!res.ok) {
+    throw cliFormatError(res.status, parsed);
+  }
+
+  return {
+    status: res.status,
+    body: parsed,
+    text,
+  };
+}
+
+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.");
+  }
+  assertAllowlisted(method, path);
+  parseHeaders(opts.header ?? []);
+  validateBodyFields(opts);
+  return { method, path };
+}
+
+export async function prepareApiOptions(opts: ApiOptions, read: () => Promise<string> = readStdin): Promise<ApiOptions> {
+  parseHeaders(opts.header ?? []);
+  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.");
+  return { ...opts, body, bodyStdin: false };
+}
+
+export function formatApiResult(result: Awaited<ReturnType<typeof api>>): string {
+  if (result.status === 204 || result.text.length === 0) return "";
+  return typeof result.body === "string" ? result.body : JSON.stringify(result.body, null, 2);
+}
+
+function normalizeTarget(methodOrPath: string | undefined, pathArg: string | undefined, hasBodyFields: boolean) {
+  const first = methodOrPath?.trim();
+  const second = pathArg?.trim();
+  if (!first) {
+    throw new Error("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");
+  }
+  if (METHODS.has(maybeMethod)) {
+    method = maybeMethod;
+    path = second as string;
+  } else if (second) {
+    const suggestion = closestChoice(maybeMethod, METHOD_NAMES);
+    throw new Error(
+      `Unknown API method ${maybeMethod}. Allowed methods: ${METHOD_NAMES.join(", ")}.` +
+        (suggestion ? ` Did you mean ${suggestion}?` : ""),
+    );
+  } else {
+    method = hasBodyFields ? "POST" : "GET";
+    path = first;
+  }
+
+  if (!path.startsWith("/")) {
+    throw new Error("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.");
+  }
+  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;
+
+  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." +
+      (suggestion ? ` Did you mean ${method} ${suggestion}?` : ""),
+  );
+}
+
+function apiRouteSuggestion(path: string): string | null {
+  const replacements: Array<[RegExp, string]> = [
+    [/^\/analytics(?=\/|[?#]|$)/, "/api/analytics"],
+    [/^\/billing(?=\/|[?#]|$)/, "/api/billing"],
+    [/^\/limits(?=\/|[?#]|$)/, "/api/limits"],
+    [/^\/members(?=\/|[?#]|$)/, "/api/members"],
+    [/^\/usage(?=\/|[?#]|$)/, "/api/usage"],
+    [/^\/webhook_endpoints(?=\/|[?#]|$)/, "/api/webhook_endpoints"],
+  ];
+  for (const [pattern, replacement] of replacements) {
+    if (pattern.test(path)) return path.replace(pattern, replacement);
+  }
+  return null;
+}
+
+function hasFields(opts: ApiOptions): boolean {
+  return (opts.field?.length ?? 0) > 0 || (opts.rawField?.length ?? 0) > 0 || !!opts.bodyStdin || opts.body !== undefined;
+}
+
+function hasStructuredFields(opts: ApiOptions): boolean {
+  return (opts.field?.length ?? 0) > 0 || (opts.rawField?.length ?? 0) > 0;
+}
+
+function validateBodyFields(opts: ApiOptions): void {
+  if (opts.bodyStdin && hasStructuredFields(opts)) {
+    throw new Error("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");
+}
+
+async function buildBody(opts: ApiOptions): Promise<string | undefined> {
+  if (opts.body !== undefined) return opts.body;
+  const fields: Record<string, unknown> = {};
+  for (const raw of opts.field ?? []) {
+    const [key, value] = splitAssignment(raw, "--field");
+    fields[key] = coerceField(value);
+  }
+  for (const raw of opts.rawField ?? []) {
+    const [key, value] = splitAssignment(raw, "--raw-field");
+    fields[key] = value;
+  }
+
+  if (Object.keys(fields).length > 0) return JSON.stringify(fields);
+  if (opts.bodyStdin) return readStdin();
+  return undefined;
+}
+
+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'.`);
+    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'.`);
+    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.`);
+    }
+    headers[key] = value;
+  }
+  if (Object.keys(headers).length > 0) return headers;
+  return {};
+}
+
+function hasHeader(headers: Record<string, string>, name: string): boolean {
+  const normalized = name.toLowerCase();
+  return Object.keys(headers).some((key) => key.toLowerCase() === normalized);
+}
+
+function splitAssignment(raw: string, flag: string): [string, string] {
+  const idx = raw.indexOf("=");
+  if (idx <= 0) throw new Error(`Invalid ${flag} '${raw}'. Use key=value.`);
+  const key = raw.slice(0, idx).trim();
+  if (!key) throw new Error(`Invalid ${flag} '${raw}'. Use key=value.`);
+  return [key, raw.slice(idx + 1)];
+}
+
+function coerceField(value: string): unknown {
+  if (value === "true") return true;
+  if (value === "false") return false;
+  if (value === "null") return null;
+  if (/^-?\d+(?:\.\d+)?$/.test(value)) return Number(value);
+  if (/^[\[{]/.test(value)) {
+    try {
+      return JSON.parse(value);
+    } catch {
+      return value;
+    }
+  }
+  return value;
+}
+
+function parseMaybeJson(text: string): unknown {
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+async function readStdin(): Promise<string> {
+  if (process.stdin.isTTY) {
+    throw new Error(
+      "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.");
+  return text;
+}

package/src/commands/appearance.ts

@@ -0,0 +1,79 @@
+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";
+
+export interface AppearanceEnvelope {
+  agent: {
+    id: string;
+    slug: string;
+    name: string;
+  };
+  appearance: Record<string, unknown>;
+  resolved_appearance: Record<string, unknown>;
+}
+
+export interface AppearanceOptions extends AgentInferOptions {
+  file?: string;
+}
+
+export async function appearanceGetData(ctx: CliContext, opts: AgentInferOptions): Promise<AppearanceEnvelope> {
+  const slug = await inferAgentSlug(opts);
+  return ctx.http.request<AppearanceEnvelope>({
+    path: `/api/agents/${encodeURIComponent(slug)}/appearance`,
+  });
+}
+
+export async function appearanceGet(ctx: CliContext, opts: AgentInferOptions): Promise<string> {
+  const res = await appearanceGetData(ctx, opts);
+  return JSON.stringify(res.appearance, null, 2);
+}
+
+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");
+  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 },
+  });
+}
+
+export async function appearanceSet(ctx: CliContext, opts: AppearanceOptions): Promise<string> {
+  const res = await appearanceSetData(ctx, opts);
+  return `Saved appearance for ${res.agent.slug}.`;
+}
+
+export async function validateAppearanceSetInput(opts: AppearanceOptions): Promise<void> {
+  if (!opts.file) throw new Error("Pass --file <file>. Usage: dharta appearance set --file appearance.json");
+  await readAppearanceFile(opts.file);
+}
+
+async function readAppearanceFile(file: string): Promise<Record<string, unknown>> {
+  const normalized = normalizeNonBlank(file, "--file");
+  let text: string;
+  try {
+    text = await readFile(normalized, "utf8");
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") throw new Error(`Cannot read --file ${normalized}: file does not exist.`);
+    if (code === "EISDIR") throw new Error(`Cannot read --file ${normalized}: expected a file, got a directory.`);
+    throw new Error(`Cannot read --file ${normalized}: ${(error as Error).message}`);
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new Error(`--file ${normalized} must contain valid JSON.`);
+  }
+
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`--file ${normalized} must contain a JSON object.`);
+  }
+  return parsed as Record<string, unknown>;
+}