@homespunapps/cli 1.0.0

package/dist/commands/feedback.js

@@ -0,0 +1,133 @@
+import { assertKnownFlags } from "../argv.js";
+import { makeClient } from "../config.js";
+import { printJson, fail, failFromError } from "../output.js";
+const CREATE_FLAGS = ["type", "message", "app-id"];
+const LIST_FLAGS = ["limit", "before"];
+const NO_BOOLS = [];
+export const feedbackHelp = `homespun feedback — submit / list feedback to the relay operator
+
+Feedback is a one-shot bug report, feature request, or note from YOUR agent
+to whoever runs the relay. Submissions are stored in the relay DB; the
+operator triages out of band.
+
+Usage:
+  homespun feedback <subcommand> [options]
+
+Subcommands:
+  create     Submit one feedback row. Requires --type and --message.
+             Prints { id, type, created_at } — the message is not echoed back.
+
+  list       List YOUR agent's own submissions, newest first. Prints
+             { items: [...], next_before?: <cursor> }. Pass --before <cursor>
+             from a previous page to fetch the next page.
+
+Options for 'create':
+  --type <bug|feature|note>   Feedback category. Required.
+  --message <text|->          Message body. Pass '-' to read from stdin.
+                              1..4000 chars after trim.
+  --app-id <id>               Optional App this feedback relates to;
+                              must be owned by YOUR agent's human.
+
+Options for 'list':
+  --limit <N>                 Page size (default 50, max 100).
+  --before <cursor>           Opaque cursor from a previous page's next_before.
+
+Global:
+  --url <url>                 Relay base URL (overrides HOMESPUN_URL).
+  --api-key <key>             Agent API key (overrides HOMESPUN_API_KEY).
+  -h, --help                  Show this help.
+
+Examples:
+  homespun feedback create --type bug --message "watch hangs on empty app"
+  echo "long-form note..." | homespun feedback create --type note --message -
+  homespun feedback list --limit 20
+
+Output: stdout is machine-readable JSON.`;
+const FEEDBACK_TYPES = ["bug", "feature", "note"];
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+async function runFeedbackCreate(args) {
+    assertKnownFlags(args, CREATE_FLAGS, NO_BOOLS, "homespun feedback create");
+    const type = args.flags.get("type");
+    const rawMessage = args.flags.get("message");
+    const appId = args.flags.get("app-id");
+    if (type === undefined) {
+        fail("'homespun feedback create' requires --type <bug|feature|note>", "invalid_args");
+    }
+    if (!FEEDBACK_TYPES.includes(type)) {
+        fail(`unknown --type '${type}' — expected one of: ${FEEDBACK_TYPES.join(", ")}`, "invalid_args");
+    }
+    if (rawMessage === undefined) {
+        fail("'homespun feedback create' requires --message <text|-> (use '-' to read from stdin)", "invalid_args");
+    }
+    let message;
+    if (rawMessage === "-") {
+        if (process.stdin.isTTY) {
+            fail("'homespun feedback create --message -' expects feedback on stdin, but stdin is a TTY", "invalid_args");
+        }
+        message = await readStdin();
+    }
+    else {
+        message = rawMessage;
+    }
+    if (message.trim().length === 0) {
+        fail("feedback message must not be empty or whitespace-only", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        const res = await client.submitFeedback({
+            type: type,
+            message,
+            ...(appId !== undefined ? { appId } : {}),
+        });
+        printJson(res);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+async function runFeedbackList(args) {
+    assertKnownFlags(args, LIST_FLAGS, NO_BOOLS, "homespun feedback list");
+    const limitRaw = args.flags.get("limit");
+    const before = args.flags.get("before");
+    let limit;
+    if (limitRaw !== undefined) {
+        const n = Number(limitRaw);
+        if (!Number.isInteger(n) || n <= 0) {
+            fail(`--limit must be a positive integer, got '${limitRaw}'`, "invalid_args");
+        }
+        limit = n;
+    }
+    const client = makeClient(args);
+    try {
+        const page = await client.listFeedback({
+            ...(limit !== undefined ? { limit } : {}),
+            ...(before !== undefined ? { before } : {}),
+        });
+        printJson(page);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+export async function runFeedback(args) {
+    const sub = args.positionals[0];
+    switch (sub) {
+        case "create":
+            await runFeedbackCreate(args);
+            break;
+        case "list":
+            await runFeedbackList(args);
+            break;
+        case undefined:
+            fail("missing subcommand — usage: homespun feedback <create|list> (run 'homespun feedback --help')", "invalid_args");
+            break;
+        default:
+            fail(`unknown feedback subcommand '${sub}' — expected create|list (run 'homespun feedback --help')`, "invalid_args");
+    }
+}

package/dist/commands/key.js

@@ -0,0 +1,82 @@
+// `homespun key` — inspect or revoke the calling agent's API key.
+//
+// Flat command namespace: `key` is one top-level noun that branches on a
+// positional verb (list / revoke). The relay scopes /v1/keys to the
+// 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 { 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");
+    const client = makeClient(args);
+    try {
+        const info = await client.listKeys();
+        printJson(info);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+async function runKeyRevoke(args) {
+    assertKnownFlags(args, NO_FLAGS, REVOKE_BOOLS, "homespun 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");
+    }
+    const client = makeClient(args);
+    try {
+        // The relay only permits revoking the caller's own key. If a positional id
+        // is given, pass it through and let the relay 403 a wrong one; otherwise
+        // resolve the caller's own id from GET /v1/keys.
+        const id = args.positionals[1] ?? (await client.listKeys()).agent_id;
+        await client.revokeKey(id);
+        printJson({ revoked: true, agent_id: id });
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+export async function runKey(args) {
+    const sub = args.positionals[0];
+    switch (sub) {
+        case "list":
+            await runKeyList(args);
+            break;
+        case "revoke":
+            await runKeyRevoke(args);
+            break;
+        case undefined:
+            fail("missing verb — usage: homespun key <list|revoke> (run 'homespun key --help')", "invalid_args");
+            break;
+        default:
+            fail(`unknown key verb '${sub}' — expected list|revoke (run 'homespun key --help')`, "invalid_args");
+    }
+}

package/dist/commands/logout.js

@@ -0,0 +1,59 @@
+// `homespun agent logout` — clear one (or all) saved profile(s).
+import { assertKnownFlags } from "../argv.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");
+    if (args.bools.has("all")) {
+        // Nuke everything — file gone, both legacy and new shape covered.
+        const path = clearStore();
+        printJson({ cleared: true, profile: null, path });
+        return;
+    }
+    const store = readStore();
+    const selector = args.flags.get("profile") ?? process.env.HOMESPUN_PROFILE;
+    let target;
+    try {
+        target = resolveProfile(store, selector);
+    }
+    catch (e) {
+        fail(e instanceof Error ? e.message : String(e), "config_error");
+    }
+    // Nothing to clear: empty store or legacy file with no migrate yet.
+    if (!target) {
+        // If there's literally nothing saved, mirror the legacy idempotent
+        // behaviour — delete the file (no-op if absent) and report cleared.
+        const path = clearStore();
+        printJson({ cleared: true, profile: null, path });
+        return;
+    }
+    const { path } = removeProfile(target.name);
+    printJson({ cleared: true, profile: target.name, path });
+}

package/dist/commands/members.js

@@ -0,0 +1,143 @@
+// `homespun members` — app membership management for a v2 app (auth spec §6,
+// spec-cli §2.5): invite/attach a member by email, list the app's
+// owner + members, and remove one. Every verb targets an app via a required
+// `--app <idOrSlug>` flag, resolved the same way `homespun apps`/`homespun data` do
+// (resolveAppId).
+//
+// 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 any of these verbs works for an app the calling agent's owning
+// human owns.
+//
+// (The v1 Template marketplace's human-login-only install/uninstall route
+// — which was never a sibling verb here, since it isn't agent-key
+// authorizable — was removed in PR 2c-1 along with the rest of the v1
+// Template subsystem.)
+import { assertKnownFlags } from "../argv.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");
+        return;
+    }
+    if (verb === undefined) {
+        fail("missing verb — homespun members <add|list|remove>", "invalid_args");
+    }
+    const sub = {
+        positionals: args.positionals.slice(1),
+        flags: args.flags,
+        bools: args.bools,
+        ...(args.danglingValueFlags !== undefined
+            ? { danglingValueFlags: args.danglingValueFlags }
+            : {}),
+    };
+    switch (verb) {
+        case "add":
+            return runAdd(sub);
+        case "list":
+            return runList(sub);
+        case "remove":
+            return runRemove(sub);
+        default:
+            fail(`unknown verb '${verb}' — homespun members <add|list|remove>`, "invalid_args");
+    }
+}
+// ---------------------------------------------------------------------------
+// add
+// ---------------------------------------------------------------------------
+async function runAdd(args) {
+    assertKnownFlags(args, ["app", "email", "role", "url", "api-key"], ["help"], "homespun members add");
+    const appArg = args.flags.get("app");
+    if (!appArg) {
+        fail("usage: homespun members add --app <idOrSlug> --email <email> [--role member]", "invalid_args");
+    }
+    const email = args.flags.get("email");
+    if (!email) {
+        fail("--email is required", "invalid_args");
+    }
+    const role = args.flags.get("role");
+    if (role !== undefined && role !== "member") {
+        fail('--role must be "member"', "invalid_args");
+    }
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    try {
+        printJson(await client.addAppMember(appId, {
+            email: email,
+            ...(role !== undefined ? { role: role } : {}),
+        }));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// list
+// ---------------------------------------------------------------------------
+async function runList(args) {
+    assertKnownFlags(args, ["app", "url", "api-key"], ["help"], "homespun members list");
+    const appArg = args.flags.get("app");
+    if (!appArg) {
+        fail("usage: homespun members list --app <idOrSlug>", "invalid_args");
+    }
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    try {
+        printJson(await client.listAppMembers(appId));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// remove
+// ---------------------------------------------------------------------------
+async function runRemove(args) {
+    assertKnownFlags(args, ["app", "human", "url", "api-key"], ["help"], "homespun members remove");
+    const appArg = args.flags.get("app");
+    if (!appArg) {
+        fail("usage: homespun members remove --app <idOrSlug> --human <humanId>", "invalid_args");
+    }
+    const humanId = args.flags.get("human");
+    if (!humanId) {
+        fail("--human is required", "invalid_args");
+    }
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    try {
+        await client.removeAppMember(appId, humanId);
+        printJson({ removed: true, app_id: appId, human_id: humanId });
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}

package/dist/commands/register.js

@@ -0,0 +1,131 @@
+// `homespun agent register` — self-provision an agent API key from the relay.
+//
+// This is the one command that needs no API key: it is the call that obtains
+// one. If the relay runs REGISTRATION_MODE=secret, pass the shared
+// registration secret via --secret or HOMESPUN_REGISTER_SECRET. On success the key
+// (and relay URL) are persisted under a named profile in the CLI config file,
+// so every later command works with only HOMESPUN_URL (or nothing) set.
+import { registerAgent, HomespunApiError } from "@homespunapps/core";
+import { assertKnownFlags } from "../argv.js";
+import { DEFAULT_RELAY_URL } from "../config.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"];
+export const registerHelp = `homespun agent register — register this agent with the relay and save the key locally
+
+Usage:
+  homespun agent register [options]
+
+Calls POST /v1/register, then saves the returned API key (and relay URL) 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. The relay defaults it
+                      if omitted.
+  --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. Falls back
+                      to the HOMESPUN_REGISTER_SECRET env var.
+  --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 }   (+ 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.`;
+export async function runRegister(args) {
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "homespun 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
+    // a fresh name" — the agent needs to end up somewhere callable, and
+    // 'default' is a stable, predictable home.
+    const profileFlag = args.flags.get("profile") ?? process.env.HOMESPUN_PROFILE;
+    const store = readStore();
+    const profileName = profileFlag !== undefined && profileFlag !== ""
+        ? profileFlag
+        : (store.currentProfile ?? DEFAULT_PROFILE_NAME);
+    if (!isValidProfileName(profileName)) {
+        fail(`invalid profile name '${profileName}' — letters, digits, _ and -, up to 32 chars`, "invalid_args");
+    }
+    // URL precedence for the relay we're registering against:
+    //   --url flag > HOMESPUN_URL env > target-profile's existing url > default.
+    // The "target profile's url" path means re-running `homespun agent register
+    // --profile dev` against a profile that already exists keeps hitting the
+    // same dev relay without retyping --url.
+    let activeUrl;
+    try {
+        const active = resolveProfile(store, profileFlag);
+        activeUrl = active?.profile.url;
+    }
+    catch {
+        // Selector didn't resolve — fine on register: we're about to create it.
+        activeUrl = undefined;
+    }
+    const url = args.flags.get("url") ??
+        process.env.HOMESPUN_URL ??
+        activeUrl ??
+        DEFAULT_RELAY_URL;
+    const name = args.flags.get("name");
+    const secret = args.flags.get("secret") ??
+        process.env.HOMESPUN_REGISTER_SECRET ??
+        undefined;
+    let result;
+    try {
+        result = await registerAgent({
+            url: url.replace(/\/$/, ""),
+            ...(name !== undefined ? { name } : {}),
+            ...(secret !== undefined && secret !== "" ? { secret } : {}),
+            cliVersion: VERSION,
+        });
+    }
+    catch (e) {
+        if (e instanceof HomespunApiError) {
+            // 426 cli_upgrade_required goes through the shared upgrade-message
+            // path (stderr block + exit 75) so the SKILL.md's instructions to the
+            // agent's harness fire on `homespun agent register` too.
+            if (e.status === 426 && e.code === "cli_upgrade_required") {
+                failUpgradeRequired(e);
+            }
+            if (e.status === 429) {
+                fail("registration rate limit exceeded — try again later", "rate_limited", undefined, { hint: e.hint, retryable: e.retryable, docs_url: e.docsUrl });
+            }
+            fail(e.message, e.code, e.details, {
+                hint: e.hint,
+                retryable: e.retryable,
+                docs_url: e.docsUrl,
+            });
+        }
+        fail(e instanceof Error ? e.message : String(e), "internal");
+    }
+    // Save under the chosen profile. We pass setCurrent=true: the user just
+    // registered against this relay, so the only sensible follow-up is to
+    // start using it. The previous behaviour (one global URL+key) is exactly
+    // the single-profile case of this.
+    const savedTo = upsertProfile(profileName, { url: url.replace(/\/$/, ""), apiKey: result.api_key }, true);
+    const out = {
+        agent_id: result.agent_id,
+        key_prefix: result.key_prefix,
+        profile: profileName,
+        saved_to: savedTo,
+    };
+    if (args.bools.has("print-key")) {
+        out["api_key"] = result.api_key;
+    }
+    printJson(out);
+}

package/dist/commands/set-key.js

@@ -0,0 +1,92 @@
+// `homespun agent set-key <key>` — write a fresh API key into the CLI config
+// file. The companion to the human-side rotation flow on /my-agents: after
+// the human regenerates a key in the browser, this command lands it on
+// the agent's machine without making them hand-edit ~/.config/homespun/config.json.
+//
+// No relay round-trip: we trust the human-supplied key. The relay will
+// reject it on the next call if it's wrong (401 invalid_api_key) — better
+// than guessing here and adding a network hop for what's a local config
+// write.
+import { assertKnownFlags } from "../argv.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.
+    if (key.startsWith("hs_") && key.length >= 9)
+        return key.slice(0, 9);
+    return key.slice(0, 8);
+}
+export async function runSetKey(args) {
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "homespun agent set-key");
+    const apiKey = args.positionals[0];
+    if (!apiKey) {
+        fail("missing api-key — usage: homespun agent set-key <api-key>", "invalid_args");
+    }
+    if (typeof apiKey !== "string" || apiKey.trim().length === 0) {
+        fail("api-key must be a non-empty string", "invalid_args");
+    }
+    // Best-effort shape check. The relay generates `hs_<32 hex>`; we don't
+    // reject other shapes outright (a future format change shouldn't strand
+    // older CLIs), but we warn on something obviously wrong like leading
+    // whitespace.
+    const trimmed = apiKey.trim();
+    if (trimmed !== apiKey) {
+        fail("api-key has surrounding whitespace — copy it without leading/trailing spaces", "invalid_args");
+    }
+    // Profile selection mirrors `homespun agent register`: --profile flag →
+    // HOMESPUN_PROFILE env → store's current_profile → 'default'.
+    const profileFlag = args.flags.get("profile") ?? process.env.HOMESPUN_PROFILE;
+    const store = readStore();
+    const profileName = profileFlag !== undefined && profileFlag !== ""
+        ? profileFlag
+        : (store.currentProfile ?? DEFAULT_PROFILE_NAME);
+    if (!isValidProfileName(profileName)) {
+        fail(`invalid profile name '${profileName}' — letters, digits, _ and -, up to 32 chars`, "invalid_args");
+    }
+    const urlFlag = args.flags.get("url");
+    const patch = { apiKey };
+    if (urlFlag !== undefined)
+        patch.url = urlFlag;
+    const saved = upsertProfile(profileName, patch);
+    // Re-resolve so we report the prefix from the persisted value, not the
+    // argument — defensive against future write-side normalisation.
+    const after = readStore();
+    const reread = resolveProfile(after, profileName);
+    printJson({
+        saved_to: saved,
+        profile: profileName,
+        key_prefix: keyPrefixOf(reread?.profile.apiKey ?? apiKey),
+    });
+}