@k2b/cloud 0.6.0-rc.0

package/src/cli/admin/instance.ts

@@ -0,0 +1,250 @@
+/**
+ * Instance-wide entry points: `status` for a quick verdict and `diagnose`
+ * for the bounded, agent-oriented troubleshooting bundle.
+ */
+import { command, flag } from "../index";
+import type { PostgresDiagnostics, RedisDiagnostics } from "./data";
+import type { GatewayHealth } from "./gateway";
+import type { BackgroundJobRow } from "./jobs";
+import { getLogs, type LogSummary, trimLogMessages } from "./logs";
+import type { NatsSnapshot } from "./nats";
+import type { SyncOverview } from "./sync";
+import type { MetricsCollector } from "./metrics";
+import { apiGet, formatBytes, parseLookbackHours, printJsonOrTable, queryString, safeCollect, skippedCollect, truncate } from "./shared";
+import type { TelemetryEvent, TelemetryRouteRow } from "./telemetry";
+import { diagnoseRange } from "./telemetry";
+
+export const DIAGNOSE_SECTIONS = ["health", "logs", "telemetry", "jobs", "postgres", "redis", "metrics", "sync", "nats"] as const;
+export type DiagnoseSection = (typeof DIAGNOSE_SECTIONS)[number];
+
+export const parseDiagnoseSections = (value: string | undefined, label: string): Set<DiagnoseSection> | null => {
+  if (!value) return null;
+  const sections = new Set<DiagnoseSection>();
+  for (const raw of value.split(",")) {
+    const section = raw.trim();
+    if (!section) continue;
+    if (!DIAGNOSE_SECTIONS.includes(section as DiagnoseSection)) {
+      throw new Error(`${label} must contain only: ${DIAGNOSE_SECTIONS.join(", ")}.`);
+    }
+    sections.add(section as DiagnoseSection);
+  }
+  return sections;
+};
+
+export const instanceCommands = [
+  command("status", {
+    summary: "Show gateway and app health",
+    run: async ({ ctx }) => {
+      const health = await apiGet<GatewayHealth>(ctx, "/api/gateway/health");
+      const row = {
+        status: health.status,
+        apps: health.summary.apps,
+        healthy: health.summary.healthy,
+        degraded: health.summary.degraded,
+        offline: health.summary.offline,
+        routes: health.summary.routes,
+        requests: health.summary.requests,
+        errors: health.summary.errors,
+      };
+      printJsonOrTable(
+        ctx,
+        health,
+        [row],
+        [
+          { key: "status" },
+          { key: "apps" },
+          { key: "healthy" },
+          { key: "degraded" },
+          { key: "offline" },
+          { key: "routes" },
+          { key: "requests" },
+          { key: "errors" },
+        ],
+      );
+    },
+  }),
+  command("diagnose", {
+    summary: "Collect a bounded diagnostics bundle for agents",
+    flags: {
+      since: flag.string({ default: "24h", description: "Lookback window like 30m, 6h, or 7d" }),
+      logLimit: flag.int({ name: "log-limit", default: 20, min: 1, max: 50, description: "Recent error/warn logs per level" }),
+      include: flag.string({ description: "Comma-separated sections: health,logs,telemetry,jobs,postgres,redis,metrics,sync,nats" }),
+      skip: flag.string({ description: "Comma-separated sections to skip" }),
+      messageLength: flag.int({
+        name: "message-length",
+        default: 500,
+        min: 40,
+        max: 5000,
+        description: "Log message length in JSON bundle",
+      }),
+      fullLogs: flag.boolean({ name: "full-logs", description: "Do not trim log messages in the JSON bundle" }),
+    },
+    run: async ({ ctx, flags }) => {
+      const hours = parseLookbackHours(flags.since);
+      const logLimit = flags.logLimit ?? 20;
+      const include = parseDiagnoseSections(flags.include, "--include");
+      const skip = parseDiagnoseSections(flags.skip, "--skip");
+      const shouldCollect = (section: DiagnoseSection) => (!include || include.has(section)) && !skip?.has(section);
+      const [
+        health,
+        logSummary,
+        logErrors,
+        logWarnings,
+        telemetrySummary,
+        telemetryErrors,
+        failingRoutes,
+        jobs,
+        postgres,
+        redis,
+        metrics,
+        sync,
+        nats,
+      ] = await Promise.all([
+        shouldCollect("health")
+          ? safeCollect("gateway health", () => apiGet<GatewayHealth>(ctx, "/api/gateway/health"))
+          : skippedCollect("gateway health"),
+        shouldCollect("logs")
+          ? safeCollect("log summary", () => apiGet<LogSummary>(ctx, "/api/logging/summary"))
+          : skippedCollect("log summary"),
+        shouldCollect("logs")
+          ? safeCollect("error logs", () => getLogs(ctx, { level: "error", sinceHours: hours, perPage: logLimit }))
+          : skippedCollect("error logs"),
+        shouldCollect("logs")
+          ? safeCollect("warning logs", () => getLogs(ctx, { level: "warn", sinceHours: hours, perPage: logLimit }))
+          : skippedCollect("warning logs"),
+        shouldCollect("telemetry")
+          ? safeCollect("telemetry summary", () =>
+              apiGet<Record<string, number | null>>(ctx, `/api/gateway/telemetry/summary${queryString({ hours })}`),
+            )
+          : skippedCollect("telemetry summary"),
+        shouldCollect("telemetry")
+          ? safeCollect("telemetry errors", () =>
+              apiGet<{ items: TelemetryEvent[]; total: number }>(
+                ctx,
+                `/api/gateway/telemetry/events${queryString({ errors: "1", hours, page: 1, per_page: Math.min(logLimit, 50) })}`,
+              ),
+            )
+          : skippedCollect("telemetry errors"),
+        // The single most useful line in the bundle: a total request count
+        // says nothing when one route dominates traffic, whereas a ranked
+        // list names the endpoints actually failing.
+        shouldCollect("telemetry")
+          ? safeCollect("failing routes", () =>
+              apiGet<{ items: TelemetryRouteRow[] }>(
+                ctx,
+                `/api/gateway/telemetry/routes${queryString({ range: diagnoseRange(hours), sort: "errorRate", errors: "1", limit: 10 })}`,
+              ),
+            )
+          : skippedCollect("failing routes"),
+        shouldCollect("jobs")
+          ? safeCollect("background jobs", () =>
+              apiGet<{ items: BackgroundJobRow[] }>(ctx, `/api/gateway/jobs${queryString({ health: "failed" })}`),
+            )
+          : skippedCollect("background jobs"),
+        shouldCollect("postgres")
+          ? safeCollect("postgres", () => apiGet<PostgresDiagnostics>(ctx, "/api/gateway/data/postgres"))
+          : skippedCollect("postgres"),
+        shouldCollect("redis")
+          ? safeCollect("redis", () => apiGet<RedisDiagnostics>(ctx, "/api/gateway/data/redis"))
+          : skippedCollect("redis"),
+        shouldCollect("metrics")
+          ? safeCollect("metrics", () =>
+              apiGet<{ generatedAt: string; series: number; collectors: MetricsCollector[] }>(ctx, "/api/gateway/metrics/snapshot"),
+            )
+          : skippedCollect("metrics"),
+        shouldCollect("sync")
+          ? safeCollect("sync", async () => {
+              const snapshot = await apiGet<SyncOverview>(ctx, "/api/gateway/sync?problems=true");
+              // Support bundles need failure context, not user payload previews.
+              return { ...snapshot, deadLetters: snapshot.deadLetters.map(({ dataPreview: _preview, ...entry }) => entry) };
+            })
+          : skippedCollect("sync"),
+        shouldCollect("nats")
+          ? safeCollect("nats", () => apiGet<NatsSnapshot>(ctx, "/api/gateway/nats?problems=true&limit=20"))
+          : skippedCollect("nats"),
+      ]);
+      const bundle = {
+        generatedAt: new Date().toISOString(),
+        lookbackHours: hours,
+        health,
+        logs: {
+          summary: logSummary,
+          errors:
+            logErrors.ok && !flags.fullLogs
+              ? { ...logErrors, data: trimLogMessages(logErrors.data, flags.messageLength ?? 500) }
+              : logErrors,
+          warnings:
+            logWarnings.ok && !flags.fullLogs
+              ? { ...logWarnings, data: trimLogMessages(logWarnings.data, flags.messageLength ?? 500) }
+              : logWarnings,
+        },
+        telemetry: { summary: telemetrySummary, errors: telemetryErrors, failingRoutes },
+        jobs,
+        postgres,
+        redis,
+        metrics,
+        sync,
+        nats,
+      };
+      if (ctx.options.output === "json") {
+        ctx.json(bundle);
+        return;
+      }
+
+      const lines = ["Cloud admin diagnose", `lookback: ${hours}h`, ""];
+      if (health.ok) {
+        lines.push(
+          `gateway: ${health.data.status}`,
+          `apps: ${health.data.summary.healthy ?? 0} healthy, ${health.data.summary.degraded ?? 0} degraded, ${health.data.summary.offline ?? 0} offline`,
+        );
+      } else lines.push(`gateway: unavailable (${health.error})`);
+      if (logSummary.ok) {
+        lines.push(
+          `logs: ${logSummary.data.errors24h} errors / ${logSummary.data.warnings24h} warnings in 24h, ${logSummary.data.total} retained`,
+        );
+      } else lines.push(`logs: unavailable (${logSummary.error})`);
+      if (telemetrySummary.ok) {
+        lines.push(`telemetry: ${telemetrySummary.data.requests ?? 0} requests, ${telemetrySummary.data.errors ?? 0} errors`);
+      } else lines.push(`telemetry: unavailable (${telemetrySummary.error})`);
+      if (failingRoutes.ok) {
+        const worst = failingRoutes.data.items.slice(0, 3);
+        lines.push(
+          worst.length === 0
+            ? "failing routes: none"
+            : `failing routes: ${worst.map((row) => `${row.route} ${row.errors}/${row.requests}`).join(", ")}`,
+        );
+      } else if (!("skipped" in failingRoutes)) lines.push(`failing routes: unavailable (${failingRoutes.error})`);
+      if (jobs.ok)
+        lines.push(`failing jobs: ${jobs.data.items.length === 0 ? "none" : jobs.data.items.map((row) => row.source).join(", ")}`);
+      else if (!("skipped" in jobs)) lines.push(`failing jobs: unavailable (${jobs.error})`);
+      if (postgres.ok)
+        lines.push(
+          `postgres: ${postgres.data.tables} tables, ${formatBytes(postgres.data.totalBytes)}, ${postgres.data.warnings.length} warnings`,
+        );
+      else lines.push(`postgres: unavailable (${postgres.error})`);
+      if (redis.ok) lines.push(`redis: ${redis.data.dbSize} keys, ${redis.data.warnings.length} warnings`);
+      else lines.push(`redis: unavailable (${redis.error})`);
+      if (metrics.ok) {
+        const failed = metrics.data.collectors.filter((collector) => collector.status !== "ok");
+        lines.push(`metrics: ${metrics.data.series} series, ${failed.length} failed collectors`);
+      } else lines.push(`metrics: unavailable (${metrics.error})`);
+      if (sync.ok)
+        lines.push(
+          `sync: ${sync.data.resources.length} resources needing attention; ${sync.data.deadLetters.length}${sync.data.truncatedStores.length ? "+" : ""} sampled dead letters; ${sync.data.apps.filter((app) => app.status !== "ok").length} unavailable apps`,
+        );
+      else if (!("skipped" in sync)) lines.push(`sync: unavailable (${sync.error})`);
+      if (nats.ok)
+        lines.push(
+          `nats: cluster ${nats.data.cluster.status}; inventory ${nats.data.inventory.status}; ${nats.data.inventory.matchedTotal ?? "unknown"} streams needing attention`,
+        );
+      else if (!("skipped" in nats)) lines.push(`nats: unavailable (${nats.error})`);
+      if (logErrors.ok && logErrors.data.entries.length > 0) {
+        lines.push("", "recent errors:");
+        for (const entry of logErrors.data.entries.slice(0, 5)) {
+          lines.push(`- [${entry.createdAt}] ${entry.source}: ${truncate(entry.message, 140)} (#${entry.id})`);
+        }
+      }
+      ctx.print(lines.join("\n"));
+    },
+  }),
+];

