@k2b/cloud 0.6.0-rc.0

package/src/cli/account.ts

@@ -0,0 +1,382 @@
+import { readFile } from "node:fs/promises";
+import { arg, type CliInputFlagValue, type CloudCliContext, command, confirmFlag, defineCliCommands, flag, readCliInput } from "./index";
+
+type User = {
+  id: string;
+  uid: string;
+  provider: "ipa" | "local";
+  profile: "user" | "guest";
+  roles: string[];
+  givenname: string;
+  sn: string;
+  displayName: string;
+  mail: string | null;
+  memberofGroup: string[];
+  manages: string[];
+  accountExpires: string | null;
+  lastLoginLocal: string | null;
+  ipa: null | {
+    phone: string | null;
+    address: {
+      street: string | null;
+      postalCode: string | null;
+      city: string | null;
+      state: string | null;
+    };
+    passwordExpires: string | null;
+    lastLoginIpa: string | null;
+    sshPublicKeys: string[];
+    sshFingerprints: string[];
+  };
+};
+
+type ApiKey = {
+  id: string;
+  name: string;
+  status: "active" | "revoked";
+  tokenPrefix: string;
+  expiresAt: string | null;
+  lastUsedAt: string | null;
+  createdAt: string;
+};
+
+type AccountActivity = {
+  id: number;
+  createdAt: string;
+  action: string;
+  label: string;
+  outcome: "allowed" | "denied" | "failed";
+};
+
+type ProfileUpdateFlags = {
+  givenName?: string;
+  lastName?: string;
+  displayName?: string;
+  phone?: string;
+  street?: string;
+  postalCode?: string;
+  city?: string;
+  state?: string;
+};
+
+const apiPath = (path = "") => `/api/me${path === "/" ? "" : path}`;
+
+const readApi = async <T>(ctx: CloudCliContext, path: string, init?: RequestInit): Promise<T> =>
+  ctx.readJson<T>(await ctx.fetch(apiPath(path), init));
+
+const jsonRequest = (method: string, value?: unknown): RequestInit => ({
+  method,
+  headers: value === undefined ? undefined : { "Content-Type": "application/json" },
+  body: value === undefined ? undefined : JSON.stringify(value),
+});
+
+const printJsonOrTable = <TRow extends Record<string, unknown>>(
+  ctx: CloudCliContext,
+  value: unknown,
+  rows: TRow[],
+  columns: Parameters<CloudCliContext["table"]>[1],
+) => {
+  if (ctx.options.output === "json") ctx.json(value);
+  else ctx.table(rows, columns);
+};
+
+const parseExpiry = (value: string | undefined): string | null => {
+  if (!value) return null;
+  const relative = value.match(/^(\d+)([dwmqy])$/i);
+  if (relative) {
+    const amount = Number.parseInt(relative[1]!, 10);
+    const unit = relative[2]!.toLowerCase();
+    const days = unit === "d" ? amount : unit === "w" ? amount * 7 : unit === "m" ? amount * 30 : unit === "q" ? amount * 90 : amount * 365;
+    return new Date(Date.now() + days * 24 * 60 * 60 * 1000).toISOString();
+  }
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) throw new Error('--expires must be an ISO timestamp or a duration like "90d".');
+  return date.toISOString();
+};
+
+const userRows = (user: User) => [
+  { key: "uid", value: user.uid },
+  { key: "name", value: user.displayName },
+  { key: "mail", value: user.mail ?? "" },
+  { key: "provider", value: user.provider },
+  { key: "profile", value: user.profile },
+  { key: "roles", value: user.roles.join(", ") },
+];
+
+const profileRows = (user: User) => [
+  ...userRows(user),
+  { key: "given name", value: user.givenname },
+  { key: "last name", value: user.sn },
+  { key: "phone", value: user.ipa?.phone ?? "" },
+  { key: "street", value: user.ipa?.address.street ?? "" },
+  { key: "postal code", value: user.ipa?.address.postalCode ?? "" },
+  { key: "city", value: user.ipa?.address.city ?? "" },
+  { key: "state", value: user.ipa?.address.state ?? "" },
+  { key: "groups", value: user.memberofGroup.join(", ") },
+  { key: "manages", value: user.manages.join(", ") },
+];
+
+const apiKeyRows = (keys: ApiKey[]) =>
+  keys.map((key) => ({
+    id: key.id,
+    name: key.name,
+    prefix: key.tokenPrefix,
+    expires: key.expiresAt ?? "never",
+    lastUsed: key.lastUsedAt ?? "never",
+    created: key.createdAt,
+  }));
+
+const activityRows = (items: AccountActivity[]) =>
+  items.map((item) => ({
+    id: item.id,
+    time: item.createdAt,
+    outcome: item.outcome,
+    action: item.action,
+    label: item.label,
+  }));
+
+const buildProfileUpdate = (flags: ProfileUpdateFlags) => {
+  const data: {
+    givenname?: string;
+    sn?: string;
+    displayName?: string;
+    ipa?: {
+      phone?: string;
+      address?: {
+        street?: string;
+        postalCode?: string;
+        city?: string;
+        state?: string;
+      };
+      sshPublicKeys?: string[];
+    };
+  } = {};
+
+  if (flags.givenName !== undefined) data.givenname = flags.givenName;
+  if (flags.lastName !== undefined) data.sn = flags.lastName;
+  if (flags.displayName !== undefined) data.displayName = flags.displayName;
+
+  if ([flags.phone, flags.street, flags.postalCode, flags.city, flags.state].some((value) => value !== undefined)) {
+    data.ipa = {};
+    if (flags.phone !== undefined) data.ipa.phone = flags.phone;
+    if ([flags.street, flags.postalCode, flags.city, flags.state].some((value) => value !== undefined)) {
+      data.ipa.address = {};
+      if (flags.street !== undefined) data.ipa.address.street = flags.street;
+      if (flags.postalCode !== undefined) data.ipa.address.postalCode = flags.postalCode;
+      if (flags.city !== undefined) data.ipa.address.city = flags.city;
+      if (flags.state !== undefined) data.ipa.address.state = flags.state;
+    }
+  }
+
+  if (Object.keys(data).length === 0) throw new Error("No profile fields provided.");
+  return data;
+};
+
+const getCurrentUser = (ctx: CloudCliContext): Promise<User> => readApi<User>(ctx, "/");
+
+const updateProfile = async (ctx: CloudCliContext, data: unknown) => {
+  const result = await readApi<{ message: string }>(ctx, "/", jsonRequest("PATCH", data));
+  if (ctx.options.output === "json") ctx.json(result);
+  else ctx.print(result.message);
+};
+
+const resolveApiKey = async (ctx: CloudCliContext, ref: string): Promise<ApiKey> => {
+  const { items } = await readApi<{ items: ApiKey[] }>(ctx, "/api-keys");
+  const matches = items.filter((key) => key.id === ref || key.tokenPrefix === ref || key.tokenPrefix.startsWith(ref) || key.name === ref);
+  if (matches.length === 0) throw new Error(`API key not found: ${ref}`);
+  if (matches.length > 1) throw new Error(`API key reference is ambiguous: ${ref}`);
+  return matches[0]!;
+};
+
+const requireIpaUser = (user: User): NonNullable<User["ipa"]> => {
+  if (!user.ipa) throw new Error("SSH keys and address fields are only available for IPA-backed accounts.");
+  return user.ipa;
+};
+
+const readPublicKey = async (file: string | undefined, valueParts: readonly string[]): Promise<string> => {
+  if (file && valueParts.length > 0) throw new Error("Pass either a public key argument or --file, not both.");
+  const key = file ? await readFile(file, "utf8") : valueParts.join(" ");
+  const trimmed = key.trim();
+  if (!trimmed) throw new Error("Missing SSH public key.");
+  return trimmed;
+};
+
+const removeSshKey = (user: User, ref: string): string[] => {
+  const ipa = requireIpaUser(user);
+  const matches = ipa.sshPublicKeys
+    .map((key, index) => ({ index, key, fingerprint: ipa.sshFingerprints[index] ?? "" }))
+    .filter((item) => item.key === ref || item.key.startsWith(ref) || item.fingerprint.startsWith(ref));
+  if (matches.length === 0) throw new Error(`SSH key not found: ${ref}`);
+  if (matches.length > 1) {
+    const candidates = matches.map((item) => `${item.fingerprint || "no fingerprint"} ${item.key.slice(0, 48)}`).join(", ");
+    throw new Error(`SSH key reference is ambiguous: ${ref}. Candidates: ${candidates}`);
+  }
+  const index = matches[0]!.index;
+  return ipa.sshPublicKeys.filter((_, keyIndex) => keyIndex !== index);
+};
+
+const readRequiredSecret = async (input: CliInputFlagValue, label: string): Promise<string> => {
+  const value = await readCliInput(input, { label, required: true, trimFinalNewline: true });
+  if (!value) throw new Error(`Missing ${label}.`);
+  return value;
+};
+
+export default defineCliCommands({
+  name: "account",
+  summary: "Manage the authenticated account, profile, personal API keys, and SSH keys.",
+  commands: [
+    command("whoami", {
+      summary: "Show the authenticated account",
+      run: async ({ ctx }) => {
+        const user = await getCurrentUser(ctx);
+        printJsonOrTable(ctx, user, userRows(user), [{ key: "key" }, { key: "value" }]);
+      },
+    }),
+    command("profile show", {
+      summary: "Show account profile fields",
+      run: async ({ ctx }) => {
+        const user = await getCurrentUser(ctx);
+        printJsonOrTable(ctx, user, profileRows(user), [{ key: "key" }, { key: "value" }]);
+      },
+    }),
+    command("profile set", {
+      summary: "Update account profile fields",
+      flags: {
+        givenName: flag.string({ name: "given-name", aliases: ["givenname"], description: "Given name" }),
+        lastName: flag.string({ name: "last-name", aliases: ["sn"], description: "Last name" }),
+        displayName: flag.string({ name: "display-name", aliases: ["displayName"], description: "Display name" }),
+        phone: flag.string({ description: "Phone number" }),
+        street: flag.string({ description: "Street address" }),
+        postalCode: flag.string({ name: "postal-code", aliases: ["postalCode"], description: "Postal code" }),
+        city: flag.string({ description: "City" }),
+        state: flag.string({ description: "State" }),
+      },
+      run: async ({ ctx, flags }) => {
+        await updateProfile(ctx, buildProfileUpdate(flags));
+      },
+    }),
+    command("activity", {
+      summary: "List recent account activity",
+      flags: {
+        days: flag.int({ default: 30, min: 1, max: 3650, description: "Number of days to include" }),
+      },
+      run: async ({ ctx, flags }) => {
+        const result = await readApi<{ items: AccountActivity[] }>(ctx, `/activity?days=${encodeURIComponent(String(flags.days ?? 30))}`);
+        printJsonOrTable(ctx, result, activityRows(result.items), [
+          { key: "time" },
+          { key: "outcome" },
+          { key: "action" },
+          { key: "label" },
+        ]);
+      },
+    }),
+    command("api-keys list", {
+      summary: "List personal API keys",
+      run: async ({ ctx }) => {
+        const result = await readApi<{ items: ApiKey[] }>(ctx, "/api-keys");
+        printJsonOrTable(ctx, result, apiKeyRows(result.items), [
+          { key: "name" },
+          { key: "prefix" },
+          { key: "expires" },
+          { key: "lastUsed" },
+          { key: "id" },
+        ]);
+      },
+    }),
+    command("api-keys create", {
+      summary: "Create a personal API key",
+      args: { name: arg.required({ valueLabel: "name", description: "API key name" }) },
+      flags: {
+        expires: flag.string({ description: "ISO timestamp or duration like 90d" }),
+      },
+      run: async ({ ctx, args, flags }) => {
+        const result = await readApi<{ credential: ApiKey; token: string }>(
+          ctx,
+          "/api-keys",
+          jsonRequest("POST", { name: args.name, expiresAt: parseExpiry(flags.expires) }),
+        );
+        if (ctx.options.output === "json") ctx.json(result);
+        else ctx.print(`Token: ${result.token}\nPrefix: ${result.credential.tokenPrefix}\nStore this token now. It cannot be shown again.`);
+      },
+    }),
+    command("api-keys revoke", {
+      summary: "Revoke a personal API key",
+      args: { ref: arg.required({ valueLabel: "id|prefix|name", description: "API key reference" }) },
+      flags: { yes: confirmFlag("Confirm API key revocation") },
+      run: async ({ ctx, args, flags }) => {
+        if (!flags.yes) throw new Error("Refusing to revoke without --yes.");
+        const key = await resolveApiKey(ctx, args.ref);
+        const result = await readApi<{ message: string }>(ctx, `/api-keys/${encodeURIComponent(key.id)}`, jsonRequest("DELETE"));
+        if (ctx.options.output === "json") ctx.json({ ...result, credential: key });
+        else ctx.print(result.message);
+      },
+    }),
+    command("ssh-keys list", {
+      summary: "List SSH public keys",
+      run: async ({ ctx }) => {
+        const user = await getCurrentUser(ctx);
+        const ipa = requireIpaUser(user);
+        const items = ipa.sshPublicKeys.map((key, index) => ({ fingerprint: ipa.sshFingerprints[index] ?? "", key }));
+        printJsonOrTable(ctx, { items }, items, [{ key: "fingerprint" }, { key: "key" }]);
+      },
+    }),
+    command("ssh-keys add", {
+      summary: "Add an SSH public key",
+      args: { publicKey: arg.rest({ valueLabel: "public-key", description: "SSH public key", required: false }) },
+      flags: { file: flag.string({ aliases: ["f"], description: "Read SSH public key from file" }) },
+      run: async ({ ctx, args, flags }) => {
+        const user = await getCurrentUser(ctx);
+        const ipa = requireIpaUser(user);
+        const key = await readPublicKey(flags.file, args.publicKey);
+        if (ipa.sshPublicKeys.includes(key)) throw new Error("SSH public key already exists.");
+        await updateProfile(ctx, { ipa: { sshPublicKeys: [...ipa.sshPublicKeys, key] } });
+      },
+    }),
+    command("ssh-keys remove", {
+      summary: "Remove an SSH public key",
+      args: { ref: arg.required({ valueLabel: "fingerprint|key-prefix", description: "SSH key fingerprint or key prefix" }) },
+      run: async ({ ctx, args }) => {
+        const user = await getCurrentUser(ctx);
+        await updateProfile(ctx, { ipa: { sshPublicKeys: removeSshKey(user, args.ref) } });
+      },
+    }),
+    command("password change", {
+      summary: "Change the account password",
+      flags: {
+        currentPassword: flag.input({
+          name: "current-password",
+          fileName: "current-password-file",
+          stdinName: false,
+          required: true,
+          description: "Current password or file",
+        }),
+        newPassword: flag.input({
+          name: "new-password",
+          fileName: "new-password-file",
+          stdinName: false,
+          required: true,
+          description: "New password or file",
+        }),
+      },
+      run: async ({ ctx, flags }) => {
+        const currentPassword = await readRequiredSecret(flags.currentPassword, "current password");
+        const newPassword = await readRequiredSecret(flags.newPassword, "new password");
+        const result = await readApi<{ message: string }>(
+          ctx,
+          "/password",
+          jsonRequest("POST", { currentPassword, newPassword, confirmPassword: newPassword }),
+        );
+        if (ctx.options.output === "json") ctx.json(result);
+        else ctx.print(result.message);
+      },
+    }),
+    command("extend", {
+      summary: "Request account extension",
+      run: async ({ ctx }) => {
+        const result = await readApi<{ message: string; newExpiry?: string }>(ctx, "/account-extension", jsonRequest("POST"));
+        if (ctx.options.output === "json") ctx.json(result);
+        else ctx.print(result.newExpiry ? `${result.message} New expiry: ${result.newExpiry}` : result.message);
+      },
+    }),
+  ],
+});

