@homespunapps/cli 1.0.1 → 1.4.3

package/dist/argv.js

@@ -18,6 +18,43 @@ export class ArgvError extends Error {
             this.hint = hint;
     }
 }
+// Flags that never take a value. `json` is kept here purely for forward-compat
+// (JSON is currently the only output mode): accepting `--json` as a no-op bool
+// means a future `--text`/`--json` toggle won't break existing invocations. It
+// is intentionally undocumented in --help.
+//
+// `version` is deliberately NOT here: the top-level `-v` / `--version` is
+// handled from rawArgv[0] before parseArgs runs, so it never needs to be a
+// boolean flag, and keeping it out leaves room for a future noun-level
+// `--version <n>` value flag without a collision.
+//
+// Exported (and colocated with the parser rather than the bin entry) so tests
+// exercise the REAL parse-time set. A per-test copy of this list is how
+// `deploy --check` shipped un-parsed and ran a real deploy (#827): the flag
+// was in the command's KNOWN_BOOLS and the test's copy, but not here, so
+// parseArgs treated it as a value flag and `bools.has("check")` stayed false.
+export const BOOLEAN_FLAGS = new Set([
+    "json",
+    "once",
+    "help",
+    "print-key",
+    "yes",
+    "plain",
+    // `homespun deploy --force` / `homespun apps ... --force`: override a compat gate.
+    "force",
+    // `homespun deploy --check`: validate-only dry run, persists nothing (#827).
+    "check",
+    // `homespun agent register --no-device`: skip the browser device-authorization
+    // flow and register directly (unowned agent), the pre-device-flow behavior.
+    "no-device",
+    // `homespun data ... import --emit-effects`: opt a silent bulk import back into
+    // firing notify/webhooks (import defaults to silent).
+    "emit-effects",
+    // `homespun agent logout --all`: wipe every saved profile, not just the active one.
+    "all",
+    // `homespun members set-role --clear-role`: drop a custom role back to plain member.
+    "clear-role",
+]);
 /**
  * Parse argv tokens. `booleanFlags` lists flags that never consume a value
  * (e.g. --json, --once, --help); everything else with a `--name` form
@@ -97,10 +134,19 @@ const GLOBAL_BOOLS = ["help", "json"];
  * `args`. The thrown ArgvError carries a hint pointing at the verb's own
  * --help, so a user fixing a typo lands on the canonical list of flags.
  *
- * Why per-command and not at parse time: the parser is single-pass and
- * generic on purpose — adding a new flag to one verb should not require a
- * shared registry. Keeping the allow-list co-located with the runner that
- * consumes it means the two cannot drift.
+ * Why per-command and not at parse time: the parser stays single-pass and
+ * generic, and each runner asserts only its own surface.
+ *
+ * This comment used to argue the allow-list must be co-located with the runner
+ * so a new flag would not require a shared registry. That reasoning assumed
+ * two consumers (the parser and the runner). There are now four: the runner,
+ * `--help`, the published CLI reference on docs.homespun.dev, and this check.
+ * Co-location bought nothing against the other three, and in practice the
+ * inline lists, the help text, and the docs page had already drifted apart.
+ * So the allow-list moved into help-catalog.ts, which every consumer reads via
+ * specFor(). A new flag is still a one-line edit, it just lands in the table
+ * instead of the runner, and the drift it used to cause is now impossible
+ * rather than merely discouraged.
  *
  * Also resolves the parser's `danglingValueFlags`: an unknown name there
  * is reported alongside other unknowns ("unknown flag(s): --bogus"); a
@@ -128,6 +174,25 @@ export function assertKnownFlags(args, knownFlags, knownBools, helpCommand) {
     if (unknown.length > 0) {
         throw new ArgvError(`unknown flag(s): ${unknown.join(", ")}`, `run \`${helpCommand} --help\` for the supported flags`);
     }
+    // Defense against parse-time drift (#827): a flag the command declares
+    // boolean must never arrive as a value flag. That happens only when the
+    // name is missing from the parse-time BOOLEAN_FLAGS set, so parseArgs
+    // consumed a value for it (`--check ./dir`, `--check=x`) or recorded it
+    // as dangling (trailing `--check`). Before this check, that mismatch
+    // passed silently, `bools.has()` stayed false, and `deploy --check` ran
+    // a REAL deploy. Fail loudly instead: in tests and dev this surfaces the
+    // missing BOOLEAN_FLAGS entry immediately, and no invocation can fall
+    // through to the non-boolean code path.
+    for (const k of args.flags.keys()) {
+        if (boolSet.has(k) && !flagSet.has(k)) {
+            throw new ArgvError(`--${k} takes no value`);
+        }
+    }
+    for (const k of dangling) {
+        if (boolSet.has(k) && !flagSet.has(k)) {
+            throw new ArgvError(`--${k} takes no value`);
+        }
+    }
     // No unknowns — but a known value-flag may still have been left without
     // a value. Handle the first such case with the pre-existing message
     // shape ("--name requires a value"). Reporting only the first keeps the

package/dist/commands/agent.js

@@ -12,26 +12,6 @@ import { runLogout } from "./logout.js";
 import { runClaim } from "./claim.js";
 import { runSetKey } from "./set-key.js";
 import { fail } from "../output.js";
-export const agentHelp = `homespun agent — manage this agent's identity on the relay
-
-Usage:
-  homespun agent <verb> [options]
-
-Verbs:
-  register          Provision an agent API key (POST /v1/register) and save it
-                    to the CLI config file. Run this once before other commands.
-  claim <code>      Bind this agent to a human via a one-shot claim code the
-                    human generated in their Settings UI (POST /v1/agents/claim).
-                    One-way; no unclaim in v1.
-  set-key <key>     Save a new API key into the CLI config file. Used after
-                    regenerating the agent's key in the relay's My-agents UI:
-                    the human pastes the new key here so subsequent commands
-                    authenticate as the same agent.
-  logout            Clear the locally-saved relay URL + API key. Does NOT
-                    revoke the key on the relay — use 'homespun key revoke' for
-                    that.
-
-Run \`homespun agent <verb> --help\` for verb-specific options.`;
 export async function runAgent(args) {
     // Strip the first positional (the verb) so each verb runner sees its
     // own arguments at positionals[0..n].

package/dist/commands/apps.js

@@ -14,40 +14,18 @@
 // to reclaim verbatim.
 import { HomespunApiError, appWsUrlFromAppUrl, openAppStream, } from "@homespunapps/core";
 import { assertKnownFlags } from "../argv.js";
+import { nounSpec, renderNounHelp, specFor } from "../help-catalog.js";
 import { makeClient, resolveConfig } from "../config.js";
 import { fail, failFromError, printJson, printJsonLine } from "../output.js";
 import { resolveAppId } from "../resolve-app.js";
-export const appsHelp = `homespun apps — app lifecycle management
-
-Usage:
-  homespun apps list   [--status active|dormant|archived|all] [--limit] [--cursor] [--slug <slug>]
-  homespun apps show   <app>
-  homespun apps update <app> --visibility <private|link|public>
-  homespun apps delete <app> [--yes]
-  homespun apps wake   <app>
-  homespun apps watch  <app> [--since <cursor>] [--collection <name[,name2,...]>]
-                   [--once] [--timeout <secs>]
-
-<app> accepts either the app_id or its slug (resolved via GET /v1/apps?slug=
-when it doesn't look like a cuid).
-
-watch streams the app's change feed as JSON-lines on stdout — one compact
-SerializedFeedEntry object per line, identical whether served over the live
-WebSocket (primary) or the long-poll fallback (used automatically when the
-WS upgrade fails, e.g. self-host mode has no WS support yet, or a locked-down
-network blocks outbound WS). A dormancy transition mid-watch emits a single
-{"type":"_dormant"} line and exits 0.
-
-Output (JSON; JSON-lines for watch). Errors on stderr:
-{"error":{"code","message"}} with non-zero exit.`;
 export async function runApps(args) {
     const verb = args.positionals[0];
     if ((verb === undefined || verb === "help") && args.bools.has("help")) {
-        process.stdout.write(appsHelp + "\n");
+        process.stdout.write(renderNounHelp(nounSpec("apps")) + "\n");
         return;
     }
     if (verb === undefined) {
-        fail("missing verb — homespun apps <list|show|update|delete|wake|watch>", "invalid_args");
+        fail("missing verb: homespun apps <list|show|update|share-link|delete|wake|watch>", "invalid_args");
     }
     const sub = {
         positionals: args.positionals.slice(1),
@@ -64,6 +42,8 @@ export async function runApps(args) {
             return runShow(sub);
         case "update":
             return runUpdate(sub);
+        case "share-link":
+            return runShareLink(sub);
         case "delete":
             return runDelete(sub);
         case "wake":
@@ -71,14 +51,14 @@ export async function runApps(args) {
         case "watch":
             return runWatch(sub);
         default:
-            fail(`unknown verb '${verb}' — homespun apps <list|show|update|delete|wake|watch>`, "invalid_args");
+            fail(`unknown verb '${verb}': homespun apps <list|show|update|share-link|delete|wake|watch>`, "invalid_args");
     }
 }
 // ---------------------------------------------------------------------------
 // list
 // ---------------------------------------------------------------------------
 async function runList(args) {
-    assertKnownFlags(args, ["status", "limit", "cursor", "slug", "url", "api-key"], ["help"], "homespun apps list");
+    assertKnownFlags(args, ...specFor("apps", "list"));
     const status = args.flags.get("status");
     if (status !== undefined &&
         !["active", "dormant", "archived", "all"].includes(status)) {
@@ -107,7 +87,7 @@ async function runList(args) {
 // show
 // ---------------------------------------------------------------------------
 async function runShow(args) {
-    assertKnownFlags(args, ["url", "api-key"], ["help"], "homespun apps show");
+    assertKnownFlags(args, ...specFor("apps", "show"));
     const appArg = args.positionals[0];
     if (!appArg)
         fail("usage: homespun apps show <app>", "invalid_args");
@@ -124,22 +104,59 @@ async function runShow(args) {
 // update
 // ---------------------------------------------------------------------------
 async function runUpdate(args) {
-    assertKnownFlags(args, ["visibility", "url", "api-key"], ["help"], "homespun apps update");
+    assertKnownFlags(args, ...specFor("apps", "update"));
     const appArg = args.positionals[0];
     if (!appArg) {
-        fail("usage: homespun apps update <app> --visibility <private|link|public>", "invalid_args");
+        fail("usage: homespun apps update <app> [--visibility <private|link|public>] [--timezone <IANA zone>]", "invalid_args");
     }
     const visibility = args.flags.get("visibility");
-    if (visibility === undefined) {
-        fail("--visibility is required", "invalid_args");
+    const timezone = args.flags.get("timezone");
+    if (visibility === undefined && timezone === undefined) {
+        fail("nothing to update; pass --visibility and/or --timezone", "invalid_args");
     }
-    if (!["private", "link", "public"].includes(visibility)) {
+    if (visibility !== undefined &&
+        !["private", "link", "public"].includes(visibility)) {
         fail("--visibility must be private|link|public", "invalid_args");
     }
+    if (timezone !== undefined && timezone.trim() === "") {
+        fail("--timezone must be an IANA zone name, e.g. Europe/Berlin", "invalid_args");
+    }
+    const client = makeClient(args);
+    const id = await resolveAppId(client, appArg);
+    try {
+        printJson(await client.updateApp(id, {
+            ...(visibility !== undefined
+                ? { visibility: visibility }
+                : {}),
+            ...(timezone !== undefined ? { timezone } : {}),
+        }));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// share-link (rotate)
+// ---------------------------------------------------------------------------
+// `homespun apps share-link rotate <app>` rotates a link app's share token.
+// Prints the new { share_url } (its #k= fragment carries the token, shown once).
+// Rotating instantly revokes the previous share URL. Also generates a link for a
+// link app that has none yet. Only `rotate` is supported (rotate-only, no
+// delete): revoking a link IS rotating it.
+async function runShareLink(args) {
+    const action = args.positionals[0];
+    if (action !== "rotate") {
+        fail("usage: homespun apps share-link rotate <app>", "invalid_args");
+    }
+    assertKnownFlags(args, ...specFor("apps", "share-link"));
+    const appArg = args.positionals[1];
+    if (!appArg) {
+        fail("usage: homespun apps share-link rotate <app>", "invalid_args");
+    }
     const client = makeClient(args);
     const id = await resolveAppId(client, appArg);
     try {
-        printJson(await client.updateApp(id, visibility));
+        printJson(await client.rotateShareLink(id));
     }
     catch (e) {
         failFromError(e);
@@ -149,7 +166,7 @@ async function runUpdate(args) {
 // delete
 // ---------------------------------------------------------------------------
 async function runDelete(args) {
-    assertKnownFlags(args, ["url", "api-key"], ["yes", "help"], "homespun apps delete");
+    assertKnownFlags(args, ...specFor("apps", "delete"));
     const appArg = args.positionals[0];
     if (!appArg)
         fail("usage: homespun apps delete <app> [--yes]", "invalid_args");
@@ -170,7 +187,7 @@ async function runDelete(args) {
 // wake
 // ---------------------------------------------------------------------------
 async function runWake(args) {
-    assertKnownFlags(args, ["url", "api-key"], ["help"], "homespun apps wake");
+    assertKnownFlags(args, ...specFor("apps", "wake"));
     const appArg = args.positionals[0];
     if (!appArg)
         fail("usage: homespun apps wake <app>", "invalid_args");
@@ -221,7 +238,7 @@ export function isDormantConflict(err) {
         err.message === "app is dormant");
 }
 async function runWatch(args) {
-    assertKnownFlags(args, ["since", "collection", "timeout", "url", "api-key"], ["once", "help"], "homespun apps watch");
+    assertKnownFlags(args, ...specFor("apps", "watch"));
     const appArg = args.positionals[0];
     if (!appArg)
         fail("usage: homespun apps watch <app>", "invalid_args");

package/dist/commands/attachment-delete.js

@@ -1,27 +1,10 @@
 // `homespun attachment delete <attachment-id>` — soft-delete a attachment.
 import { assertKnownFlags } from "../argv.js";
+import { specFor } from "../help-catalog.js";
 import { makeClient } from "../config.js";
 import { fail, failFromError, printJson } from "../output.js";
-const KNOWN_FLAGS = [];
-const KNOWN_BOOLS = [];
-export const blobDeleteHelp = `homespun attachment delete — soft-delete a attachment
-
-Usage:
-  homespun attachment delete <attachment-id> [options]
-
-Marks the attachment as deleted (DELETE /v1/attachments/:id). Idempotent: deleting an
-already-deleted attachment still returns success. Tokens minted against this attachment
-become unusable.
-
-Options:
-  --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, JSON):
-  { attachment_id, deleted: true }`;
 export async function runBlobDelete(args) {
-    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "homespun attachment delete");
+    assertKnownFlags(args, ...specFor("attachment", "delete"));
     const attachmentId = args.positionals[0];
     if (!attachmentId) {
         fail("missing <attachment-id> — 'homespun attachment delete <attachment-id>'", "invalid_args");

package/dist/commands/attachment-download.js

@@ -1,31 +1,11 @@
 // `homespun attachment download <attachment-id>` — fetch attachment bytes by id.
 import { writeFileSync } from "node:fs";
 import { assertKnownFlags } from "../argv.js";
+import { specFor } from "../help-catalog.js";
 import { makeClient } from "../config.js";
 import { fail, failFromError, printJson } from "../output.js";
-const KNOWN_FLAGS = ["out"];
-const KNOWN_BOOLS = [];
-export const blobDownloadHelp = `homespun attachment download — fetch a attachment's bytes
-
-Usage:
-  homespun attachment download <attachment-id> [--out <path>] [options]
-
-GETs the attachment bytes. With --out <path> the bytes are written to that file and
-a JSON summary is printed on stdout; without --out the bytes are written to
-stdout verbatim (useful for piping into another tool — but binary on a TTY
-is rarely useful).
-
-Options:
-  --out <path>           Write bytes to <path> instead of stdout.
-  --url <url>            Relay base URL (overrides HOMESPUN_URL).
-  --api-key <key>        Agent API key (overrides HOMESPUN_API_KEY).
-  -h, --help             Show this help.
-
-Output:
-  Without --out: raw bytes to stdout.
-  With --out:    { attachment_id, written: <path>, bytes: <n> } to stdout.`;
 export async function runBlobDownload(args) {
-    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "homespun attachment download");
+    assertKnownFlags(args, ...specFor("attachment", "download"));
     const attachmentId = args.positionals[0];
     if (!attachmentId) {
         fail("missing <attachment-id> — 'homespun attachment download <attachment-id>'", "invalid_args");

package/dist/commands/attachment-list.js

@@ -4,31 +4,11 @@
 // are excluded; tokens are not enumerated here (use 'homespun attachment token list
 // <attachment-id>' for that).
 import { assertKnownFlags } from "../argv.js";
+import { specFor } from "../help-catalog.js";
 import { makeClient } from "../config.js";
 import { fail, printJson, failFromError } from "../output.js";
-const KNOWN_FLAGS = ["cursor", "limit"];
-const KNOWN_BOOLS = [];
-export const blobListHelp = `homespun attachment list — enumerate YOUR agent's attachments
-
-Usage:
-  homespun attachment list [--cursor <token>] [--limit <n>] [options]
-
-Returns the agent's non-deleted attachments (newest first). Paginated via opaque
-cursor: when next_cursor is non-null in the response, pass it back as
---cursor to get the next page.
-
-Options:
-  --cursor <token>       Opaque pagination cursor from a prior response.
-  --limit <n>            Page size (1..100). Defaults to the relay default
-                         (50).
-  --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, JSON):
-  { items: AttachmentRef[], next_cursor: string | null }`;
 export async function runBlobList(args) {
-    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "homespun attachment list");
+    assertKnownFlags(args, ...specFor("attachment", "list"));
     const cursor = args.flags.get("cursor");
     const limitRaw = args.flags.get("limit");
     let limit;

package/dist/commands/attachment-show.js

@@ -1,27 +1,10 @@
 // `homespun attachment show <attachment-id>` — print a attachment's metadata.
 import { assertKnownFlags } from "../argv.js";
+import { specFor } from "../help-catalog.js";
 import { makeClient } from "../config.js";
 import { fail, failFromError, printJson } from "../output.js";
-const KNOWN_FLAGS = [];
-const KNOWN_BOOLS = [];
-export const blobShowHelp = `homespun attachment show — print a attachment's metadata (no bytes)
-
-Usage:
-  homespun attachment show <attachment-id> [options]
-
-Looks up the attachment by id and prints its AttachmentRef metadata — owner, scope,
-mime, size, sha256, etc. Does NOT download the bytes; use 'homespun attachment
-download' for that.
-
-Options:
-  --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, JSON):
-  AttachmentRef`;
 export async function runBlobShow(args) {
-    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "homespun attachment show");
+    assertKnownFlags(args, ...specFor("attachment", "show"));
     const attachmentId = args.positionals[0];
     if (!attachmentId) {
         fail("missing <attachment-id> — 'homespun attachment show <attachment-id>'", "invalid_args");

package/dist/commands/attachment-token.js

@@ -12,51 +12,11 @@
 // positionals[2..]. Mirrors how participant.ts dispatches under `app
 // app participant`.
 import { assertKnownFlags } from "../argv.js";
+import { specFor } from "../help-catalog.js";
 import { makeClient } from "../config.js";
 import { fail, failFromError, printJson } from "../output.js";
-const MINT_FLAGS = ["ttl"];
-const MINT_BOOLS = ["once"];
-const NO_FLAGS = [];
-const NO_BOOLS = [];
-export const blobTokenHelp = `homespun attachment token — manage a attachment's capability URLs
-
-Capability URLs let a participant (or any browser holding the URL) fetch a
-attachment without the agent's API key. Tokens are stored HASHED on the relay; the
-plaintext token is returned only ONCE from 'mint' — save the response before
-delivering the URL.
-
-Usage:
-  homespun attachment token <verb> <args>
-
-Verbs:
-  mint <attachment-id>          Mint a /b/<token> capability URL for one attachment.
-                          Optional: --ttl <seconds> (defaults by scope:
-                          30d app / 24h agent; the caller can only
-                          shorten), --once (token self-deletes on
-                          first successful GET). Returns { token, url,
-                          expires_at, ... } — ONCE.
-
-  revoke <attachment-id> <token-id>
-                          Invalidate one previously-minted token by id.
-                          Idempotent: revoking twice still returns success.
-
-  list <attachment-id>          Enumerate the tokens minted against one attachment,
-                          including revoked rows (for audit). Returns
-                          { attachment_id, items: [...] } where each item carries
-                          { token_id, token_prefix, expires_at, once,
-                          created_at, last_used_at, use_count, revoked_at }.
-                          The token plaintext is NEVER returned.
-
-Options:
-  --ttl <seconds>         (mint) per-token TTL; clamped by scope default.
-  --once                  (mint) token self-deletes on first GET.
-  --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 runBlobTokenMint(args) {
-    assertKnownFlags(args, MINT_FLAGS, MINT_BOOLS, "homespun attachment token mint");
+    assertKnownFlags(args, ...specFor("attachment", "token mint"));
     const attachmentId = args.positionals[1];
     if (!attachmentId) {
         fail("missing <attachment-id> — 'homespun attachment token mint <attachment-id>'", "invalid_args");
@@ -79,7 +39,7 @@ async function runBlobTokenMint(args) {
     }
 }
 async function runBlobTokenRevoke(args) {
-    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "homespun attachment token revoke");
+    assertKnownFlags(args, ...specFor("attachment", "token revoke"));
     const attachmentId = args.positionals[1];
     const tokenId = args.positionals[2];
     if (!attachmentId || !tokenId) {
@@ -95,7 +55,7 @@ async function runBlobTokenRevoke(args) {
     }
 }
 async function runBlobTokenList(args) {
-    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "homespun attachment token list");
+    assertKnownFlags(args, ...specFor("attachment", "token list"));
     const attachmentId = args.positionals[1];
     if (!attachmentId) {
         fail("missing <attachment-id> — 'homespun attachment token list <attachment-id>'", "invalid_args");

package/dist/commands/attachment-upload.js

@@ -2,34 +2,11 @@
 import { readFileSync } from "node:fs";
 import { basename } from "node:path";
 import { assertKnownFlags } from "../argv.js";
+import { specFor } from "../help-catalog.js";
 import { makeClient } from "../config.js";
 import { fail, failFromError, printJson } from "../output.js";
-const KNOWN_FLAGS = ["file", "scope", "app-id", "filename", "mime"];
-const KNOWN_BOOLS = [];
-export const blobUploadHelp = `homespun attachment upload — upload a local file as a attachment
-
-Usage:
-  homespun attachment upload --file <path> [options]
-
-Required:
-  --file <path>          Local file to upload.
-
-Scope (default: agent):
-  --scope <s>            "agent" | "app".
-  --app-id <id>          Required when --scope=app.
-
-Optional:
-  --filename <name>      Display filename (otherwise basename of --file).
-  --mime <type>          Declared Content-Type. The relay sniffs the bytes
-                         regardless — this is advisory.
-  --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, JSON):
-  AttachmentRef — { attachment_id, scope, mime, size, sha256, ... }`;
 export async function runBlobUpload(args) {
-    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "homespun attachment upload");
+    assertKnownFlags(args, ...specFor("attachment", "upload"));
     const filePath = args.flags.get("file");
     if (!filePath) {
         fail("missing --file <path> — 'homespun attachment upload' requires a local file to upload", "invalid_args");

package/dist/commands/attachment.js

@@ -12,54 +12,14 @@
 // Most attachment verbs read their primary positional (the attachment_id) at
 // positionals[0]; we slice off our own verb before delegating so each verb
 // runner doesn't need to know it was reached through `homespun attachment`.
-import { runBlobUpload, blobUploadHelp } from "./attachment-upload.js";
-import { runBlobDownload, blobDownloadHelp } from "./attachment-download.js";
-import { runBlobShow, blobShowHelp } from "./attachment-show.js";
-import { runBlobList, blobListHelp } from "./attachment-list.js";
-import { runBlobDelete, blobDeleteHelp } from "./attachment-delete.js";
-import { runBlobToken, blobTokenHelp } from "./attachment-token.js";
+import { nounSpec, renderNounHelp } from "../help-catalog.js";
+import { runBlobUpload } from "./attachment-upload.js";
+import { runBlobDownload } from "./attachment-download.js";
+import { runBlobShow } from "./attachment-show.js";
+import { runBlobList } from "./attachment-list.js";
+import { runBlobDelete } from "./attachment-delete.js";
+import { runBlobToken } from "./attachment-token.js";
 import { fail } from "../output.js";
-export const blobHelp = `homespun attachment — manage attachments (binary attachments) on the relay
-
-A attachment is a typed binary file (image, PDF, audio, video, ...) the agent has
-uploaded to the relay. Blobs are scoped:
-
-  agent     reusable across the agent's apps (default)
-  app       bound to one App; deleted with it
-
-Pages reference attachments by id (the relay's schema validates the id with
-\`format: homespun-attachment-id\`). For a participant-facing URL that bypasses the
-agent's API key, mint a token with 'homespun attachment token mint'.
-
-Usage:
-  homespun attachment <verb> [options]
-
-Verbs:
-  upload                 Upload a local file. Required: --file. Optional:
-                         --scope, --app-id, --filename, --mime. Prints
-                         { attachment_id, scope, mime, size, sha256, ... }.
-
-  download <attachment-id>     Download a attachment by id. Use --out <path> to write a
-                         file (default: writes to stdout — useful for piping).
-
-  show <attachment-id>         Print a attachment's metadata (HEAD-based — doesn't
-                         download the bytes).
-
-  list                   Enumerate YOUR agent's non-deleted attachments (newest
-                         first). Supports --cursor + --limit for pagination.
-
-  delete <attachment-id>       Soft-delete a attachment. Idempotent.
-
-  token <verb>           Capability URLs for a attachment (mint | revoke | list).
-                         'mint' returns a /b/<token> URL anyone can GET, with
-                         optional --ttl and --once. 'revoke' invalidates one
-                         token. 'list' enumerates a attachment's tokens (without
-                         the token plaintext, which is unrecoverable).
-
-Run \`homespun attachment <verb> --help\` for verb-specific options.
-
-Output: stdout is machine-readable JSON. Errors go to stderr as
-{"error":{"code","message"}} with a non-zero exit.`;
 /**
  * Build a new ParsedArgs with the leading positional (the verb) stripped.
  * The downstream verb runners read their primary positional (the attachment_id)
@@ -89,7 +49,7 @@ export async function runBlob(args) {
     if (verb === "token" &&
         args.bools.has("help") &&
         args.positionals.length === 1) {
-        process.stdout.write(blobTokenHelp + "\n");
+        process.stdout.write(renderNounHelp(nounSpec("attachment")) + "\n");
         return;
     }
     // `homespun attachment list --help` — same pattern (list takes no required positional
@@ -98,7 +58,7 @@ export async function runBlob(args) {
     if (verb === "list" &&
         args.bools.has("help") &&
         args.positionals.length === 1) {
-        process.stdout.write(blobListHelp + "\n");
+        process.stdout.write(renderNounHelp(nounSpec("attachment")) + "\n");
         return;
     }
     const inner = shiftPositionals(args);
@@ -128,6 +88,3 @@ export async function runBlob(args) {
             fail(`unknown attachment verb '${verb}' — expected upload|download|show|list|delete|token (run 'homespun attachment --help')`, "invalid_args");
     }
 }
-// Re-export per-verb helps so tests / docs can import them by canonical name
-// without knowing which file owns each verb.
-export { blobUploadHelp, blobDownloadHelp, blobShowHelp, blobListHelp, blobDeleteHelp, blobTokenHelp, };