package/src/cli/admin/jobs.ts

@@ -0,0 +1,223 @@
+/**
+ * Background jobs and scheduled work, read through the trace spans every
+ * Cloud job records. Until now this was the one observability domain with no
+ * CLI at all — visible in the admin UI, invisible to scripts and agents.
+ *
+ * Read-only. Triggering a schedule stays a deliberate action in the admin UI.
+ */
+import { arg, command, flag, paginationFlags } from "../index";
+import { apiGet, formatMs, pageQuery, printJsonOrTable, queryString, truncate } from "./shared";
+
+export type BackgroundJobTrace = {
+  runs: number;
+  failed: number;
+  running: number;
+  stuck: number;
+  anomalous: number;
+  latestStatus: string | null;
+  latestStartedAt: string | null;
+  latestEndedAt: string | null;
+  avgDurationMs: number | null;
+  categories: string[];
+};
+
+export type BackgroundJobRow = {
+  kind: "schedule" | "trace";
+  source: string;
+  label?: string | null;
+  appId?: string | null;
+  cron?: string | null;
+  trace: BackgroundJobTrace | null;
+};
+
+export type TraceSpan = {
+  traceId: string;
+  spanId: string;
+  source: string;
+  appId: string | null;
+  category: string | null;
+  status: string;
+  /** Failure detail; the field is `statusMessage`, not `error`. */
+  statusMessage: string | null;
+  /** Structured per-run metadata (counts, ids); shape is job-specific. */
+  summary: Record<string, unknown> | null;
+  eventCount: number;
+  startedAt: string | null;
+  endedAt: string | null;
+  durationMs: number | null;
+};
+
+export type TraceEvent = {
+  name: string;
+  severity: string | null;
+  occurredAt: string | null;
+  body: string | null;
+  attributes: Record<string, unknown> | null;
+};
+
+const HEALTH_VALUES = ["all", "failed", "stuck", "running", "healthy"] as const;
+const WINDOW_VALUES = ["10m", "1h", "12h", "24h", "7d", "30d"] as const;
+
+const windowFlag = () => flag.enum(WINDOW_VALUES, { default: "24h", description: "Lookback window for run statistics" });
+const TYPE_VALUES = ["all", "job", "schedule", "backfill", "ai", "http", "notification", "sync", "custom"] as const;
+
+/** `traceId:spanId`, the identifier `jobs runs` prints and `jobs show` takes. */
+const runKey = (span: { traceId: string; spanId: string }): string => `${span.traceId}:${span.spanId}`;
+
+const jobRows = (items: BackgroundJobRow[]) =>
+  items.map((row) => ({
+    source: row.source,
+    kind: row.kind,
+    app: row.appId ?? "-",
+    schedule: row.cron ?? "-",
+    runs: row.trace?.runs ?? 0,
+    failed: row.trace?.failed ?? 0,
+    running: row.trace?.running ?? 0,
+    stuck: row.trace?.stuck ?? 0,
+    latest: row.trace?.latestStatus ?? "-",
+    avgMs: formatMs(row.trace?.avgDurationMs ?? null),
+  }));
+
+export const jobCommands = [
+  command("jobs list", {
+    summary: "List background jobs and schedules with their run health",
+    description:
+      "Joins registered schedules with recorded trace runs over the selected window. `--health failed` means the MOST RECENT run of a source failed, i.e. currently unhealthy — it does not list every source that has ever failed. `--health stuck` lists sources with spans left open past the abandonment threshold; those are not running, nothing is working on them. Use `jobs runs --source <id>` for run history.",
+    examples: [
+      "cld admin jobs list --json",
+      "cld admin jobs list --health stuck",
+      "cld admin jobs list --health failed --window 7d",
+      "cld admin jobs list --type backfill",
+      "cld admin jobs list --type schedule --search mail",
+    ],
+    flags: {
+      search: flag.string({ aliases: ["q"], description: "Free-text match on source, label, or app" }),
+      type: flag.enum(TYPE_VALUES, { default: "all", description: "Trace category" }),
+      health: flag.enum(HEALTH_VALUES, { default: "all", description: "Health of the source in this window" }),
+      window: windowFlag(),
+    },
+    run: async ({ ctx, flags }) => {
+      const raw = await apiGet<{ items: BackgroundJobRow[] }>(
+        ctx,
+        `/api/gateway/jobs${queryString({ search: flags.search, type: flags.type, health: flags.health, window: flags.window })}`,
+      );
+      printJsonOrTable(ctx, raw, jobRows(raw.items), [
+        { key: "source", label: "Source" },
+        { key: "kind", label: "Kind" },
+        { key: "app", label: "App" },
+        { key: "schedule", label: "Cron" },
+        { key: "runs", label: "Runs" },
+        { key: "failed", label: "Failed" },
+        { key: "running", label: "Running" },
+        { key: "stuck", label: "Stuck" },
+        { key: "latest", label: "Latest" },
+        { key: "avgMs", label: "Avg" },
+      ]);
+    },
+  }),
+
+  command("jobs stats", {
+    summary: "Show aggregate run counts across all background jobs",
+    description:
+      "Running counts spans in flight now; stuck counts spans left open past the abandonment threshold; anomalous counts finished runs longer than that threshold, which are excluded from the duration percentiles so those describe real runs.",
+    examples: ["cld admin jobs stats --json", "cld admin jobs stats --window 7d"],
+    flags: { source: flag.string({ description: "Restrict to one job source" }), window: windowFlag() },
+    run: async ({ ctx, flags }) => {
+      const raw = await apiGet<Record<string, number>>(
+        ctx,
+        `/api/gateway/jobs/stats${queryString({ source: flags.source, window: flags.window })}`,
+      );
+      printJsonOrTable(
+        ctx,
+        raw,
+        [raw],
+        [
+          { key: "runs", label: "Runs" },
+          { key: "sources", label: "Sources" },
+          { key: "running", label: "Running" },
+          { key: "stuck", label: "Stuck" },
+          { key: "anomalous", label: "Anomalous" },
+          { key: "succeeded", label: "Succeeded" },
+          { key: "failed", label: "Failed" },
+        ],
+      );
+    },
+  }),
+
+  command("jobs runs", {
+    summary: "List individual job runs, newest first",
+    description: "Scope with --source to one job. The printed run id is `<traceId>:<spanId>` and is what `jobs show` expects.",
+    examples: ["cld admin jobs runs --source gateway:telemetry:cleanup --json", "cld admin jobs runs --per-page 10"],
+    flags: {
+      source: flag.string({ description: "Restrict to one job source" }),
+      window: windowFlag(),
+      ...paginationFlags({ defaultPerPage: 25, maxPerPage: 200 }),
+    },
+    run: async ({ ctx, flags }) => {
+      const raw = await apiGet<{ items: TraceSpan[] }>(
+        ctx,
+        `/api/gateway/jobs/runs${queryString({ source: flags.source, window: flags.window, ...pageQuery(flags) })}`,
+      );
+      printJsonOrTable(
+        ctx,
+        raw,
+        raw.items.map((span) => ({
+          run: runKey(span),
+          source: span.source,
+          status: span.status,
+          startedAt: span.startedAt ?? "-",
+          durationMs: formatMs(span.durationMs),
+          error: truncate(span.statusMessage, 60) ?? "-",
+        })),
+        [
+          { key: "run", label: "Run" },
+          { key: "source", label: "Source" },
+          { key: "status", label: "Status" },
+          { key: "startedAt", label: "Started" },
+          { key: "durationMs", label: "Duration" },
+          { key: "error", label: "Error" },
+        ],
+      );
+    },
+  }),
+
+  command("jobs show", {
+    summary: "Show one job run with its recorded events",
+    description: "Events are the closest thing a background job has to a log. Take the run id from `jobs runs`.",
+    examples: ["cld admin jobs show <traceId>:<spanId> --json"],
+    args: { run: arg.required({ valueLabel: "run" }) },
+    run: async ({ ctx, args }) => {
+      const raw = await apiGet<{ span: TraceSpan | null; events: TraceEvent[] }>(
+        ctx,
+        `/api/gateway/jobs/runs/${encodeURIComponent(args.run)}`,
+      );
+      if (ctx.options.output === "json") {
+        ctx.json(raw);
+        return;
+      }
+      if (!raw.span) {
+        ctx.print("Run not found.");
+        return;
+      }
+      ctx.print(`${raw.span.source} — ${raw.span.status}`);
+      ctx.print(`started: ${raw.span.startedAt ?? "-"}  duration: ${formatMs(raw.span.durationMs)}`);
+      if (raw.span.summary) ctx.print(`summary: ${JSON.stringify(raw.span.summary)}`);
+      if (raw.span.statusMessage) ctx.print(`status message: ${raw.span.statusMessage}`);
+      ctx.print("");
+      ctx.table(
+        raw.events.map((event) => ({
+          occurredAt: event.occurredAt ?? "-",
+          severity: event.severity ?? "-",
+          name: event.name,
+          body: truncate(event.body, 80) ?? "-",
+        })),
+        [
+          { key: "occurredAt", label: "At" },
+          { key: "severity", label: "Level" },
+          { key: "name", label: "Event" },
+          { key: "body", label: "Detail" },
+        ],
+      );
+    },
+  }),
+];

