@homespunapps/cli 1.0.1 → 1.4.3

package/dist/commands/grant.js

@@ -0,0 +1,158 @@
+// `homespun grants` (M5) grant-link management for a v2 app: mint a
+// capability URL that confers a DECLARED custom role on a stable, per-holder
+// anonymous identity, list an app's grant links, and revoke one. Every verb
+// targets an app via a required `--app <idOrSlug>` flag, resolved the same way
+// `homespun members`/`homespun data` do (resolveAppId).
+//
+// Auth on the relay side is owner-or-agent; this CLI always authenticates as
+// the owning agent, so any verb works for an app the calling agent's owning
+// human owns.
+//
+// A grant link NEVER escalates: --role must be a DECLARED custom role
+// (x-homespun-manifest.roles), never a built-in role (owner/member/agent). The
+// minted grant_url carries the raw token in its #g= fragment and is printed
+// ONCE (it is never recoverable afterward).
+import { assertKnownFlags } from "../argv.js";
+import { nounSpec, renderNounHelp, specFor } from "../help-catalog.js";
+import { makeClient } from "../config.js";
+import { fail, failFromError, printJson } from "../output.js";
+import { resolveAppId } from "../resolve-app.js";
+export async function runGrant(args) {
+    const verb = args.positionals[0];
+    if ((verb === undefined || verb === "help") && args.bools.has("help")) {
+        process.stdout.write(renderNounHelp(nounSpec("grants")) + "\n");
+        return;
+    }
+    if (verb === undefined) {
+        fail("missing verb: homespun grants <mint|list|revoke>", "invalid_args");
+    }
+    const sub = {
+        positionals: args.positionals.slice(1),
+        flags: args.flags,
+        bools: args.bools,
+        ...(args.danglingValueFlags !== undefined
+            ? { danglingValueFlags: args.danglingValueFlags }
+            : {}),
+    };
+    switch (verb) {
+        case "mint":
+            return runMint(sub);
+        case "list":
+            return runList(sub);
+        case "revoke":
+            return runRevoke(sub);
+        default:
+            fail(`unknown verb '${verb}' (homespun grants <mint|list|revoke>)`, "invalid_args");
+    }
+}
+function parsePositiveInt(raw, flag) {
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n <= 0) {
+        fail(`${flag} must be a positive integer`, "invalid_args");
+    }
+    return n;
+}
+// ---------------------------------------------------------------------------
+// mint
+// ---------------------------------------------------------------------------
+async function runMint(args) {
+    assertKnownFlags(args, ...specFor("grants", "mint"));
+    const appArg = args.flags.get("app");
+    if (!appArg) {
+        fail("usage: homespun grants mint --app <idOrSlug> --role <customRole>", "invalid_args");
+    }
+    const role = args.flags.get("role");
+    if (!role) {
+        fail("--role is required", "invalid_args");
+    }
+    const mode = args.flags.get("mode");
+    if (mode !== undefined && mode !== "once" && mode !== "multi") {
+        fail('--mode must be "once" or "multi"', "invalid_args");
+    }
+    const pinRow = args.flags.get("pin-row");
+    const pinWhereRaw = args.flags.get("pin-where");
+    if (pinRow !== undefined && pinWhereRaw !== undefined) {
+        fail("--pin-row and --pin-where are mutually exclusive", "invalid_args");
+    }
+    let pin;
+    if (pinRow !== undefined) {
+        pin = { rowKey: pinRow };
+    }
+    else if (pinWhereRaw !== undefined) {
+        let parsed;
+        try {
+            parsed = JSON.parse(pinWhereRaw);
+        }
+        catch {
+            fail("--pin-where must be a JSON array of conditions", "invalid_args");
+        }
+        if (!Array.isArray(parsed)) {
+            fail("--pin-where must be a JSON array of conditions", "invalid_args");
+        }
+        pin = { where: parsed };
+    }
+    const maxUsesRaw = args.flags.get("max-uses");
+    const ttlRaw = args.flags.get("ttl");
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    try {
+        printJson(await client.mintAppGrant(appId, {
+            role: role,
+            ...(mode !== undefined ? { mode: mode } : {}),
+            ...(maxUsesRaw !== undefined
+                ? { maxUses: parsePositiveInt(maxUsesRaw, "--max-uses") }
+                : {}),
+            ...(args.flags.get("label") !== undefined
+                ? { label: args.flags.get("label") }
+                : {}),
+            ...(ttlRaw !== undefined
+                ? { ttlSeconds: parsePositiveInt(ttlRaw, "--ttl") }
+                : {}),
+            ...(pin !== undefined ? { pin } : {}),
+        }));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// list
+// ---------------------------------------------------------------------------
+async function runList(args) {
+    assertKnownFlags(args, ...specFor("grants", "list"));
+    const appArg = args.flags.get("app");
+    if (!appArg) {
+        fail("usage: homespun grants list --app <idOrSlug>", "invalid_args");
+    }
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    try {
+        printJson(await client.listAppGrants(appId));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// revoke
+// ---------------------------------------------------------------------------
+async function runRevoke(args) {
+    assertKnownFlags(args, ...specFor("grants", "revoke"));
+    const appArg = args.flags.get("app");
+    if (!appArg) {
+        fail("usage: homespun grants revoke --app <idOrSlug> --grant <grantId>", "invalid_args");
+    }
+    const grantId = args.flags.get("grant");
+    if (!grantId) {
+        fail("--grant is required", "invalid_args");
+    }
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    try {
+        await client.revokeAppGrant(appId, grantId);
+        printJson({ revoked: true, app_id: appId, grant_id: grantId });
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}

package/dist/commands/ingest.js

@@ -0,0 +1,85 @@
+// `homespun ingest`: inbound catch-hook read surface for an app (inbound-webhooks
+// PR 3). List the app's declared hooks with their full secret URL, and rotate a
+// hook's secret. Every verb targets an app via a required `--app <idOrSlug>`,
+// resolved the same way `homespun members`/`homespun data` do (resolveAppId).
+//
+// This is the smallest surface an agent needs during app setup: after deploying
+// a manifest that declares an `ingest` hook, the agent runs `homespun ingest list`
+// to read back the exact URL and tells its owner to paste it into Stripe/Zapier/
+// Home Assistant/etc. Hooks are manifest-declared, so there is no create/delete
+// here; `rotate` re-keys a leaked URL without a redeploy.
+//
+// Auth on the relay side is owner-or-agent (the owning agent's API key OR the
+// owner human's login cookie); this CLI always authenticates as the agent, so
+// both verbs work for an app the calling agent's owning human owns.
+import { assertKnownFlags } from "../argv.js";
+import { nounSpec, renderNounHelp, specFor } from "../help-catalog.js";
+import { makeClient } from "../config.js";
+import { fail, failFromError, printJson } from "../output.js";
+import { resolveAppId } from "../resolve-app.js";
+export async function runIngest(args) {
+    const verb = args.positionals[0];
+    if ((verb === undefined || verb === "help") && args.bools.has("help")) {
+        process.stdout.write(renderNounHelp(nounSpec("ingest")) + "\n");
+        return;
+    }
+    if (verb === undefined) {
+        fail("missing verb (homespun ingest <list|rotate>)", "invalid_args");
+    }
+    const sub = {
+        positionals: args.positionals.slice(1),
+        flags: args.flags,
+        bools: args.bools,
+        ...(args.danglingValueFlags !== undefined
+            ? { danglingValueFlags: args.danglingValueFlags }
+            : {}),
+    };
+    switch (verb) {
+        case "list":
+            return runList(sub);
+        case "rotate":
+            return runRotate(sub);
+        default:
+            fail(`unknown verb '${verb}' (homespun ingest <list|rotate>)`, "invalid_args");
+    }
+}
+// ---------------------------------------------------------------------------
+// list
+// ---------------------------------------------------------------------------
+async function runList(args) {
+    assertKnownFlags(args, ...specFor("ingest", "list"));
+    const appArg = args.flags.get("app");
+    if (!appArg) {
+        fail("usage: homespun ingest list --app <idOrSlug>", "invalid_args");
+    }
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    try {
+        printJson(await client.listIngestHooks(appId));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// rotate
+// ---------------------------------------------------------------------------
+async function runRotate(args) {
+    assertKnownFlags(args, ...specFor("ingest", "rotate"));
+    const appArg = args.flags.get("app");
+    if (!appArg) {
+        fail("usage: homespun ingest rotate --app <idOrSlug> --name <hookName>", "invalid_args");
+    }
+    const name = args.flags.get("name");
+    if (!name) {
+        fail("--name is required", "invalid_args");
+    }
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    try {
+        printJson(await client.rotateIngestHook(appId, name));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}

package/dist/commands/key.js

@@ -5,37 +5,11 @@
 // authenticated agent, so there is exactly one key — the caller's own. Both
 // verbs therefore act ONLY on the caller's own key.
 import { assertKnownFlags } from "../argv.js";
+import { specFor } from "../help-catalog.js";
 import { makeClient } from "../config.js";
 import { printJson, fail, failFromError } from "../output.js";
-const NO_FLAGS = [];
-const NO_BOOLS = [];
-const REVOKE_BOOLS = ["yes"];
-export const keyHelp = `homespun key — inspect or revoke YOUR agent's API key
-
-Usage:
-  homespun key <verb> [options]
-
-Verbs:
-  list       Show YOUR agent's key info. The relay scopes keys to the
-             authenticated agent — there is exactly one key per agent, your
-             own. Prints { agent_id, name, key_prefix, created_at,
-             last_used_at, revoked_at }.
-
-  revoke     Revoke YOUR OWN API key — a self-destruct. The key stops working
-             IMMEDIATELY; every subsequent command fails until you run
-             'homespun agent register' again to provision a new key. The relay only
-             allows revoking your own key. Requires --yes to confirm.
-             Prints { revoked: true, agent_id }.
-
-Options:
-  --yes               Confirm 'key revoke' (required — it is irreversible).
-  --url <url>         Relay base URL (overrides HOMESPUN_URL).
-  --api-key <key>     Agent API key (overrides HOMESPUN_API_KEY).
-  -h, --help          Show this help.
-
-Output: stdout is machine-readable JSON.`;
 async function runKeyList(args) {
-    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "homespun key list");
+    assertKnownFlags(args, ...specFor("key", "list"));
     const client = makeClient(args);
     try {
         const info = await client.listKeys();
@@ -45,8 +19,20 @@ async function runKeyList(args) {
         failFromError(e);
     }
 }
+async function runKeyMint(args) {
+    assertKnownFlags(args, ...specFor("key", "mint"));
+    const client = makeClient(args);
+    try {
+        // The raw key is in this response ONCE and never again, so print it verbatim.
+        const minted = await client.mintKey();
+        printJson(minted);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
 async function runKeyRevoke(args) {
-    assertKnownFlags(args, NO_FLAGS, REVOKE_BOOLS, "homespun key revoke");
+    assertKnownFlags(args, ...specFor("key", "revoke"));
     if (!args.bools.has("yes")) {
         fail("'homespun key revoke' revokes YOUR OWN API key — it stops working " +
             "immediately and is irreversible. Pass --yes to confirm.", "confirmation_required");
@@ -70,13 +56,16 @@ export async function runKey(args) {
         case "list":
             await runKeyList(args);
             break;
+        case "mint":
+            await runKeyMint(args);
+            break;
         case "revoke":
             await runKeyRevoke(args);
             break;
         case undefined:
-            fail("missing verb — usage: homespun key <list|revoke> (run 'homespun key --help')", "invalid_args");
+            fail("missing verb; usage: homespun key <list|mint|revoke> (run 'homespun key --help')", "invalid_args");
             break;
         default:
-            fail(`unknown key verb '${sub}' — expected list|revoke (run 'homespun key --help')`, "invalid_args");
+            fail(`unknown key verb '${sub}', expected list|mint|revoke (run 'homespun key --help')`, "invalid_args");
     }
 }

package/dist/commands/logout.js

@@ -1,36 +1,10 @@
 // `homespun agent logout` — clear one (or all) saved profile(s).
 import { assertKnownFlags } from "../argv.js";
+import { specFor } from "../help-catalog.js";
 import { clearStore, readStore, removeProfile, resolveProfile, } from "../store.js";
 import { printJson, fail } from "../output.js";
-const NO_FLAGS = [];
-const KNOWN_BOOLS = ["all"];
-export const logoutHelp = `homespun agent logout — clear a saved profile (or all of them)
-
-Usage:
-  homespun agent logout [options]
-
-By default this clears the ACTIVE profile only (the one selected by --profile
-/ HOMESPUN_PROFILE / the store's current_profile). The on-disk file keeps the
-other profiles, and 'current_profile' is unset so the next command falls back
-to env / default URL until another profile is selected.
-
-Pass --all to delete the whole config file (the pre-profile behaviour) — this
-wipes every profile, not just the active one. Idempotent — no error if there
-is nothing to clear.
-
-This only clears the LOCAL config. It does NOT revoke the key on the relay —
-keys keep working until revoked. To revoke a key server-side, use
-'homespun key revoke'.
-
-Options:
-  --profile <name>    Target this profile instead of the active one.
-  --all               Delete every profile (the whole config file).
-  -h, --help          Show this help.
-
-Output (stdout, JSON):
-  { cleared: true, profile, path }   (profile=null when --all)`;
 export async function runLogout(args) {
-    assertKnownFlags(args, NO_FLAGS, KNOWN_BOOLS, "homespun agent logout");
+    assertKnownFlags(args, ...specFor("agent", "logout"));
     if (args.bools.has("all")) {
         // Nuke everything — file gone, both legacy and new shape covered.
         const path = clearStore();

package/dist/commands/members.js

@@ -14,43 +14,18 @@
 // authorizable — was removed in PR 2c-1 along with the rest of the v1
 // Template subsystem.)
 import { assertKnownFlags } from "../argv.js";
+import { nounSpec, renderNounHelp, specFor } from "../help-catalog.js";
 import { makeClient } from "../config.js";
 import { fail, failFromError, printJson } from "../output.js";
 import { resolveAppId } from "../resolve-app.js";
-export const membersHelp = `homespun members — app membership management
-
-Usage:
-  homespun members add    --app <idOrSlug> --email <email> [--role member]
-  homespun members list   --app <idOrSlug>
-  homespun members remove --app <idOrSlug> --human <humanId>
-
---app accepts either the app_id or its slug (resolved via GET /v1/apps?slug=
-when it doesn't look like a cuid).
-
-add: if a Human already exists for --email, the member row is attached
-immediately and the response is { member: { humanId, email, role,
-createdAt } }. Otherwise the relay mints a signed invite and emails a magic
-link, responding { ok: true, invited, expires_at }. Only "member" is a valid
---role (the default); ownership transfer is not available here. Fails with
-a relay error (503 auth_provider_unavailable) if the relay has no email
-provider configured.
-
-list: returns { members: [{ humanId, email, role, createdAt }] } — the
-app's owner plus every attached member.
-
-remove: idempotent; also revokes the human's live sessions on this app. The
-app owner cannot be removed (the relay refuses with a 409 conflict).
-
-Output (JSON). Errors on stderr:
-{"error":{"code","message"}} with non-zero exit.`;
 export async function runMembers(args) {
     const verb = args.positionals[0];
     if ((verb === undefined || verb === "help") && args.bools.has("help")) {
-        process.stdout.write(membersHelp + "\n");
+        process.stdout.write(renderNounHelp(nounSpec("members")) + "\n");
         return;
     }
     if (verb === undefined) {
-        fail("missing verb — homespun members <add|list|remove>", "invalid_args");
+        fail("missing verb — homespun members <add|list|set-role|remove|roles>", "invalid_args");
     }
     const sub = {
         positionals: args.positionals.slice(1),
@@ -65,17 +40,21 @@ export async function runMembers(args) {
             return runAdd(sub);
         case "list":
             return runList(sub);
+        case "set-role":
+            return runSetRole(sub);
         case "remove":
             return runRemove(sub);
+        case "roles":
+            return runRoles(sub);
         default:
-            fail(`unknown verb '${verb}' — homespun members <add|list|remove>`, "invalid_args");
+            fail(`unknown verb '${verb}' — homespun members <add|list|set-role|remove|roles>`, "invalid_args");
     }
 }
 // ---------------------------------------------------------------------------
 // add
 // ---------------------------------------------------------------------------
 async function runAdd(args) {
-    assertKnownFlags(args, ["app", "email", "role", "url", "api-key"], ["help"], "homespun members add");
+    assertKnownFlags(args, ...specFor("members", "add"));
     const appArg = args.flags.get("app");
     if (!appArg) {
         fail("usage: homespun members add --app <idOrSlug> --email <email> [--role member]", "invalid_args");
@@ -104,7 +83,7 @@ async function runAdd(args) {
 // list
 // ---------------------------------------------------------------------------
 async function runList(args) {
-    assertKnownFlags(args, ["app", "url", "api-key"], ["help"], "homespun members list");
+    assertKnownFlags(args, ...specFor("members", "list"));
     const appArg = args.flags.get("app");
     if (!appArg) {
         fail("usage: homespun members list --app <idOrSlug>", "invalid_args");
@@ -119,10 +98,45 @@ async function runList(args) {
     }
 }
 // ---------------------------------------------------------------------------
+// set-role
+// ---------------------------------------------------------------------------
+async function runSetRole(args) {
+    assertKnownFlags(args, ...specFor("members", "set-role"));
+    const appArg = args.flags.get("app");
+    if (!appArg) {
+        fail("usage: homespun members set-role --app <idOrSlug> --human <humanId> (--custom-role <name> | --clear-role)", "invalid_args");
+    }
+    const humanId = args.flags.get("human");
+    if (!humanId) {
+        fail("--human is required", "invalid_args");
+    }
+    // Clearing a role is a real instruction, so it gets its own explicit flag
+    // rather than being spelled as an omitted or empty --custom-role: an omitted
+    // value must never silently wipe someone's role.
+    const customRole = args.flags.get("custom-role");
+    const clear = args.bools.has("clear-role");
+    if (clear && customRole !== undefined) {
+        fail("--custom-role and --clear-role are mutually exclusive", "invalid_args");
+    }
+    if (!clear && customRole === undefined) {
+        fail("one of --custom-role <name> or --clear-role is required", "invalid_args");
+    }
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    try {
+        printJson(await client.setAppMemberRole(appId, humanId, {
+            customRole: clear ? null : customRole,
+        }));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
 // remove
 // ---------------------------------------------------------------------------
 async function runRemove(args) {
-    assertKnownFlags(args, ["app", "human", "url", "api-key"], ["help"], "homespun members remove");
+    assertKnownFlags(args, ...specFor("members", "remove"));
     const appArg = args.flags.get("app");
     if (!appArg) {
         fail("usage: homespun members remove --app <idOrSlug> --human <humanId>", "invalid_args");
@@ -141,3 +155,21 @@ async function runRemove(args) {
         failFromError(e);
     }
 }
+// ---------------------------------------------------------------------------
+// roles
+// ---------------------------------------------------------------------------
+async function runRoles(args) {
+    assertKnownFlags(args, ...specFor("members", "roles"));
+    const appArg = args.flags.get("app");
+    if (!appArg) {
+        fail("usage: homespun members roles --app <idOrSlug>", "invalid_args");
+    }
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    try {
+        printJson(await client.listAppRoles(appId));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}

package/dist/commands/register.js

@@ -20,59 +20,12 @@
 import { hostname } from "node:os";
 import { registerAgent, HomespunApiError } from "@homespunapps/core";
 import { assertKnownFlags } from "../argv.js";
+import { specFor } from "../help-catalog.js";
 import { DEFAULT_RELAY_URL } from "../config.js";
 import { runDeviceFlow } from "../device-flow.js";
 import { printJson, fail, failUpgradeRequired } from "../output.js";
 import { isValidProfileName, DEFAULT_PROFILE_NAME, readStore, resolveProfile, upsertProfile, } from "../store.js";
 import { VERSION } from "../version.js";
-const KNOWN_FLAGS = ["name", "secret"];
-const KNOWN_BOOLS = ["print-key", "no-device"];
-export const registerHelp = `homespun agent register - register this agent with the relay and save the key locally
-
-Usage:
-  homespun agent register [options]
-
-By default this runs the browser device-authorization flow: it prints a link
-and a short code, you (or the account owner) open the link on any device,
-sign in, and approve - and the agent comes out already linked to that
-account. Older relays without the flow fall back to plain POST /v1/register
-automatically (such agents need a separate 'homespun agent claim' afterwards).
-
-The returned API key (and relay URL) are saved under a named profile in the
-CLI config file - so afterwards every other command works with only HOMESPUN_URL
-set (no HOMESPUN_API_KEY needed).
-
-If --profile is omitted, the registered key goes under the currently-active
-profile (or 'default' for a fresh install). Pass --profile <name> to keep
-multiple environments (dev/staging/prod) side by side; switch between them
-with 'homespun config use <name>' or '--profile <name>' / HOMESPUN_PROFILE.
-
-Options:
-  --name <n>          Agent display name on the relay (shown on the approval
-                      screen). Defaults to cli-<hostname> for the device flow;
-                      the relay defaults it for the direct path.
-  --profile <name>    Local profile name to save under. Defaults to the active
-                      profile, or 'default' on a fresh install. Letters,
-                      digits, _ and -, up to 32 chars.
-  --url <url>         Relay base URL. Falls back to HOMESPUN_URL, then the active
-                      profile, then the hosted Homespun relay. Self-hosters set
-                      this.
-  --secret <s>        Registration secret, sent as a Bearer token. Only needed
-                      when the relay uses REGISTRATION_MODE=secret. Implies the
-                      direct path (no browser approval). Falls back to the
-                      HOMESPUN_REGISTER_SECRET env var.
-  --no-device         Skip the browser approval and register directly
-                      (POST /v1/register). The agent is unowned until claimed.
-  --print-key         Also echo the full api_key in the output. By default the
-                      key is only persisted to the config file, never printed.
-  -h, --help          Show this help.
-
-Output (stdout, JSON):
-  { agent_id, key_prefix, profile, saved_to, registered_via }
-  (+ api_key when --print-key)
-
-The API key is saved to the CLI config file (mode 0600); it is not printed
-unless --print-key is passed.`;
 /**
  * Default agent name for the device flow: the consent screen must name what
  * the human is approving, so an unnamed agent gets "cli-<hostname>" instead
@@ -95,7 +48,7 @@ function apiKeyPrefix(key) {
     return key.startsWith("hs_") ? key.slice(0, 9) : key.slice(0, 8);
 }
 export async function runRegister(args) {
-    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "homespun agent register");
+    assertKnownFlags(args, ...specFor("agent", "register"));
     // Profile selection for the WRITE side: --profile flag → HOMESPUN_PROFILE env
     // → the store's current profile → DEFAULT_PROFILE_NAME ('default') for
     // a fresh install. We deliberately don't fall through to "no profile, use

package/dist/commands/set-key.js

@@ -8,39 +8,9 @@
 // than guessing here and adding a network hop for what's a local config
 // write.
 import { assertKnownFlags } from "../argv.js";
+import { specFor } from "../help-catalog.js";
 import { isValidProfileName, DEFAULT_PROFILE_NAME, readStore, resolveProfile, upsertProfile, } from "../store.js";
 import { printJson, fail } from "../output.js";
-const KNOWN_FLAGS = ["url"];
-const KNOWN_BOOLS = [];
-export const setKeyHelp = `homespun agent set-key <api-key> — save a new API key to the local config
-
-Usage:
-  homespun agent set-key <api-key> [--url <url>] [--profile <name>]
-
-After regenerating an agent's API key in the relay's My-agents UI, run
-this on the agent's machine to land the new key in the CLI config file
-(\${XDG_CONFIG_HOME:-~/.config}/homespun/config.json, mode 0600). Every later
-command then works with no HOMESPUN_API_KEY env var.
-
-The key is saved under the ACTIVE profile (unless --profile picks a different
-one). To add a brand-new profile by hand (e.g. for an out-of-band key from a
-closed-registration relay), use 'homespun config add'.
-
-If you'd rather not touch the config file at all, set the new key as the
-HOMESPUN_API_KEY env var on the agent process — both work.
-
-Options:
-  --url <url>         Also update the saved relay URL on the target profile.
-                      Useful when pointing the agent at a different relay
-                      alongside the key swap.
-  --profile <name>    Target this profile instead of the active one. Created
-                      if it doesn't exist.
-  -h, --help          Show this help.
-
-Output (stdout, JSON):
-  { saved_to, profile, key_prefix }
-
-The key is never echoed back. To verify, run \`homespun key list\` afterwards.`;
 function keyPrefixOf(key) {
     // Match the relay's keyPrefix() display width for "hs_" + 6 hex chars
     // (11 total). Falls back to the first 8 chars for any unrecognised shape.
@@ -49,7 +19,7 @@ function keyPrefixOf(key) {
     return key.slice(0, 8);
 }
 export async function runSetKey(args) {
-    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "homespun agent set-key");
+    assertKnownFlags(args, ...specFor("agent", "set-key"));
     const apiKey = args.positionals[0];
     if (!apiKey) {
         fail("missing api-key — usage: homespun agent set-key <api-key>", "invalid_args");