@plenary/cli 0.3.0 → 0.5.0

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { readFileSync as readFileSync5 } from "fs";
+import { readFileSync as readFileSync6 } from "fs";
 import { Command, CommanderError as CommanderError2 } from "commander";
 
 // src/output.ts
@@ -158,25 +158,99 @@ function requireBaseUrl(ctx) {
   }
   return ctx.baseUrl;
 }
-function requireApiKey(ctx) {
-  if (!ctx.apiKey) {
-    throw usageError("no credential: pass --api-key or set PLENARY_API_KEY");
+
+// src/api/http.ts
+import { errorFromResponse } from "@plenary/client";
+
+// src/session.ts
+import { chmodSync, existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, renameSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import path2 from "path";
+function credentialsPath(io) {
+  const base = io.env.XDG_CONFIG_HOME || path2.join(io.env.HOME || homedir(), ".config");
+  return path2.join(base, "plenary", "credentials.json");
+}
+function readStore(io) {
+  const file = credentialsPath(io);
+  if (!existsSync2(file)) return {};
+  try {
+    const parsed = JSON.parse(readFileSync2(file, "utf8"));
+    return typeof parsed === "object" && parsed !== null ? parsed : {};
+  } catch {
+    return {};
   }
-  return ctx.apiKey;
+}
+function writeStore(io, store) {
+  const file = credentialsPath(io);
+  mkdirSync(path2.dirname(file), { recursive: true, mode: 448 });
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(store, null, 2) + "\n", { mode: 384 });
+  chmodSync(tmp, 384);
+  renameSync(tmp, file);
+}
+function loadSession(io, baseUrl) {
+  return readStore(io)[baseUrl];
+}
+function saveSession(io, baseUrl, session) {
+  const store = readStore(io);
+  store[baseUrl] = { ...session, updated_at: (/* @__PURE__ */ new Date()).toISOString() };
+  writeStore(io, store);
+}
+function clearSession(io, baseUrl) {
+  const store = readStore(io);
+  if (!(baseUrl in store)) return false;
+  delete store[baseUrl];
+  writeStore(io, store);
+  return true;
+}
+async function sessionAccessToken(ctx) {
+  if (ctx.sessionToken) return ctx.sessionToken;
+  const baseUrl = ctx.baseUrl;
+  if (!baseUrl) return void 0;
+  const stored = loadSession(ctx.io, baseUrl);
+  if (!stored) return void 0;
+  const response = await ctx.io.fetch(`${baseUrl}/api/v1/auth/refresh`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ refresh_token: stored.refresh_token })
+  });
+  const body = await response.json().catch(() => null);
+  if (!response.ok || !body || !("access_token" in body)) {
+    const code = body?.error?.code ?? `http_${response.status}`;
+    if (response.status === 401) {
+      clearSession(ctx.io, baseUrl);
+      throw usageError(`session for ${baseUrl} is no longer valid (${code}): run \`plenary login\``);
+    }
+    throw usageError(`could not refresh the session for ${baseUrl} (${code})`);
+  }
+  saveSession(ctx.io, baseUrl, { refresh_token: body.refresh_token, identifier: stored.identifier });
+  ctx.sessionToken = body.access_token;
+  return body.access_token;
 }
 
 // src/api/http.ts
-import { errorFromResponse } from "@plenary/client";
+async function credentialHeaders(ctx, mode) {
+  if (mode === "none") return {};
+  if (mode === "session") {
+    const token2 = await sessionAccessToken(ctx);
+    if (!token2) throw usageError("this command needs a user session: run `plenary login`");
+    return { Authorization: `Bearer ${token2}` };
+  }
+  if (ctx.apiKey) return { "X-API-KEY": ctx.apiKey };
+  const token = await sessionAccessToken(ctx);
+  if (token) return { Authorization: `Bearer ${token}` };
+  if (mode === "required") {
+    throw usageError("no credential: pass --api-key, set PLENARY_API_KEY, or run `plenary login`");
+  }
+  return {};
+}
 function apiPath(p) {
   return p.startsWith("/") ? p : `/api/v1/${p}`;
 }
