@plenary/cli 1.0.1 → 1.1.0

package/dist/index.js

@@ -393,6 +393,35 @@ async function readSecret(io, prompt) {
   }
 }
 
+// src/entries/client.ts
+import { createClient } from "@plenary/client";
+function requireSiteKey(ctx) {
+  if (!ctx.siteKey) {
+    throw usageError("no site key: pass --site, set PLENARY_SITE_KEY, or set siteKey in plenary.json");
+  }
+  return ctx.siteKey;
+}
+async function resolveLocale(ctx, siteKey) {
+  if (ctx.locale) return ctx.locale;
+  const sites = await request(ctx, "GET", "sites");
+  const site = sites.data.find((s) => s.key === siteKey);
+  if (!site) throw usageError(`site "${siteKey}" not found on the instance`);
+  return site.default_locale;
+}
+async function contentClient(ctx) {
+  const siteKey = requireSiteKey(ctx);
+  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/commands/admin.ts
 function collect(value, previous) {
   return [...previous, value];
@@ -404,8 +433,8 @@ function parseGrant(spec) {
   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>]`);
+    else if (name === "model" && value) grant.content_model_key = value;
+    else throw usageError(`invalid --grant "${spec}": expected key[,site=<key>][,model=<key>]`);
   }
   return grant;
 }
@@ -427,10 +456,11 @@ function registerAdmin(program, io) {
     ]);
     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 roles = program.command("roles").description("The configured site's roles (needs a super user session)");
+  roles.command("list").description("List the site's roles").action(async (_flags, cmd) => {
     const ctx = resolveContext(cmd.optsWithGlobals(), io);
-    const res = await request(ctx, "GET", "roles", { auth: "session" });
+    const site = requireSiteKey(ctx);
+    const res = await request(ctx, "GET", `sites/${encodeURIComponent(site)}/roles`, { auth: "session" });
     if (ctx.json) {
       io.stdout.write(toJson(res.data) + "\n");
       return;
@@ -444,21 +474,25 @@ function registerAdmin(program, io) {
     ]);
     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) => {
+  roles.command("get").description("Show one of the site's roles 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" });
+    const site = requireSiteKey(ctx);
+    const res = await request(ctx, "GET", `sites/${encodeURIComponent(site)}/roles/${encodeURIComponent(key)}`, {
+      auth: "session"
+    });
     if (ctx.json) {
       io.stdout.write(toJson(res.data) + "\n");
       return;
     }
     const r = res.data;
     const head = [
+      ["Site", r.site_key],
       ["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 ?? ""]);
+    const grants = r.grants.map((g) => [g.key, g.site_key ?? "", g.content_model_key ?? ""]);
     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)");
@@ -484,10 +518,14 @@ function registerAdmin(program, 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>", "the site the key belongs to: a public key reads it, a private key's grants are held to it").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(
+  keys.command("create").description(
+    "Create an API key; the secret is printed once, alone on stdout. --site names the site the key belongs to: a public key reads it (default: the configured site), a private key's grants are held to it"
+  ).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=<model key>] (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);
+      const globals = cmd.optsWithGlobals();
+      const ctx = resolveContext(globals, io);
       if (flags.type !== "private" && flags.type !== "public") throw usageError("--type must be private or public");
+      const site = globals.site ?? (flags.type === "public" ? ctx.siteKey : void 0);
       const body = {
         name: flags.name,
         description: flags.description ?? null,
@@ -495,7 +533,7 @@ function registerAdmin(program, io) {
         is_active: true,
         expires_at: flags.expires ?? null,
         grants: flags.grant.map(parseGrant),
-        ...flags.site ? { site_key: flags.site } : {},
+        ...site ? { site_key: site } : {},
         allowed_origins: flags.origin,
         rate_limit_per_minute: Number(flags.rateLimit),
         include_drafts: Boolean(flags.includeDrafts)
@@ -568,6 +606,12 @@ Examples:
 }
 
 // src/commands/auth.ts
+function describeUser(me) {
+  if (me.is_super_user) return "super user";
+  const roles = /* @__PURE__ */ new Set();
+  for (const g of me.grants) if (g.role_key && g.site_key) roles.add(`${g.role_key} on ${g.site_key}`);
+  return roles.size ? [...roles].join(", ") : "no site roles";
+}
 async function login(ctx, identifier, password, otpMethod) {
   const io = ctx.io;
   const first = await request(ctx, "POST", "auth/login", {
@@ -631,11 +675,11 @@ $XDG_CONFIG_HOME/plenary/credentials.json, keyed by instance.`
     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"
+        toJson({ base_url: baseUrl, identifier, is_super_user: me.data.is_super_user, credentials: credentialsPath(io) }) + "\n"
       );
       return;
     }