package/src/cli/admin/account-administration.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import { cliText, command, confirmFlag, flag, printStructured, readCliInput } from "../index";
+import { apiGet } from "./shared";
+
+const path = "/api/admin/core/settings";
+const Configuration = z.object({ requestsEnabled: z.boolean(), actionNotice: z.string() }).strict();
+
+export const accountAdministrationCommands = [
+  command("accounts administration get", {
+    summary: "Export account-request policy and the optional account/group follow-up template",
+    async run({ ctx }) {
+      const config = Configuration.parse(await apiGet(ctx, `${path}/account-administration`));
+      if (!printStructured(ctx, config)) ctx.print(JSON.stringify(config, null, 2));
+    },
+  }),
+  command("accounts administration set", {
+    summary: "Configure account requests and the optional Liquid-Markdown follow-up template",
+    flags: {
+      config: flag.input({ required: true, description: "JSON with requestsEnabled and actionNotice: --config, --config-file or --stdin" }),
+      yes: confirmFlag("Confirm changes to account requests and administrative follow-up notices"),
+    },
+    async run({ ctx, flags }) {
+      if (!flags.yes)
+        throw new Error(
+          cliText(ctx, {
+            en: "Account administration changes require --yes.",
+            de: "Änderungen an der Account-Verwaltung erfordern --yes.",
+          }),
+        );
+      const input = await readCliInput(flags.config, { required: true, label: "Account administration configuration" });
+      const config = Configuration.parse(JSON.parse(input ?? ""));
+      await ctx.readJson(
+        await ctx.fetch(path, {
+          method: "PUT",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({
+            updates: { "user.account_requests.enabled": config.requestsEnabled, "user.action_notice": config.actionNotice },
+          }),
+        }),
+      );
+      if (!printStructured(ctx, { saved: true }))
+        ctx.print(cliText(ctx, { en: "Account administration saved.", de: "Account-Verwaltung gespeichert." }));
+    },
+  }),
+];