-async function request(ctx, method, path6, opts = {}) {
+async function request(ctx, method, path7, opts = {}) {
   const base = requireBaseUrl(ctx);
-  const auth = opts.auth ?? "required";
-  const headers = { ...opts.headers };
-  if (auth === "required") headers["X-API-KEY"] = requireApiKey(ctx);
-  else if (auth === "optional" && ctx.apiKey) headers["X-API-KEY"] = ctx.apiKey;
-  const url = new URL(base + apiPath(path6));
+  const headers = { ...opts.headers, ...await credentialHeaders(ctx, opts.auth ?? "required") };
+  const url = new URL(base + apiPath(path7));
   for (const [k, v] of Object.entries(opts.query ?? {})) {
     if (v !== void 0) url.searchParams.set(k, v);
   }
@@ -214,7 +288,7 @@ async function parseBody(response) {
 }
 
 // src/input.ts
-import { readFileSync as readFileSync2 } from "fs";
+import { readFileSync as readFileSync3 } from "fs";
 import { createInterface } from "readline/promises";
 function parsePairs(pairs, sep, what) {
   const out = {};
@@ -229,7 +303,7 @@ async function readText(data, stdin) {
   if (data === "-") return readStream(stdin);
   if (data.startsWith("@")) {
     try {
-      return readFileSync2(data.slice(1), "utf8");
+      return readFileSync3(data.slice(1), "utf8");
     } catch (err) {
       throw usageError(`cannot read ${data.slice(1)}: ${err.message}`);
     }
@@ -267,15 +341,194 @@ async function confirm(io, question, yes) {
     rl.close();
   }
 }
+async function readLine(io, prompt) {
+  const rl = createInterface({ input: io.stdin, output: io.isTTY ? io.stderr : void 0, terminal: io.isTTY });
+  try {
+    if (!io.isTTY) {
+      const it = rl[Symbol.asyncIterator]();
+      const { value } = await it.next();
+      return (value ?? "").trim();
+    }
+    return (await rl.question(prompt)).trim();
+  } finally {
+    rl.close();
+  }
+}
+async function readSecret(io, prompt) {
+  const stdin = io.stdin;
+  if (!io.isTTY || typeof stdin.setRawMode !== "function") return readLine(io, prompt);
+  io.stderr.write(prompt);
+  stdin.setRawMode(true);
+  stdin.resume();
+  try {
+    return await new Promise((resolve, reject) => {
+      let value = "";
+      const onData = (chunk) => {
+        for (const ch of String(chunk)) {
+          const code = ch.charCodeAt(0);
+          if (code === 3) {
+            cleanup();
+            reject(usageError("aborted"));
+            return;
+          }
+          if (code === 13 || code === 10) {
+            cleanup();
+            io.stderr.write("\n");
+            resolve(value);
+            return;
+          }
+          if (code === 127 || code === 8) value = value.slice(0, -1);
+          else value += ch;
+        }
+      };
+      const cleanup = () => {
+        stdin.off("data", onData);
+        stdin.setRawMode?.(false);
+        stdin.pause();
+      };
+      stdin.on("data", onData);
+    });
+  } finally {
+    stdin.setRawMode?.(false);
+  }
+}
+
+// src/commands/admin.ts
+function collect(value, previous) {
+  return [...previous, value];
+}
+function parseGrant(spec) {
+  const [key, ...filters] = spec.split(",").map((s) => s.trim());
+  if (!key) throw usageError(`invalid --grant "${spec}"`);
+  const grant = { key };
+  for (const f of filters) {
+    const [name, value] = f.split("=");
+    if (name === "site" && value) grant.site_key = value;
+    else if (name === "model" && value) grant.content_model_id = value;
+    else throw usageError(`invalid --grant "${spec}": expected key[,site=<key>][,model=<uuid>]`);
+  }
+  return grant;
+}
+function registerAdmin(program, io) {
+  program.command("sites").description("Sites").command("list").description("List sites").action(async (_flags, cmd) => {
+    const ctx = resolveContext(cmd.optsWithGlobals(), io);
+    const res = await request(ctx, "GET", "sites");
+    if (ctx.json) {
+      io.stdout.write(toJson(res.data) + "\n");
+      return;
+    }
+    const rows = res.data.map((s) => [
+      s.key,
+      s.name,
+      s.default_locale,
+      s.locales.join(","),
+      s.timezone,
+      s.is_active ? "" : "inactive"
+    ]);
+    io.stdout.write(formatTable(rows, ["KEY", "NAME", "DEFAULT", "LOCALES", "TIMEZONE", ""]) + "\n");
+  });
+  const roles = program.command("roles").description("Roles (needs a user session)");
+  roles.command("list").description("List roles").action(async (_flags, cmd) => {
+    const ctx = resolveContext(cmd.optsWithGlobals(), io);
+    const res = await request(ctx, "GET", "roles", { auth: "session" });
+    if (ctx.json) {
+      io.stdout.write(toJson(res.data) + "\n");
+      return;
+    }
+    const rows = res.data.map((r) => [
+      r.key,
+      r.name,
+      String(r.grant_count),
+      String(r.assigned_user_count),
+      r.is_system ? "system" : ""
+    ]);
+    io.stdout.write(formatTable(rows, ["KEY", "NAME", "GRANTS", "USERS", ""]) + "\n");
+  });
+  roles.command("get").description("Show a role and its grants").argument("<key>").action(async (key, _flags, cmd) => {
+    const ctx = resolveContext(cmd.optsWithGlobals(), io);
+    const res = await request(ctx, "GET", `roles/${encodeURIComponent(key)}`, { auth: "session" });
+    if (ctx.json) {
+      io.stdout.write(toJson(res.data) + "\n");
+      return;
+    }
+    const r = res.data;
+    const head = [
+      ["Key", r.key],
+      ["Name", r.name],
+      ["System", r.is_system ? "yes" : "no"]
+    ];
+    if (r.description) head.push(["Description", r.description]);
+    const grants = r.grants.map((g) => [g.key, g.site_key ?? "", g.content_model_id ?? ""]);
+    io.stdout.write(formatTable(head) + "\n\n" + formatTable(grants, ["GRANT", "SITE", "MODEL"]) + "\n");
+  });
+  const keys = program.command("api-keys").description("API keys (needs a user session)");
+  keys.command("list").description("List API keys").action(async (_flags, cmd) => {
+    const ctx = resolveContext(cmd.optsWithGlobals(), io);
+    const res = await request(ctx, "GET", "api-keys", { auth: "session" });
+    if (ctx.json) {
+      io.stdout.write(toJson(res.data) + "\n");
+      return;
+    }
+    const rows = res.data.map((k) => [
+      k.id,
+      k.name,
+      k.key_type,
+      k.revoked_at ? "revoked" : k.is_active ? "active" : "inactive",
+      k.last_used_at ?? "never",
+      k.expires_at ?? ""
+    ]);
+    io.stdout.write(formatTable(rows, ["ID", "NAME", "TYPE", "STATE", "LAST USED", "EXPIRES"]) + "\n");
+  });
+  keys.command("get").description("Show one API key (never its secret)").argument("<id>").action(async (id, _flags, cmd) => {
+    const ctx = resolveContext(cmd.optsWithGlobals(), io);
+    const res = await request(ctx, "GET", `api-keys/${encodeURIComponent(id)}`, { auth: "session" });
+    io.stdout.write(toJson(res.data) + "\n");
+  });
+  keys.command("create").description("Create an API key; the secret is printed once, alone on stdout").requiredOption("-n, --name <name>").option("-t, --type <private|public>", "key type", "private").option("--description <text>").option("-g, --grant <spec>", "private keys: key[,site=<key>][,model=<uuid>] (repeatable)", collect, []).option("--site <key>", "public keys: a site it may read (repeatable)", collect, []).option("--expires <iso>", "expiry timestamp").option("--origin <origin>", "an allowed browser origin (repeatable)", collect, []).option("--rate-limit <n>", "requests per minute, 0 = unlimited", "0").option("--include-drafts", "public keys: read drafts too").action(
+    async (flags, cmd) => {
+      const ctx = resolveContext(cmd.optsWithGlobals(), io);
+      if (flags.type !== "private" && flags.type !== "public") throw usageError("--type must be private or public");
+      const body = {
+        name: flags.name,
+        description: flags.description ?? null,
+        key_type: flags.type,
+        is_active: true,
+        expires_at: flags.expires ?? null,
+        grants: flags.grant.map(parseGrant),
+        sites: flags.site,
+        allowed_origins: flags.origin,
+        rate_limit_per_minute: Number(flags.rateLimit),
+        include_drafts: Boolean(flags.includeDrafts)
+      };
+      const res = await request(ctx, "POST", "api-keys", { auth: "session", body });
+      if (ctx.json) {
+        io.stdout.write(toJson(res.data) + "\n");
+        return;
+      }
+      io.stderr.write(
+        `created ${flags.type} key "${flags.name}" (${res.data.id}); the secret follows and is not shown again
+`
+      );
+      io.stdout.write(res.data.key + "\n");
+    }
+  );
+  keys.command("delete").description("Delete an API key").argument("<id>").option("-y, --yes", "do not ask").action(async (id, flags, cmd) => {
+    const ctx = resolveContext(cmd.optsWithGlobals(), io);
+    await confirm(io, `Delete API key ${id}?`, Boolean(flags.yes));
+    await request(ctx, "DELETE", `api-keys/${encodeURIComponent(id)}`, { auth: "session" });
+    io.stdout.write(`deleted ${id}
+`);
+  });
+}
 
 // src/commands/api.ts
 import { errorFromResponse as errorFromResponse2 } from "@plenary/client";
 var METHODS = /* @__PURE__ */ new Set(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"]);
-function collect(value, previous) {
+function collect2(value, previous) {
   return [...previous, value];
 }
 function registerApi(program, io) {
-  program.command("api").description("Call any API endpoint and print the response body").argument("<method>", "GET, POST, PUT, PATCH, DELETE, or HEAD").argument("<path>", "a path such as models or /api/v1/models").option("-d, --data <json>", "request body: inline JSON, @file, or - for stdin").option("-q, --query <key=value>", "query parameter (repeatable)", collect, []).option("-H, --header <key:value>", "request header (repeatable)", collect, []).option("-i, --include", "print the status line and response headers to stderr").addHelpText(
+  program.command("api").description("Call any API endpoint and print the response body").argument("<method>", "GET, POST, PUT, PATCH, DELETE, or HEAD").argument("<path>", "a path such as models or /api/v1/models").option("-d, --data <json>", "request body: inline JSON, @file, or - for stdin").option("-q, --query <key=value>", "query parameter (repeatable)", collect2, []).option("-H, --header <key:value>", "request header (repeatable)", collect2, []).option("-i, --include", "print the status line and response headers to stderr").addHelpText(
     "after",
     `
 Examples:
@@ -284,12 +537,12 @@ Examples:
   plenary api POST content/post -q site_key=main -d '{"fields":{"title":"Hello"}}'
   plenary api PUT models/<uuid> -d @model.json`
   ).action(
-    async (methodArg, path6, opts, cmd) => {
+    async (methodArg, path7, opts, cmd) => {
       const ctx = resolveContext(cmd.optsWithGlobals(), io);
       const method = methodArg.toUpperCase();
       if (!METHODS.has(method)) throw usageError(`unsupported method "${methodArg}"`);
       const body = opts.data !== void 0 ? await readData(opts.data, io.stdin) : void 0;
-      const res = await request(ctx, method, path6, {
+      const res = await request(ctx, method, path7, {
         query: parsePairs(opts.query, "=", "query parameter"),
         headers: parsePairs(opts.header, ":", "header"),
         body,
@@ -314,6 +567,130 @@ Examples:
   );
 }
 
+// src/commands/auth.ts
+async function login(ctx, identifier, password, otpMethod) {
+  const io = ctx.io;
+  const first = await request(ctx, "POST", "auth/login", {
+    auth: "none",
+    body: { identifier, password }
+  });
+  const res = first.data;
+  if (res.status === "success") return res;
+  const challengeId = res.challenge_id;
+  const methods = Object.keys(res.otp_methods);
+  if (res.status === "otp_required") {
+    let method = otpMethod ?? (methods.length === 1 ? methods[0] : void 0);
+    if (!method) {
+      if (!io.isTTY) throw usageError(`2FA needs a delivery method: pass --otp-method ${methods.join("|")}`);
+      const shown = methods.map((m) => `${m} (${res.otp_methods[m]})`).join(", ");
+      method = await readLine(io, `Send the code by ${shown}? [${methods[0]}] `);
+      if (method === "") method = methods[0];
+    }
+    if (!methods.includes(method)) throw usageError(`--otp-method must be one of ${methods.join(", ")}`);
+    await request(ctx, "POST", "auth/login/otp/send", {
+      auth: "none",
+      body: { challenge_id: challengeId, otp_method: method }
+    });
+    io.stderr.write(`code sent by ${method}
+`);
+  } else {
+    io.stderr.write(`code sent to ${Object.values(res.otp_methods).join(", ")}
+`);
+  }
+  if (!io.isTTY) throw usageError("2FA needs a terminal to enter the code");
+  const code = await readLine(io, "Code: ");
+  const verified = await request(ctx, "POST", "auth/login/otp/verify", {
+    auth: "none",
+    body: { challenge_id: challengeId, otp_code: code }
+  });
+  return verified.data;
+}
+function registerAuth(program, io) {
+  program.command("login").description("Sign in as a user and keep the session for admin commands").option("-u, --identifier <email-or-username>", "or PLENARY_USERNAME").option("--otp-method <email|sms>", "how to receive a 2FA code when more than one way is offered").addHelpText(
+    "after",
+    `
+The password is prompted for (never a flag); PLENARY_PASSWORD supplies it
+without a terminal. Only the refresh token is stored, in
+$XDG_CONFIG_HOME/plenary/credentials.json, keyed by instance.`
+  ).action(async (flags, cmd) => {
+    const ctx = resolveContext(cmd.optsWithGlobals(), io);
+    const baseUrl = requireBaseUrl(ctx);
+    let identifier = flags.identifier ?? io.env.PLENARY_USERNAME;
+    if (!identifier) {
+      if (!io.isTTY) throw usageError("no identifier: pass --identifier or set PLENARY_USERNAME");
+      identifier = await readLine(io, "Email or username: ");
+    }
+    let password = io.env.PLENARY_PASSWORD;
+    if (!password) {
+      if (!io.isTTY) throw usageError("no password: set PLENARY_PASSWORD or run on a terminal");
+      password = await readSecret(io, "Password: ");
+    }
+    const tokens = await login(ctx, identifier, password, flags.otpMethod);
+    saveSession(io, baseUrl, { refresh_token: tokens.refresh_token, identifier });
+    ctx.sessionToken = tokens.access_token;
+    const me = await request(ctx, "GET", "auth/me", { auth: "session" });
+    if (ctx.json) {
+      io.stdout.write(
+        toJson({ base_url: baseUrl, identifier, role: me.data.role, credentials: credentialsPath(io) }) + "\n"
+      );
+      return;
+    }
+    io.stdout.write(`logged in to ${baseUrl} as ${identifier} (${me.data.role_name ?? me.data.role})
+`);
+  });
+  program.command("logout").description("Revoke the stored session for this instance").action(async (_flags, cmd) => {
+    const ctx = resolveContext(cmd.optsWithGlobals(), io);
+    const baseUrl = requireBaseUrl(ctx);
+    const stored = loadSession(io, baseUrl);
+    if (!stored) {
+      io.stdout.write(`no session for ${baseUrl}
+`);
+      return;
+    }
+    try {
+      await request(ctx, "POST", "auth/logout", { auth: "none", body: { refresh_token: stored.refresh_token } });
+    } finally {
+      clearSession(io, baseUrl);
+    }
+    io.stdout.write(`logged out of ${baseUrl}
+`);
+  });
+  program.command("whoami").description("Show the credentials this run would use").action(async (_flags, cmd) => {
+    const ctx = resolveContext(cmd.optsWithGlobals(), io);
+    const baseUrl = requireBaseUrl(ctx);
+    const stored = loadSession(io, baseUrl);
+    const out = { base_url: baseUrl, api_key: null, session: null };
+    const lines = [];
+    if (ctx.apiKey) {
+      const me = await request(ctx, "GET", "auth/me", {
+        auth: "none",
+        headers: { "X-API-KEY": ctx.apiKey },
+        allowError: true
+      });
+      out.api_key = me.ok ? me.data : { error: me.data?.error ?? me.status };
+      if (me.ok && me.data.key_type) {
+        lines.push(
+          `API key   ${me.data.key_type} "${me.data.name}" (${me.data.grants?.length ?? 0} grants), used for content commands`
+        );
+      } else if (me.status === 403) {
+        lines.push("API key   accepted (this server cannot describe keys), used for content commands");
+      } else {
+        lines.push(`API key   rejected (HTTP ${me.status})`);
+      }
+    }
+    if (stored) {
+      const headers = await credentialHeaders(ctx, "session");
+      const me = await request(ctx, "GET", "auth/me", { auth: "none", headers });
+      out.session = { identifier: stored.identifier ?? null, role: me.data.role, role_name: me.data.role_name ?? null };
+      lines.push(
+        `Session   ${stored.identifier ?? "user"} (${me.data.role_name ?? me.data.role}), used for admin commands${ctx.apiKey ? "" : " and content"}`
+      );
+    }
+    if (lines.length === 0) lines.push("no credentials: set PLENARY_API_KEY or run `plenary login`");
+    io.stdout.write((ctx.json ? toJson(out) : lines.join("\n")) + "\n");
+  });
+}
+
 // src/commands/catalog.ts
 function registerCatalog(program, io, name) {
   const group = program.command(name).description(name === "models" ? "Content models and objects" : "Forms");
@@ -386,13 +763,16 @@ async function resolveLocale(ctx, siteKey) {
 }
 async function contentClient(ctx) {
   const siteKey = requireSiteKey(ctx);
-  return createClient({
-    baseUrl: requireBaseUrl(ctx),
-    siteKey,
-    apiKey: requireApiKey(ctx),
-    locale: await resolveLocale(ctx, siteKey),
-    fetch: ctx.io.fetch
-  });
+  const baseUrl = requireBaseUrl(ctx);
+  const auth = await credentialHeaders(ctx, "required");
+  const apiKey = auth["X-API-KEY"] ?? "";
+  const fetch = apiKey ? ctx.io.fetch : (input, init = {}) => {
+    const headers = new Headers(init.headers);
+    headers.delete("X-API-KEY");
+    for (const [k, v] of Object.entries(auth)) headers.set(k, v);
+    return ctx.io.fetch(input, { ...init, headers });
+  };
+  return createClient({ baseUrl, siteKey, apiKey, locale: await resolveLocale(ctx, siteKey), fetch });
 }
 
 // src/entries/query.ts
@@ -468,11 +848,11 @@ async function toListOptions(flags, stdin) {
 }
 
 // src/commands/entries.ts
-function collect2(value, previous) {
+function collect3(value, previous) {
   return [...previous, value];
 }
 function withListFlags(cmd) {
-  return cmd.option("-w, --where <field=value>", "filter: field=value or field=$op:value (repeatable)", collect2, []).option("--filters <json>", "a filter tree (inline JSON, @file, or -); excludes --where").option("-s, --sort <field[:dir]>", "sort field, asc unless :desc (repeatable, in precedence order)", collect2, []).option("--limit <n>", "page size").option("--offset <n>", "rows to skip").option("--include <fields>", "comma-separated data fields to return").option("--exclude <fields>", "comma-separated data fields to omit").option("--hydrate <field[=subfields]>", "hydrate a reference field (repeatable)", collect2, []).option("--count", "ask for the total and show it");
+  return cmd.option("-w, --where <field=value>", "filter: field=value or field=$op:value (repeatable)", collect3, []).option("--filters <json>", "a filter tree (inline JSON, @file, or -); excludes --where").option("-s, --sort <field[:dir]>", "sort field, asc unless :desc (repeatable, in precedence order)", collect3, []).option("--limit <n>", "page size").option("--offset <n>", "rows to skip").option("--include <fields>", "comma-separated data fields to return").option("--exclude <fields>", "comma-separated data fields to omit").option("--hydrate <field[=subfields]>", "hydrate a reference field (repeatable)", collect3, []).option("--count", "ask for the total and show it");
 }
 function withWriteFlags(cmd) {
   return cmd.option("-d, --data <json>", "the field values as a JSON object (inline, @file, or -)").option("--slug <slug>").option("--folder <id>", "content folder id").option("--note <text>", "revision note (required by models with Require Change Notes)").option("--publish-at <iso>", "schedule a publish").option("--unpublish-at <iso>", "schedule an unpublish");
@@ -511,7 +891,7 @@ function registerEntries(program, io) {
 `);
     }
   );
-  entries.command("get").description("Print one entry as JSON; omit the slug for a singleton").argument("<model>").argument("[slug-or-id]").option("--include <fields>").option("--exclude <fields>").option("--hydrate <field[=subfields]>", "hydrate a reference field (repeatable)", collect2, []).action(async (model, slug, flags, cmd) => {
+  entries.command("get").description("Print one entry as JSON; omit the slug for a singleton").argument("<model>").argument("[slug-or-id]").option("--include <fields>").option("--exclude <fields>").option("--hydrate <field[=subfields]>", "hydrate a reference field (repeatable)", collect3, []).action(async (model, slug, flags, cmd) => {
     const ctx = resolveContext(cmd.optsWithGlobals(), io);
     const client = await contentClient(ctx);
     const opts = await toReadOptions(flags);
@@ -639,7 +1019,7 @@ function report(ctx, entry, verb) {
 }
 
 // src/commands/formentries.ts
-function collect3(value, previous) {
+function collect4(value, previous) {
   return [...previous, value];
 }
 function toQuery(ctx, opts) {
@@ -664,7 +1044,7 @@ function toQuery(ctx, opts) {
 var PAGE2 = 100;
 function registerFormEntries(forms, io) {
   const entries = forms.command("entries").description("Form entries (what visitors submitted)");
-  const listFlags = (cmd) => cmd.option("-w, --where <field=value>", "filter: field=value or field=$op:value (repeatable)", collect3, []).option("--filters <json>", "a filter tree (inline JSON, @file, or -)").option("-s, --sort <field[:dir]>", "sort field, asc unless :desc (repeatable)", collect3, []).option("--limit <n>").option("--offset <n>").option("--count", "ask for the total and show it");
+  const listFlags = (cmd) => cmd.option("-w, --where <field=value>", "filter: field=value or field=$op:value (repeatable)", collect4, []).option("--filters <json>", "a filter tree (inline JSON, @file, or -)").option("-s, --sort <field[:dir]>", "sort field, asc unless :desc (repeatable)", collect4, []).option("--limit <n>").option("--offset <n>").option("--count", "ask for the total and show it");
   listFlags(entries.command("list").description("List a form's entries").argument("<form>")).action(
     async (form, flags, cmd) => {
       const ctx = resolveContext(cmd.optsWithGlobals(), io);
@@ -705,8 +1085,8 @@ function summary(data) {
 }
 
 // src/commands/media.ts
-import { readFileSync as readFileSync3 } from "fs";
-import path2 from "path";
+import { readFileSync as readFileSync4 } from "fs";
+import path3 from "path";
 function size(bytes) {
   if (bytes < 1024) return `${bytes} B`;
   if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
@@ -721,12 +1101,12 @@ function registerMedia(program, io) {
     for (const file of files) {
       let bytes;
       try {
-        bytes = readFileSync3(file);
+        bytes = readFileSync4(file);
       } catch (err) {
         throw usageError(`cannot read ${file}: ${err.message}`);
       }
       const form = new FormData();
-      form.append("upload_file", new Blob([new Uint8Array(bytes)]), path2.basename(file));
+      form.append("upload_file", new Blob([new Uint8Array(bytes)]), path3.basename(file));
       if (flags.folder) form.append("folder_id", flags.folder);
       if (flags.private) form.append("visibility", "private");
       try {
@@ -765,27 +1145,40 @@ function registerMedia(program, io) {
 }
 
 // src/commands/metadata.ts
-import path4 from "path";
+import path5 from "path";
 
 // src/metadata/dir.ts
-import { existsSync as existsSync2, mkdirSync, readdirSync, readFileSync as readFileSync4, writeFileSync } from "fs";
-import path3 from "path";
-var MANAGED_DIRS = ["models", "forms"];
+import { existsSync as existsSync3, mkdirSync as mkdirSync2, readdirSync, readFileSync as readFileSync5, writeFileSync as writeFileSync2 } from "fs";
+import path4 from "path";
+var MANAGED_DIRS = ["models", "forms", "roles", "sites"];
+function parseKinds(spec) {
+  if (!spec || spec === "all") return [...MANAGED_DIRS];
+  const out = [];
+  for (const raw of spec.split(",")) {
+    const k = raw.trim();
+    if (!MANAGED_DIRS.includes(k)) throw new Error(`unknown kind "${k}" (want ${MANAGED_DIRS.join(", ")} or all)`);
+    if (!out.includes(k)) out.push(k);
+  }
+  return out;
+}
+function filterKinds(files, kinds) {
+  return files.filter((f) => kinds.includes(f.path.split("/")[0]));
+}
 function readTree(root) {
   const out = [];
   for (const rel of managedFiles(root)) {
-    out.push({ path: rel, content: readFileSync4(path3.join(root, rel), "utf8") });
+    out.push({ path: rel, content: readFileSync5(path4.join(root, rel), "utf8") });
   }
   return out;
 }
-function writeTree(root, files) {
-  const before = new Set(managedFiles(root));
+function writeTree(root, files, kinds = [...MANAGED_DIRS]) {
+  const before = new Set(managedFiles(root).filter((p) => kinds.includes(p.split("/")[0])));
   const written = [];
   for (const f of [...files].sort((a, b) => a.path.localeCompare(b.path))) {
     if (!isTreePath(f.path)) continue;
-    const abs = path3.join(root, f.path);
-    mkdirSync(path3.dirname(abs), { recursive: true });
-    writeFileSync(abs, f.content);
+    const abs = path4.join(root, f.path);
+    mkdirSync2(path4.dirname(abs), { recursive: true });
+    writeFileSync2(abs, f.content);
     written.push(f.path);
     before.delete(f.path);
   }
@@ -798,8 +1191,8 @@ function isTreePath(p) {
 function managedFiles(root) {
   const out = [];
   for (const dir of MANAGED_DIRS) {
-    const abs = path3.join(root, dir);
-    if (!existsSync2(abs)) continue;
+    const abs = path4.join(root, dir);
+    if (!existsSync3(abs)) continue;
     for (const name of readdirSync(abs).sort()) {
       if (name.endsWith(".yaml")) out.push(`${dir}/${name}`);
     }
@@ -810,20 +1203,24 @@ function managedFiles(root) {
 // src/metadata/plan.ts
 function formatPlan(result, verbose = false) {
   const lines = [];
-  let creates = 0;
-  let updates = 0;
-  let noops = 0;
-  for (const c of result.changes) {
-    if (c.action === "create") creates++;
-    else if (c.action === "update") updates++;
-    else noops++;
+  const n = { create: 0, update: 0, delete: 0, skip: 0, noop: 0 };
+  const ordered = [...result.changes].sort((a, b) => Number(b.action === "delete") - Number(a.action === "delete"));
+  for (const c of ordered) {
+    n[c.action]++;
     if (c.action === "noop" && !verbose) continue;
-    const label = c.action === "noop" ? "unchanged" : c.action;
-    lines.push(`${label.padEnd(9)} ${c.kind.padEnd(10)} ${c.key}${detail(c)}`);
+    const label = c.action === "noop" ? "unchanged" : c.action === "skip" ? "skipped" : c.action;
+    const note = c.action === "skip" ? "  (system-owned)" : detail(c);
+    lines.push(`${label.padEnd(9)} ${c.kind.padEnd(10)} ${c.key}${note}`);
+  }
+  const parts = [`${n.create} to create`, `${n.update} to update`];
+  if (n.delete) parts.push(`${n.delete} to delete`);
+  if (n.skip) parts.push(`${n.skip} skipped`);
+  parts.push(`${n.noop} unchanged`);
+  if (n.create + n.update + n.delete === 0) {
+    lines.push(`No changes: ${n.noop} unchanged${n.skip ? `, ${n.skip} skipped` : ""}.`);
+  } else {
+    lines.push(`${result.applied ? "Applied" : "Plan"}: ${parts.join(", ")}.`);
   }
-  const counts = `${creates} to create, ${updates} to update, ${noops} unchanged`;
-  if (creates + updates === 0) lines.push(`No changes: ${noops} unchanged.`);
-  else lines.push(result.applied ? `Applied: ${counts}.` : `Plan: ${counts}.`);
   return lines.join("\n");
 }
 function detail(c) {
@@ -839,40 +1236,68 @@ function detail(c) {
 }
 
 // src/commands/metadata.ts
+function kindsOf(opts) {
+  try {
+    return parseKinds(opts.only);
+  } catch (err) {
+    throw usageError(`--only: ${err.message}`);
+  }
+}
 function treeRoot(ctx, opts) {
-  return opts.dir ? path4.resolve(ctx.io.cwd, opts.dir) : path4.resolve(ctx.projectRoot, ctx.metadataDir);
+  return opts.dir ? path5.resolve(ctx.io.cwd, opts.dir) : path5.resolve(ctx.projectRoot, ctx.metadataDir);
 }
-function readTreeOrFail(root) {
-  const files = readTree(root);
-  if (files.length === 0) throw usageError(`no YAML files under ${root}/models or ${root}/forms`);
+function readTreeOrFail(root, kinds) {
+  const files = filterKinds(readTree(root), kinds);
+  if (files.length === 0) throw usageError(`no YAML files under ${root}/{${kinds.join(",")}}`);
   return files;
 }
-async function runImport(ctx, root, apply, verbose) {
-  const files = readTreeOrFail(root);
-  const res = await request(ctx, "POST", "metadata/models/import", { body: { files, apply } });
+async function runImport(ctx, root, opts, apply) {
+  const kinds = kindsOf(opts);
+  const files = readTreeOrFail(root, kinds);
+  const prune = Boolean(opts.prune);
+  const body = { files, apply: false, prune };
+  let res = await request(ctx, "POST", "metadata/import", { body });
+  const deletes = res.data.changes.filter((c) => c.action === "delete");
+  if (apply) {
+    if (deletes.length > 0) {
+      if (!ctx.json) ctx.io.stdout.write(formatPlan(res.data, Boolean(opts.verbose)) + "\n");
+      await confirm(ctx.io, `Delete ${deletes.length} ${deletes.length === 1 ? "entity" : "entities"} from the instance?`, Boolean(opts.yes));
+    }
+    res = await request(ctx, "POST", "metadata/import", { body: { ...body, apply: true } });
+  }
   if (ctx.json) ctx.io.stdout.write(toJson(res.data) + "\n");
-  else ctx.io.stdout.write(formatPlan(res.data, verbose) + "\n");
+  else ctx.io.stdout.write(formatPlan(res.data, Boolean(opts.verbose)) + "\n");
 }
+var onlyOption = ["--only <kinds>", "comma list of models, forms, roles, sites (default: all)"];
 function registerMetadata(program, io) {
   const metadata = program.command("metadata").description("Keep a directory of model and form YAML in step with the instance").addHelpText(
     "after",
     `
-The tree is models/<key>.yaml and forms/<key>.yaml under the metadata
-directory ("metadataDir" in plenary.json, default ./plenary). See
-docs/CONTENT_MODELS.md, "YAML import and export".`
+The tree is models/, forms/, roles/ and sites/ under the metadata directory
+("metadataDir" in plenary.json, default ./plenary), one <key>.yaml per
+entity. Models and forms need an API key or a session; roles and sites need
+a user session (plenary login). See docs/CLI.md.`
   );
-  metadata.command("pull").description("Write every model and form the key may read into the directory").option("--dir <path>", "metadata directory (default: the configured one)").action(async (opts, cmd) => {
+  metadata.command("pull").description("Write every model, form, role and site the credential may read into the directory").option("--dir <path>", "metadata directory (default: the configured one)").option(...onlyOption).action(async (opts, cmd) => {
     const ctx = resolveContext(cmd.optsWithGlobals(), io);
     const root = treeRoot(ctx, opts);
-    const res = await request(ctx, "GET", "metadata/models");
-    const result = writeTree(root, res.data.files);
+    const kinds = kindsOf(opts);
+    const res = await request(ctx, "GET", "metadata", {
+      query: { only: kinds.join(",") }
+    });
+    const result = writeTree(root, res.data.files, kinds);
+    const omitted = res.data.omitted ?? [];
     if (ctx.json) {
-      io.stdout.write(toJson({ dir: root, ...result }) + "\n");
+      io.stdout.write(toJson({ dir: root, ...result, omitted }) + "\n");
       return;
     }
     io.stdout.write(`wrote ${result.written.length} file${result.written.length === 1 ? "" : "s"} to ${root}
 `);
-    if (result.written.length === 0) {
+    if (omitted.length) {
+      io.stderr.write(`not included, the credential may not read them: ${omitted.join(", ")}
+`);
+    }
+    if (result.written.length === 0 && omitted.length === 0) {
       io.stderr.write("the server sent no models: the key may lack content:models:read (a public key never has it)\n");
     }
     if (result.stale.length) {
@@ -881,19 +1306,26 @@ ${result.stale.map((p) => `  ${p}`).join("\n")}
 `);
     }
   });
-  metadata.command("diff").description("Preview what push would change, without writing anything").option("--dir <path>", "metadata directory (default: the configured one)").option("--verbose", "list unchanged models too").action(async (opts, cmd) => {
+  metadata.command("diff").description("Preview what push would change, without writing anything").option("--dir <path>", "metadata directory (default: the configured one)").option(...onlyOption).option("--prune", "include what push --prune would delete").option("--verbose", "list unchanged entities too").action(async (opts, cmd) => {
     const ctx = resolveContext(cmd.optsWithGlobals(), io);
-    await runImport(ctx, treeRoot(ctx, opts), false, Boolean(opts.verbose));
+    await runImport(ctx, treeRoot(ctx, opts), opts, false);
   });
-  metadata.command("push").description("Apply the directory to the instance (creates and updates; never deletes)").option("--dir <path>", "metadata directory (default: the configured one)").option("--dry-run", "same as diff").option("--verbose", "list unchanged models too").action(async (opts, cmd) => {
+  metadata.command("push").description("Apply the directory to the instance (creates and updates; deletes only with --prune)").option("--dir <path>", "metadata directory (default: the configured one)").option(...onlyOption).option("--prune", "also delete entities absent from the directory, within the kinds it holds").option("-y, --yes", "do not ask before pruning").option("--dry-run", "same as diff").option("--verbose", "list unchanged entities too").addHelpText(
+    "after",
+    `
+--prune deletes only within the kinds present in the directory: a tree with
+no roles/ cannot delete a role. System-owned roles are never touched and are
+reported as skipped. The plan is shown and confirmed before anything is
+deleted; -y skips the question, and a run with no terminal needs it.`
+  ).action(async (opts, cmd) => {
     const ctx = resolveContext(cmd.optsWithGlobals(), io);
-    await runImport(ctx, treeRoot(ctx, opts), !opts.dryRun, Boolean(opts.verbose));
+    await runImport(ctx, treeRoot(ctx, opts), opts, !opts.dryRun);
   });
 }
 
 // src/commands/init.ts
-import { existsSync as existsSync3, writeFileSync as writeFileSync2 } from "fs";
-import path5 from "path";
+import { existsSync as existsSync4, writeFileSync as writeFileSync3 } from "fs";
+import path6 from "path";
 import { createInterface as createInterface2 } from "readline/promises";
 function registerInit(program, io) {
   program.command("init").description(`Write a ${CONFIG_FILE} for this project (never a credential)`).option("--dir <path>", "metadata directory, relative to the config file", DEFAULT_METADATA_DIR).option("-f, --force", `overwrite an existing ${CONFIG_FILE}`).addHelpText(
@@ -902,12 +1334,12 @@ function registerInit(program, io) {
 The base URL, site and locale come from --base-url, --site and --locale (or
 their PLENARY_* variables); anything missing is prompted for on a terminal.`
   ).action(async (opts, cmd) => {
-    const target = path5.join(io.cwd, CONFIG_FILE);
-    if (existsSync3(target) && !opts.force) {
+    const target = path6.join(io.cwd, CONFIG_FILE);
+    if (existsSync4(target) && !opts.force) {
       throw usageError(`${target} already exists (pass --force to overwrite)`);
     }
     const globals = cmd.optsWithGlobals();
-    const ctx = resolveContext({ ...globals, config: void 0 }, { ...io, cwd: path5.parse(io.cwd).root });
+    const ctx = resolveContext({ ...globals, config: void 0 }, { ...io, cwd: path6.parse(io.cwd).root });
     const baseUrl = globals.baseUrl ?? ctx.baseUrl ?? await ask(io, "Base URL (https://cms.example.com)");
     if (!baseUrl) throw usageError("a base URL is required: pass --base-url or set PLENARY_BASE_URL");
     const siteKey = globals.site ?? ctx.siteKey ?? await ask(io, "Site key", "default");
@@ -916,7 +1348,7 @@ their PLENARY_* variables); anything missing is prompted for on a terminal.`
     if (siteKey) config.siteKey = siteKey;
     if (locale) config.locale = locale;
     if (opts.dir !== DEFAULT_METADATA_DIR) config.metadataDir = opts.dir;
-    writeFileSync2(target, JSON.stringify(config, null, 2) + "\n");
+    writeFileSync3(target, JSON.stringify(config, null, 2) + "\n");
     io.stdout.write(`wrote ${target}
 `);
   });
@@ -941,9 +1373,10 @@ function registerStatus(program, io) {
     let me;
     let credentialError;
     let undescribed = false;
-    if (ctx.apiKey) {
+    const headers = await credentialHeaders(ctx, "optional");
+    if (Object.keys(headers).length > 0) {
       try {
-        me = (await request(ctx, "GET", "/api/v1/auth/me")).data;
+        me = (await request(ctx, "GET", "/api/v1/auth/me", { auth: "none", headers })).data;
       } catch (err) {
         if (!(err instanceof PlenaryError2)) throw err;
         if (err.status === 403) undescribed = true;
@@ -974,13 +1407,13 @@ function registerStatus(program, io) {
     if (me?.principal === "api_key") {
       lines.push(`Credential ${me.key_type} API key "${me.name}" (${me.grants.length} grant${me.grants.length === 1 ? "" : "s"}${me.sites.length ? `, sites ${me.sites.join(", ")}` : ""})`);
     } else if (me?.principal === "user") {
-      lines.push(`Credential user session, role ${me.role_name ?? me.role}`);
+      lines.push(`Credential user session (stored login), role ${me.role_name ?? me.role}`);
     } else if (credentialError) {
       lines.push(`Credential rejected: ${credentialError.code} (HTTP ${credentialError.status})`);
     } else if (undescribed) {
       lines.push("Credential API key accepted (this server predates API-key support on /auth/me and cannot describe the key)");
     } else {
-      lines.push("Credential none (set PLENARY_API_KEY or pass --api-key)");
+      lines.push("Credential none (set PLENARY_API_KEY, pass --api-key, or run `plenary login`)");
     }
     if (ctx.configPath) lines.push(`Config     ${ctx.configPath}`);
     io.stdout.write(lines.join("\n") + "\n");
@@ -991,7 +1424,7 @@ function registerStatus(program, io) {
 // src/cli.ts
 function version() {
   try {
-    const pkg = JSON.parse(readFileSync5(new URL("../package.json", import.meta.url), "utf8"));
+    const pkg = JSON.parse(readFileSync6(new URL("../package.json", import.meta.url), "utf8"));
     return pkg.version;
   } catch {
     return "0.0.0";
@@ -1003,12 +1436,14 @@ function createProgram(io) {
     writeErr: (s) => io.stderr.write(s)
   });
   registerInit(program, io);
+  registerAuth(program, io);
   registerStatus(program, io);
   registerMetadata(program, io);
   registerCatalog(program, io, "models");
   registerFormEntries(registerCatalog(program, io, "forms"), io);
   registerEntries(program, io);
   registerMedia(program, io);
+  registerAdmin(program, io);
   registerApi(program, io);
   return program;
 }