-    io.stdout.write(`logged in to ${baseUrl} as ${identifier} (${me.data.role_name ?? me.data.role})
+    io.stdout.write(`logged in to ${baseUrl} as ${identifier} (${describeUser(me.data)})
 `);
   });
   program.command("logout").description("Revoke the stored session for this instance").action(async (_flags, cmd) => {
@@ -681,9 +725,9 @@ $XDG_CONFIG_HOME/plenary/credentials.json, keyed by instance.`
     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 };
+      out.session = { identifier: stored.identifier ?? null, is_super_user: me.data.is_super_user };
       lines.push(
-        `Session   ${stored.identifier ?? "user"} (${me.data.role_name ?? me.data.role}), used for admin commands${ctx.apiKey ? "" : " and content"}`
+        `Session   ${stored.identifier ?? "user"} (${describeUser(me.data)}), used for admin commands${ctx.apiKey ? "" : " and content"}`
       );
     }
     if (lines.length === 0) lines.push("no credentials: set PLENARY_CLI_API_KEY or run `plenary login`");
@@ -749,34 +793,8 @@ function registerCatalog(program, io, name) {
   return group;
 }
 
-// src/entries/client.ts
-import { createClient } from "@plenary/client";
-function requireSiteKey(ctx) {
-  if (!ctx.siteKey) {
-    throw usageError("no site key: pass --site, set PLENARY_SITE_KEY, or set siteKey in plenary.json");
-  }
-  return ctx.siteKey;
-}
-async function resolveLocale(ctx, siteKey) {
-  if (ctx.locale) return ctx.locale;
-  const sites = await request(ctx, "GET", "sites");
-  const site = sites.data.find((s) => s.key === siteKey);
-  if (!site) throw usageError(`site "${siteKey}" not found on the instance`);
-  return site.default_locale;
-}
-async function contentClient(ctx) {
-  const siteKey = requireSiteKey(ctx);
-  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/commands/entries.ts
+import { PlenaryNotFoundError } from "@plenary/client";
 
 // src/entries/query.ts
 var OPERATORS = /* @__PURE__ */ new Set(["$eq", "$ne", "$lt", "$lte", "$gt", "$gte", "$in", "$nin", "$like", "$ilike", "$is_null"]);
@@ -850,6 +868,96 @@ async function toListOptions(flags, stdin) {
   return opts;
 }
 
+// src/commands/folders.ts
+function contentFolders(ctx, model) {
+  return { path: `content/${encodeURIComponent(model)}/folders`, siteKey: requireSiteKey(ctx) };
+}
+function mediaFolders(ctx) {
+  return { path: "media/folders", siteKey: ctx.siteKey };
+}
+function normalizePath(p) {
+  const trimmed = p.trim().replace(/\/+$/, "");
+  return trimmed === "" ? "/" : trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+}
+async function listFolders(ctx, scope) {
+  const res = await request(ctx, "GET", scope.path, { query: { site_key: scope.siteKey } });
+  return res.data.folders;
+}
+async function findFolder(ctx, scope, ref) {
+  const folders = await listFolders(ctx, scope);
+  const byPath = ref.startsWith("/");
+  const path7 = normalizePath(ref);
+  const matches = folders.filter((f) => byPath ? f.path === path7 : f.id === ref);
+  if (matches.length === 0) throw usageError(`no folder ${ref}`);
+  if (matches.length > 1) throw usageError(`${ref} is a folder on several sites; pass --site`);
+  return matches[0];
+}
+async function folderIdAt(ctx, scope, path7) {
+  if (normalizePath(path7) === "/") return null;
+  return (await findFolder(ctx, scope, normalizePath(path7))).id;
+}
+function registerFolderCommands(parent, io, kind) {
+  const scopeFor = (ctx, model) => kind === "content" ? contentFolders(ctx, model) : mediaFolders(ctx);
+  const withModel = (cmd) => kind === "content" ? cmd.argument("<model>") : cmd;
+  const split = (args) => {
+    const cmd = args[args.length - 1];
+    const flags = args[args.length - 2];
+    const positional = args.slice(0, -2);
+    const model = kind === "content" ? positional.shift() : void 0;
+    return { ctx: resolveContext(cmd.optsWithGlobals(), io), model, positional, flags };
+  };
+  const countHeader = kind === "content" ? "ENTRIES" : "MEDIA";
+  withModel(parent.command("list").description("List folders by path")).action(async (...args) => {
+    const { ctx, model } = split(args);
+    const folders = await listFolders(ctx, scopeFor(ctx, model));
+    if (ctx.json) {
+      io.stdout.write(toJson(folders) + "\n");
+      return;
+    }
+    const rows = folders.map((f) => [f.id, f.path, f.name, String(f.entry_count ?? f.media_count ?? "")]);
+    io.stdout.write(formatTable(rows, ["ID", "PATH", "NAME", countHeader]) + "\n");
+  });
+  withModel(parent.command("get").description("Print one folder as JSON")).argument("<id-or-path>", "a folder id, or its path such as /company/team").action(async (...args) => {
+    const { ctx, model, positional } = split(args);
+    io.stdout.write(toJson(await findFolder(ctx, scopeFor(ctx, model), positional[0])) + "\n");
+  });
+  withModel(parent.command("create").description("Create a folder; its parent must exist")).argument("<path>", "the new folder's path, such as /company/team; the last segment is its slug").option("--name <name>", "display name (default: the slug)").action(async (...args) => {
+    const { ctx, model, positional, flags } = split(args);
+    const scope = scopeFor(ctx, model);
+    const path7 = normalizePath(positional[0]);
+    if (path7 === "/") throw usageError("the root folder always exists");
+    const slug = path7.slice(path7.lastIndexOf("/") + 1);
+    const parentId = await folderIdAt(ctx, scope, path7.slice(0, path7.lastIndexOf("/")));
+    const res = await request(ctx, "POST", scope.path, {
+      query: { site_key: scope.siteKey },
+      body: { parent_id: parentId, name: flags.name ?? slug, slug }
+    });
+    if (ctx.json) io.stdout.write(toJson(res.data) + "\n");
+    else io.stdout.write(`created ${res.data.id}  ${res.data.path}
+`);
+  });
+  withModel(
+    parent.command("delete").description(`Delete a folder; its sub-folders and ${kind === "content" ? "entries" : "media"} move up to its parent`)
+  ).argument("<id-or-path>").option("-y, --yes", "do not ask").action(async (...args) => {
+    const { ctx, model, positional, flags } = split(args);
+    const scope = scopeFor(ctx, model);
+    const folder = await findFolder(ctx, scope, positional[0]);
+    await confirm(io, `Delete folder ${folder.path}?`, Boolean(flags.yes));
+    await request(ctx, "DELETE", `${scope.path}/${encodeURIComponent(folder.id)}`, {
+      query: { site_key: kind === "content" ? scope.siteKey : void 0 }
+    });
+    if (ctx.json) io.stdout.write(toJson({ id: folder.id, deleted: true }) + "\n");
+    else io.stdout.write(`deleted ${folder.id}  ${folder.path}
+`);
+  });
+}
+function registerContentFolders(program, io) {
+  registerFolderCommands(program.command("folders").description("A model's content folders"), io, "content");
+}
+function registerMediaFolders(media, io) {
+  registerFolderCommands(media.command("folders").description("Media library folders"), io, "media");
+}
+
 // src/commands/entries.ts
 function collect3(value, previous) {
   return [...previous, value];
@@ -858,10 +966,13 @@ function withListFlags(cmd) {
   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");
+  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("--folder-path <path>", "content folder path, such as /company (instead of --folder; / is the root)").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");
 }
 function entryRow(e) {
-  return [e.id, e.status, e.slug ?? "", e.title ?? "", e.updated_at];
+  return [e.id ?? "", statusLabel(e), e.slug ?? "", e.title ?? "", e.updated_at ?? ""];
+}
+function statusLabel(e) {
+  return `${e.status ?? ""}${e.draft ? "*" : ""}`;
 }
 var ENTRY_HEADER = ["ID", "STATUS", "SLUG", "TITLE", "UPDATED"];
 var PAGE = 100;
@@ -885,6 +996,9 @@ function registerEntries(program, io) {
       const ctx = resolveContext(cmd.optsWithGlobals(), io);
       const client = await contentClient(ctx);
       const result = await client.listEntries(model, await toListOptions(flags, io.stdin));
+      if (!Array.isArray(result.items)) {
+        throw usageError(`${model} is a singleton; use 'plenary entries get ${model}'`);
+      }
       if (ctx.json) {
         io.stdout.write(toJson(result) + "\n");
         return;
@@ -908,17 +1022,26 @@ function registerEntries(program, io) {
     const body = { fields: await readObject(flags.data, io.stdin) };
     if (ctx.locale) body.locale = ctx.locale;
     applyWriteFlags(body, flags);
+    await applyFolderPath(ctx, model, body, flags);
     let entry = (await request(ctx, "POST", `content/${encodeURIComponent(model)}`, { query: { site_key: siteKey }, body })).data;
     if (flags.publish) entry = await publish(ctx, entry.id, "publish");
     report(ctx, entry, "created");
   });
   withWriteFlags(
     entries.command("update").description("Update an entry: --data is merged into its fields (a null removes one)").argument("<model>").argument("<slug-or-id>")
+  ).option("--publish", "publish it right after updating (on a published entry, publish the pending changes)").addHelpText(
+    "after",
+    `
+On a published entry the update is saved as pending changes and the live
+copy stays as it was until the entry is published again; --data is then
+merged into the pending copy. --publish makes the change live in a second
+call.`
   ).action(async (model, slug, flags, cmd) => {
     const ctx = resolveContext(cmd.optsWithGlobals(), io);
     const client = await contentClient(ctx);
     const current = await client.getEntry(model, slug);
-    const fields = { ...current.data };
+    const working = current.draft ?? current;
+    const fields = { ...working.data };
     if (flags.data !== void 0) {
       for (const [k, v] of Object.entries(await readObject(flags.data, io.stdin))) {
         if (v === null) delete fields[k];
@@ -927,14 +1050,16 @@ function registerEntries(program, io) {
     }
     const body = {
       fields,
-      slug: current.slug ?? void 0,
+      slug: working.slug ?? void 0,
       locale: current.locale ?? void 0,
       folder_id: current.folder_id,
       publish_at: current.publish_at,
       unpublish_at: current.unpublish_at
     };
     applyWriteFlags(body, flags);
-    const entry = (await request(ctx, "PUT", `content/${encodeURIComponent(current.id)}`, { body })).data;
+    await applyFolderPath(ctx, model, body, flags);
+    let entry = (await request(ctx, "PUT", `content/${encodeURIComponent(current.id)}`, { body })).data;
+    if (flags.publish) entry = await publish(ctx, entry.id, "publish");
     report(ctx, entry, "updated");
   });
   entries.command("delete").description("Delete an entry (recoverable from history while the model tracks revisions)").argument("<id>").option("--note <text>", "revision note").option("-y, --yes", "do not ask").action(async (id, flags, cmd) => {
@@ -945,12 +1070,20 @@ function registerEntries(program, io) {
     else io.stdout.write(`deleted ${id}
 `);
   });
-  for (const action of ["publish", "unpublish"]) {
-    entries.command(action).description(`${action === "publish" ? "Publish" : "Unpublish"} an entry now`).argument("<id>").action(async (id, _flags, cmd) => {
-      const ctx = resolveContext(cmd.optsWithGlobals(), io);
-      report(ctx, await publish(ctx, id, action), action === "publish" ? "published" : "unpublished");
-    });
-  }
+  entries.command("publish").description("Publish an entry now; on a published entry, make its pending changes live").argument("<id>").action(async (id, _flags, cmd) => {
+    const ctx = resolveContext(cmd.optsWithGlobals(), io);
+    report(ctx, await publish(ctx, id, "publish"), "published");
+  });
+  entries.command("unpublish").description("Unpublish an entry now").argument("<id>").option("--draft <merge|discard>", "with changes pending: keep them as the draft's content (merge) or drop them (discard)").action(async (id, flags, cmd) => {
+    const ctx = resolveContext(cmd.optsWithGlobals(), io);
+    const entry = (await request(ctx, "POST", `content/${encodeURIComponent(id)}/unpublish`, { query: { draft: flags.draft } })).data;
+    report(ctx, entry, "unpublished");
+  });
+  entries.command("discard").description("Drop the pending changes on a published entry, leaving the live copy as it is").argument("<id>").option("--note <text>", "revision note").action(async (id, flags, cmd) => {
+    const ctx = resolveContext(cmd.optsWithGlobals(), io);
+    const entry = (await request(ctx, "DELETE", `content/${encodeURIComponent(id)}/draft`, { query: { note: flags.note } })).data;
+    report(ctx, entry, "discarded");
+  });
   withListFlags(
     entries.command("export").description("Write every matching entry to stdout as NDJSON").argument("<model>")
   ).action(async (model, flags, cmd) => {
@@ -960,16 +1093,23 @@ function registerEntries(program, io) {
       io.stdout.write(JSON.stringify(e) + "\n");
     }
   });
-  entries.command("import").description("Create one entry per NDJSON line (exported entries or {fields, slug, \u2026} bodies)").argument("<model>").argument("<file>", "a file, or - for stdin").option("--publish", "publish each entry after creating it").addHelpText(
+  entries.command("import").description("Create one entry per NDJSON line (exported entries or {fields, slug, \u2026} bodies)").argument("<model>").argument("<file>", "a file, or - for stdin").option("--publish", "publish each entry after writing it").option("--upsert", "update the entry with the line's slug when it exists, instead of failing").addHelpText(
     "after",
     `
 Every line is tried; a line that fails is reported with its number and the
-run continues, exiting 1 at the end if any failed.`
+run continues, exiting 1 at the end if any failed.
+
+With --upsert a line is matched by its slug (unique per site, model and
+locale), so a seed file can be imported again. A match has its fields
+replaced by the line's; the slug, folder and schedule it doesn't state are
+kept. A line without a slug fails.`
   ).action(async (model, file, flags, cmd) => {
     const ctx = resolveContext(cmd.optsWithGlobals(), io);
     const siteKey = requireSiteKey(ctx);
+    const client = flags.upsert ? await contentClient(ctx) : void 0;
     const text = await readText(file === "-" ? "-" : `@${file}`, io.stdin);
     let failed = 0;
+    let updated = 0;
     let n = 0;
     for (const raw of text.split("\n")) {
       const line = raw.trim();
@@ -977,12 +1117,23 @@ run continues, exiting 1 at the end if any failed.`
       n++;
       try {
         const body = importBody(JSON.parse(line), ctx);
-        let entry = (await request(ctx, "POST", `content/${encodeURIComponent(model)}`, {
+        const current = client && await findBySlug(client, model, body);
+        let entry = current ? (await request(ctx, "PUT", `content/${encodeURIComponent(current.id)}`, {
+          body: {
+            slug: current.slug ?? void 0,
+            locale: current.locale ?? void 0,
+            folder_id: current.folder_id,
+            publish_at: current.publish_at,
+            unpublish_at: current.unpublish_at,
+            ...body
+          }
+        })).data : (await request(ctx, "POST", `content/${encodeURIComponent(model)}`, {
           query: { site_key: siteKey },
           body
         })).data;
+        if (current) updated++;
         if (flags.publish) entry = await publish(ctx, entry.id, "publish");
-        io.stdout.write(`ok    ${entry.id}${entry.slug ? `  ${entry.slug}` : ""}
+        io.stdout.write(`ok    ${entry.id}${entry.slug ? `  ${entry.slug}` : ""}${current ? "  (updated)" : ""}
 `);
       } catch (err) {
         failed++;
@@ -991,7 +1142,7 @@ run continues, exiting 1 at the end if any failed.`
 `);
       }
     }
-    io.stderr.write(`${n - failed} created, ${failed} failed
+    io.stderr.write(`${n - failed - updated} created, ${updated ? `${updated} updated, ` : ""}${failed} failed
 `);
     if (failed) throw new CliError("", 1);
   });
@@ -1003,6 +1154,11 @@ function applyWriteFlags(body, flags) {
   if (flags.unpublishAt !== void 0) body.unpublish_at = flags.unpublishAt;
   if (flags.note !== void 0) body.note = flags.note;
 }
+async function applyFolderPath(ctx, model, body, flags) {
+  if (flags.folderPath === void 0) return;
+  if (flags.folder !== void 0) throw usageError("pass --folder or --folder-path, not both");
+  body.folder_id = await folderIdAt(ctx, contentFolders(ctx, model), flags.folderPath);
+}
 function importBody(line, ctx) {
   if ("fields" in line) return line;
   if (!("data" in line)) throw usageError("expected an object with fields or data");
@@ -1015,9 +1171,18 @@ function importBody(line, ctx) {
   if (e.unpublish_at) body.unpublish_at = e.unpublish_at;
   return body;
 }
+async function findBySlug(client, model, body) {
+  if (!body.slug) throw usageError("--upsert needs a slug on every line");
+  try {
+    return await client.getEntry(model, body.slug, body.locale ? { locale: body.locale } : {});
+  } catch (err) {
+    if (err instanceof PlenaryNotFoundError) return void 0;
+    throw err;
+  }
+}
 function report(ctx, entry, verb) {
   if (ctx.json) ctx.io.stdout.write(toJson(entry) + "\n");
-  else ctx.io.stdout.write(`${verb} ${entry.id}${entry.slug ? `  ${entry.slug}` : ""}  (${entry.status})
+  else ctx.io.stdout.write(`${verb} ${entry.id}${entry.slug ? `  ${entry.slug}` : ""}  (${statusLabel(entry)})
 `);
 }
 
@@ -1090,15 +1255,53 @@ function summary(data) {
 // src/commands/media.ts
 import { readFileSync as readFileSync4 } from "fs";
 import path3 from "path";
+var MIME_BY_EXT = {
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".png": "image/png",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".avif": "image/avif",
+  ".svg": "image/svg+xml",
+  ".tif": "image/tiff",
+  ".tiff": "image/tiff",
+  ".bmp": "image/bmp",
+  ".mp4": "video/mp4",
+  ".webm": "video/webm",
+  ".ogv": "video/ogg",
+  ".mov": "video/quicktime",
+  ".mp3": "audio/mpeg",
+  ".ogg": "audio/ogg",
+  ".wav": "audio/wav",
+  ".flac": "audio/flac",
+  ".pdf": "application/pdf",
+  ".zip": "application/zip",
+  ".txt": "text/plain",
+  ".csv": "text/csv"
+};
+function mimeForFile(file) {
+  return MIME_BY_EXT[path3.extname(file).toLowerCase()] ?? "application/octet-stream";
+}
 function size(bytes) {
   if (bytes < 1024) return `${bytes} B`;
   if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
   return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
 }
+async function findExisting(ctx, name, folder) {
+  const pattern = `^${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}$`;
+  const res = await request(ctx, "GET", "media", {
+    query: { search: pattern, site_key: ctx.siteKey, limit: "100" }
+  });
+  return res.data.find((m) => m.file_name === name && (m.folder_id ?? void 0) === folder);
+}
 function registerMedia(program, io) {
   const media = program.command("media").description("Media library");
-  media.command("upload").description("Upload one or more files").argument("<files...>").option("--folder <id>", "media folder id").option("--private", "store as a private asset").action(async (files, flags, cmd) => {
+  media.command("upload").description("Upload one or more files").argument("<files...>").option("--folder <id>", "media folder id").option("--folder-path <path>", "media folder path, such as /brand/logos (instead of --folder)").option("--private", "store as a private asset").option("--skip-existing", "skip a file whose name is already in the folder").action(async (files, flags, cmd) => {
     const ctx = resolveContext(cmd.optsWithGlobals(), io);
+    if (flags.folderPath !== void 0) {
+      if (flags.folder !== void 0) throw usageError("pass --folder or --folder-path, not both");
+      flags.folder = await folderIdAt(ctx, mediaFolders(ctx), flags.folderPath) ?? void 0;
+    }
     const uploaded = [];
     let failed = 0;
     for (const file of files) {
@@ -1108,8 +1311,17 @@ function registerMedia(program, io) {
       } catch (err) {
         throw usageError(`cannot read ${file}: ${err.message}`);
       }
+      if (flags.skipExisting) {
+        const existing = await findExisting(ctx, path3.basename(file), flags.folder);
+        if (existing) {
+          uploaded.push(existing);
+          if (!ctx.json) io.stdout.write(`${existing.media_id}  ${existing.file_name}  (exists)
+`);
+          continue;
+        }
+      }
       const form = new FormData();
-      form.append("upload_file", new Blob([new Uint8Array(bytes)]), path3.basename(file));
+      form.append("upload_file", new Blob([new Uint8Array(bytes)], { type: mimeForFile(file) }), path3.basename(file));
       if (ctx.siteKey) form.append("site_key", ctx.siteKey);
       if (flags.folder) form.append("folder_id", flags.folder);
       if (flags.private) form.append("visibility", "private");
@@ -1146,6 +1358,7 @@ function registerMedia(program, io) {
     const res = await request(ctx, "GET", `media/${encodeURIComponent(id)}`);
     io.stdout.write(toJson(res.data) + "\n");
   });
+  registerMediaFolders(media, io);
 }
 
 // src/commands/metadata.ts
@@ -1251,9 +1464,9 @@ function kindsOf(opts, site) {
   } catch (err) {
     throw usageError(`--only: ${err.message}`);
   }
-  if (!site) return kinds;
+  if (site) return kinds;
   if (opts.only && opts.only !== "all" && kinds.includes("roles")) {
-    throw usageError(`roles are instance-wide and not part of site ${site}'s tree; use --all-sites`);
+    throw usageError("roles belong to a site and are not part of the instance-wide tree; drop --all-sites");
   }
   return kinds.filter((k) => k !== "roles");
 }
@@ -1307,7 +1520,7 @@ async function runImport(ctx, root, opts, apply) {
   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)"];
-var allSitesOption = ["--all-sites", "the whole instance, not just the configured site (roles need this)"];
+var allSitesOption = ["--all-sites", "the whole instance, not just the configured site (no roles)"];
 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",
@@ -1315,10 +1528,11 @@ function registerMetadata(program, io) {
 The tree is models/, forms/, roles/ and sites/ under the metadata directory
 ("metadataDir" in plenary.json, default ./plenary), one <key>.yaml per
 entity. With a site configured (--site, PLENARY_SITE_KEY or "siteKey" in
-plenary.json) the tree is that site's alone: its models, forms and site file,
-never roles, and --prune deletes only within it. --all-sites moves the whole
-instance. Models and forms need an API key or a session; roles and sites need
-a user session (plenary login). See docs/CLI.md.`
+plenary.json) the tree is that site's alone: its models, forms, roles and
+site file, and --prune deletes only within it. --all-sites moves the whole
+instance, which holds no roles. Models and forms need an API key or a
+session; roles need a super user session and sites a session that may update
+them (plenary login). See docs/CLI.md.`
   );
   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).option(...allSitesOption).action(async (opts, cmd) => {
     const ctx = resolveContext(cmd.optsWithGlobals(), io);
@@ -1455,7 +1669,7 @@ 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.site_key ? `, site ${me.site_key}` : ", instance-wide"})`);
     } else if (me?.principal === "user") {
-      lines.push(`Credential user session (stored login), role ${me.role_name ?? me.role}`);
+      lines.push(`Credential user session (stored login), ${describeUser(me)}`);
     } else if (credentialError) {
       lines.push(`Credential rejected: ${credentialError.code} (HTTP ${credentialError.status})`);
     } else if (undescribed) {
@@ -1490,6 +1704,7 @@ function createProgram(io) {
   registerCatalog(program, io, "models");
   registerFormEntries(registerCatalog(program, io, "forms"), io);
   registerEntries(program, io);
+  registerContentFolders(program, io);
   registerMedia(program, io);
   registerAdmin(program, io);
   registerApi(program, io);