package/src/cli/admin/account-categories.ts

@@ -0,0 +1,49 @@
+import { AccountCategoryPolicySchema } from "../../contracts/account-categories";
+import { cliText, command, confirmFlag, flag, printStructured, readCliInput } from "../index";
+import { apiGet } from "./shared";
+
+const path = "/api/admin/core/settings";
+export const accountCategoryCommands = [
+  command("accounts config get", {
+    summary: "Export account types, login visibility and the local Login label",
+    async run({ ctx }) {
+      const policy = AccountCategoryPolicySchema.parse(await apiGet(ctx, `${path}/account-categories`));
+      if (!printStructured(ctx, policy)) ctx.print(JSON.stringify(policy, null, 2));
+    },
+  }),
+  command("accounts config set", {
+    summary: "Replace account category policy; disabled categories lose user-bound access",
+    flags: {
+      config: flag.input({ required: true, description: "Complete configuration JSON: --config, --config-file or --stdin" }),
+      yes: confirmFlag("Confirm access changes, including your own account category"),
+    },
+    async run({ ctx, flags }) {
+      if (!flags.yes)
+        throw new Error(
+          cliText(ctx, {
+            en: "Account access changes require --yes. Keep an allowed admin or emergency token available.",
+            de: "Zugriffsänderungen erfordern --yes. Halte einen erlaubten Admin-Zugang oder Notfall-Token bereit.",
+          }),
+        );
+      const input = await readCliInput(flags.config, { required: true, label: "Account category configuration" });
+      const policy = AccountCategoryPolicySchema.parse(JSON.parse(input ?? ""));
+      const updates = Object.fromEntries(
+        Object.entries(policy).flatMap(([category, fields]) =>
+          Object.entries(fields).map(([field, value]) => [`user.category.${category}.${field}`, value]),
+        ),
+      );
+      const response = await ctx.fetch(path, {
+        method: "PUT",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ updates }),
+      });
+      if (!response.ok) {
+        await ctx.readJson(response);
+        throw new Error(`Account configuration failed (${response.status})`);
+      }
+      // Do not re-fetch after disabling the caller's own category: its next request is denied.
+      if (!printStructured(ctx, { saved: true }))
+        ctx.print(cliText(ctx, { en: "Account configuration saved.", de: "Account-Konfiguration gespeichert." }));
+    },
+  }),
+];