package/src/cli/admin/legal.ts

@@ -0,0 +1,122 @@
+import { arg, type CloudCliContext, cliText, command, confirmFlag, flag, printRows, printStructured, readCliInput } from "../index";
+import { apiGet } from "./shared";
+
+const LEGAL_KINDS = ["terms", "privacy", "imprint"] as const;
+type LegalKind = (typeof LEGAL_KINDS)[number];
+type LegalMode = "local" | "external";
+
+type LegalDocument = {
+  kind: LegalKind;
+  path: string;
+  mode: LegalMode;
+  content: string;
+  url: string;
+};
+
+const legalApiPath = "/api/admin/core/settings";
+
+const parseKind = (value: string): LegalKind => {
+  if (LEGAL_KINDS.includes(value as LegalKind)) return value as LegalKind;
+  throw new Error(`Document must be one of: ${LEGAL_KINDS.join(", ")}.`);
+};
+
+const listDocuments = async (ctx: CloudCliContext): Promise<LegalDocument[]> =>
+  (await apiGet<{ items: LegalDocument[] }>(ctx, `${legalApiPath}/legal`)).items;
+
+const getDocument = async (ctx: CloudCliContext, kind: LegalKind): Promise<LegalDocument> => {
+  const document = (await listDocuments(ctx)).find((item) => item.kind === kind);
+  if (!document) throw new Error(`Legal document "${kind}" was not found.`);
+  return document;
+};
+
+const saveSettings = async (ctx: CloudCliContext, body: { updates?: Record<string, unknown>; resets?: string[] }): Promise<void> => {
+  const response = await ctx.fetch(legalApiPath, {
+    method: "PUT",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  if (response.ok) return;
+  await ctx.readJson(response);
+  throw new Error(`Settings request failed with ${response.status}.`);
+};
+
+const printDocument = (ctx: CloudCliContext, document: LegalDocument) => {
+  if (printStructured(ctx, document)) return;
+  ctx.print(
+    [
+      `${document.kind} (${document.mode})`,
+      `Path: ${document.path}`,
+      ...(document.mode === "external" ? [`URL: ${document.url || "-"}`] : ["", document.content || "No local content configured."]),
+    ].join("\n"),
+  );
+};
+
+export const legalCommands = [
+  command("legal list", {
+    summary: "List Terms, Privacy, and Imprint configuration",
+    run: async ({ ctx }) => {
+      const items = await listDocuments(ctx);
+      printRows(
+        ctx,
+        items,
+        items.map((document) => ({
+          document: document.kind,
+          source: document.mode,
+          target: document.mode === "external" ? document.url : document.path,
+        })),
+        [{ key: "document" }, { key: "source" }, { key: "target" }],
+      );
+    },
+  }),
+  command("legal get", {
+    summary: "Show one legal document configuration",
+    args: { document: arg.required({ valueLabel: "terms|privacy|imprint" }) },
+    run: async ({ ctx, args }) => printDocument(ctx, await getDocument(ctx, parseKind(args.document))),
+  }),
+  command("legal set", {
+    summary: "Publish local Markdown or redirect to an external URL",
+    args: { document: arg.required({ valueLabel: "terms|privacy|imprint" }) },
+    flags: {
+      content: flag.input({ description: "Local Markdown; pass a value, --content-file, or --stdin" }),
+      url: flag.string({ description: "External URL" }),
+    },
+    examples: ["cld admin legal set terms --content-file ./terms.md", "cld admin legal set privacy --url https://example.org/privacy"],
+    run: async ({ ctx, args, flags }) => {
+      const kind = parseKind(args.document);
+      const contentProvided = flags.content.provided;
+      const urlProvided = flags.url !== undefined;
+      if (contentProvided === urlProvided) throw new Error("Pass exactly one of --content, --content-file, --stdin, or --url.");
+
+      const mode: LegalMode = contentProvided ? "local" : "external";
+      const value = contentProvided ? await readCliInput(flags.content, { label: `${kind} Markdown`, required: true }) : flags.url?.trim();
+      if (mode === "external" && !value) throw new Error("--url must not be empty.");
+
+      await saveSettings(ctx, {
+        updates: {
+          [`legal.${kind}.mode`]: mode,
+          [`legal.${kind}.${mode === "local" ? "content" : "url"}`]: value ?? "",
+        },
+      });
+      const result = { document: kind, mode };
+      if (!printStructured(ctx, result)) {
+        ctx.print(cliText(ctx, { en: `Updated ${kind}.`, de: `${kind} wurde aktualisiert.` }));
+      }
+    },
+  }),
+  command("legal reset", {
+    summary: "Reset one legal document to its defaults",
+    args: { document: arg.required({ valueLabel: "terms|privacy|imprint" }) },
+    flags: { yes: confirmFlag("Reset the legal document") },
+    run: async ({ ctx, args, flags }) => {
+      const kind = parseKind(args.document);
+      if (!flags.yes) throw new Error("Refusing to reset without --yes.");
+      await saveSettings(ctx, {
+        resets: [`legal.${kind}.mode`, `legal.${kind}.content`, `legal.${kind}.url`],
+      });
+      const result = { document: kind, reset: true };
+      if (!printStructured(ctx, result)) {
+        ctx.print(cliText(ctx, { en: `Reset ${kind}.`, de: `${kind} wurde zurückgesetzt.` }));
+      }
+    },
+  }),
+];

package/src/cli/admin/linux.ts

@@ -0,0 +1,53 @@
+import { LinuxIdentityConfigurationSchema, type LinuxIdentityConfiguration } from "../../contracts/posix";
+import { cliText, command, confirmFlag, flag, printStructured, readCliInput } from "../index";
+import { apiGet, apiJson, queryString } from "./shared";
+
+const path = "/api/admin/core/linux-identities";
+
+export const linuxCommands = [
+  command("linux preview", {
+    summary: "Inspect one page of Linux identities without changing accounts",
+    flags: {
+      after: flag.string({ description: "Continue after the previous page's nextCursor" }),
+      search: flag.string({ description: "Filter by username substring" }),
+      scope: flag.enum(["ready", "all"] as const, { description: "Show eligible accounts missing Linux attributes or all accounts (default)" }),
+    },
+    async run({ ctx, flags }) {
+      const result = await apiGet<unknown>(ctx, `${path}${queryString({ after: flags.after, search: flags.search, scope: flags.scope })}`);
+      if (!printStructured(ctx, result)) ctx.print(JSON.stringify(result, null, 2));
+    },
+  }),
+  command("linux config get", {
+    summary: "Export the complete Linux identity configuration",
+    async run({ ctx }) {
+      const { config } = await apiGet<{ config: LinuxIdentityConfiguration }>(ctx, path);
+      if (!printStructured(ctx, config)) ctx.print(JSON.stringify(config, null, 2));
+    },
+  }),
+  command("linux config set", {
+    summary: "Replace the complete Linux identity configuration",
+    flags: {
+      config: flag.input({ required: true, description: "Configuration JSON: --config, --config-file, or --stdin" }),
+      rangeReserved: flag.boolean({ name: "range-reserved", description: "Confirm the range is reserved across all connected systems" }),
+      yes: confirmFlag("Confirm replacing Linux identity configuration"),
+    },
+    async run({ ctx, flags }) {
+      if (!flags.yes)
+        throw new Error(
+          cliText(ctx, { en: "Refusing to change configuration without --yes.", de: "Konfiguration wird ohne --yes nicht geändert." }),
+        );
+      const input = await readCliInput(flags.config, { label: "Linux configuration", required: true });
+      if (input === undefined) throw new Error("Missing Linux configuration.");
+      const config = LinuxIdentityConfigurationSchema.parse(JSON.parse(input));
+      if (config.enabled && !flags.rangeReserved)
+        throw new Error(
+          cliText(ctx, {
+            en: "Enabling Linux identities requires --range-reserved.",
+            de: "Zum Aktivieren ist --range-reserved erforderlich.",
+          }),
+        );
+      const result = await apiJson<unknown>(ctx, "PUT", `${path}/configuration`, { config, rangeReserved: flags.rangeReserved });
+      if (!printStructured(ctx, result)) ctx.print(JSON.stringify(result, null, 2));
+    },
+  }),
+];