package/src/cli/admin/ai-usage.ts

@@ -0,0 +1,118 @@
+import { arg, command, flag } from "../index";
+import { apiGet, printJsonOrTable } from "./shared";
+import { AI_USAGE_RANGES, AI_USAGE_REASONS } from "../../shared/ai-usage";
+import type { AiUsageReport, AiUsageRun } from "../../ai/usage";
+const filters = {
+  range: flag.enum(AI_USAGE_RANGES, { default: "30d", description: "Response/run period" }),
+  until: flag.string({ description: "Fixed ISO end time; reuse report.query.until across pages" }),
+  userId: flag.string({ name: "user", description: "User UUID or unassigned" }),
+  modelProfileId: flag.string({ name: "model", description: "Model profile ID" }),
+  providerModel: flag.string({ name: "provider-model", description: "Actual provider model" }),
+  appId: flag.string({ name: "app", description: "Source application ID" }),
+  kind: flag.enum(["chat", "background", "tool"] as const, { description: "Run kind (runs only)" }),
+  status: flag.string({ description: "Run status, e.g. failed (runs only)" }),
+  task: flag.string({ description: "Exact task or tool name (runs only)" }),
+  errorCode: flag.string({ name: "error-code", description: "Stored error code (runs only)" }),
+  search: flag.string({ description: "Search task and error text (runs/facets only)" }),
+  rating: flag.enum(["up", "down"] as const, { description: "Rating (feedback only)" }),
+  reason: flag.enum(AI_USAGE_REASONS, { description: "Feedback reason (feedback only)" }),
+  sort: flag.enum(["runs", "tokens", "credits", "errors", "negative", "negativeRate"] as const, {
+    default: "runs",
+    description: "Comparison sort order",
+  }),
+  page: flag.int({ default: 1, min: 1 }),
+  perPage: flag.int({ name: "per-page", default: 50, min: 1, max: 100 }),
+};
+// HTTP validation is authoritative, also for dynamically discovered CLI modules.
+const params = (values: Record<string, string | number | undefined>) => {
+  const q = new URLSearchParams();
+  for (const [key, value] of Object.entries(values)) if (value !== undefined) q.set(key, String(value));
+  return q;
+};
+export const aiUsageCommands = [
+  ...(["report", "users", "models", "tasks", "apps", "launches", "capabilities", "feedback", "runs"] as const).map((section) =>
+    command(`ai usage ${section}`, {
+      summary:
+        section === "report"
+          ? "Summarize AI usage and coverage; use --json for the complete report"
+          : `List AI usage ${section}; supports --json and pagination`,
+      flags: filters,
+      run: async ({ ctx, flags }) => {
+        const report = await apiGet<AiUsageReport>(ctx, `/api/admin/core/ai-usage/report?${params(flags)}`);
+        if (section === "report" && ctx.options.output === "jsonl") return ctx.jsonLine(report);
+        if (section === "report")
+          return printJsonOrTable(
+            ctx,
+            report,
+            [report.overview],
+            [{ key: "runs" }, { key: "tokens" }, { key: "credits" }, { key: "failed" }, { key: "positive" }, { key: "negative" }],
+          );
+        const page = report[section];
+        if (ctx.options.output === "jsonl") {
+          for (const item of page.items) ctx.jsonLine(item);
+          return;
+        }
+        if (ctx.options.output === "json") return ctx.json({ ...page, query: report.query, since: report.since, until: report.until });
+        if (section === "runs")
+          ctx.table(report.runs.items, [
+            { key: "id" },
+            { key: "kind" },
+            { key: "task" },
+            { key: "status" },
+            { key: "userLabel" },
+            { key: "modelProfileId" },
+            { key: "error" },
+          ]);
+        else if (section === "feedback")
+          ctx.table(report.feedback.items, [
+            { key: "id" },
+            { key: "userLabel" },
+            { key: "modelProfileId" },
+            { key: "rating" },
+            { key: "comment" },
+          ]);
+        else if (section === "launches") ctx.table(report.launches.items, [{ key: "appId" }, { key: "chats" }, { key: "users" }]);
+        else
+          ctx.table(report[section].items, [
+            { key: "id" },
+            { key: "label" },
+            { key: "providerModel" },
+            { key: "runs" },
+            { key: "tokens" },
+            { key: "failed" },
+            { key: "positive" },
+            { key: "negative" },
+            { key: "rated" },
+          ]);
+        ctx.print(`Page ${page.page}; ${page.total} total. Snapshot until ${report.until}`);
+      },
+    }),
+  ),
+  command("ai usage get", {
+    summary: "Read one AI run, including its complete stored error and references",
+    args: { kind: arg.required(), id: arg.required() },
+    run: async ({ ctx, args }) => {
+      const result = await apiGet<AiUsageRun>(
+        ctx,
+        `/api/admin/core/ai-usage/runs/${encodeURIComponent(args.kind)}/${encodeURIComponent(args.id)}`,
+      );
+      ctx.json(result);
+    },
+  }),
+  command("ai usage facets", {
+    summary: "Find user IDs, model profiles, provider models, apps or tasks for filtering",
+    flags: {
+      field: flag.enum(["userId", "modelProfileId", "providerModel", "appId", "task"] as const, { required: true }),
+      search: flag.string(),
+      range: filters.range,
+    },
+    run: async ({ ctx, flags }) => {
+      const result = await apiGet<{ items: { id: string; label: string }[] }>(ctx, `/api/admin/core/ai-usage/facets?${params(flags)}`);
+      if (ctx.options.output === "jsonl") {
+        for (const item of result.items) ctx.jsonLine(item);
+        return;
+      }
+      printJsonOrTable(ctx, result, result.items, [{ key: "id" }, { key: "label" }]);
+    },
+  }),
+];

package/src/cli/admin/app-sign-in.ts

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import { cliText, command, confirmFlag, flag, printStructured, readCliInput } from "../index";
+import { apiGet } from "./shared";
+
+const path = "/api/admin/core/settings";
+const Configuration = z.object({ enabled: z.boolean(), origin: z.string(), adminPairing: z.boolean() }).strict();
+
+export const appSignInCommands = [
+  command("app-sign-in config get", {
+    summary: "Export app sign-in activation, trusted origin, and administrator-assisted pairing policy",
+    async run({ ctx }) {
+      const config = Configuration.parse(await apiGet(ctx, `${path}/app-sign-in`));
+      if (!printStructured(ctx, config)) ctx.print(JSON.stringify(config, null, 2));
+    },
+  }),
+  command("app-sign-in config set", {
+    summary: "Save app sign-in settings; incomplete setup keeps pairing and sign-in unavailable",
+    flags: {
+      config: flag.input({ required: true, description: "JSON with enabled, origin and adminPairing: --config, --config-file or --stdin" }),
+      yes: confirmFlag("Confirm app sign-in configuration and trusted website changes"),
+    },
+    async run({ ctx, flags }) {
+      if (!flags.yes)
+        throw new Error(cliText(ctx, { en: "App sign-in changes require --yes.", de: "Änderungen an der App-Anmeldung erfordern --yes." }));
+      const input = await readCliInput(flags.config, { required: true, label: "App sign-in configuration" });
+      const config = Configuration.parse(JSON.parse(input ?? ""));
+      await ctx.readJson(
+        await ctx.fetch(path, {
+          method: "PUT",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({
+            updates: {
+              "user.app_approval.enabled": config.enabled,
+              "user.app_approval.origin": config.origin,
+              "user.app_approval.admin_pairing": config.adminPairing,
+            },
+          }),
+        }),
+      );
+      if (!printStructured(ctx, { saved: true }))
+        ctx.print(
+          cliText(ctx, {
+            en: "App sign-in settings saved. Check the saved configuration status in Administration → Sign-in. This does not verify the PWA.",
+            de: "App-Anmeldung gespeichert. Prüfe den Konfigurationsstatus unter Administration → Anmeldung. Die PWA wird damit nicht geprüft.",
+          }),
+        );
+    },
+  }),
+];