@ahood/cli 0.4.2 → 0.5.1

package/README.md

@@ -60,6 +60,8 @@ npm i -g @ahood/cli
 ahood <command>
 ```
 
+**The `-g` flag matters.** `npm i @ahood/cli` (no `-g`) installs into the current directory's `node_modules/` instead, and `ahood` won't be on your `PATH` -- you'll get `ahood: command not found`. If that happens, either re-run with `-g`, or use `npx @ahood/cli@latest <command>` from that directory instead.
+
 Requires Node.js 18 or later.
 
 ## Why ahood
@@ -103,6 +105,15 @@ alice/pdf-tools
   version:     1.4.0
   ...
 
+$ ahood skill read alice/pdf-tools
+---
+name: pdf-tools
+description: Merge, split, and compress PDFs from the command line
+---
+
+# PDF Tools
+...
+
 $ ahood skill add alice/pdf-tools@1.4.0
 Installed alice/pdf-tools@1.4.0 to .claude/skills/alice/pdf-tools
 ```
@@ -154,6 +165,25 @@ ahood skill publish alice/pdf-tools@1.5.1 --path ./pdf-tools --json
 ```
 </details>
 
+<details>
+<summary><strong>Create a private group and share a skill with it</strong></summary>
+
+```
+$ ahood group create "Design Team" --description "Shared skills for the design team"
+Created group Design Team (design-team).
+
+$ ahood group invite-link design-team
+https://ahood.vercel.app/groups/join?token=abc123...
+Expires: 2026-09-14T00:00:00.000Z
+This link (and its token) is shown only this once -- save it now, it cannot be retrieved again.
+
+$ ahood skill share alice/pdf-tools --group design-team
+Shared alice/pdf-tools with design-team.
+```
+
+Sharing is additive -- it doesn't change `alice/pdf-tools`'s own public/private visibility, it just makes it visible to everyone in `design-team` too. On the other side, whoever received the link runs `ahood group join <the link>` to join.
+</details>
+
 ## Commands
 
 <!-- Generated from src/help.ts's COMMANDS_HELP by scripts/sync-readme.mjs --
@@ -177,6 +207,7 @@ ahood skill publish alice/pdf-tools@1.5.1 --path ./pdf-tools --json
 | --- | --- |
 | `ahood skill search <query> [--json] [--limit <n>]` | Search published skills. |
 | `ahood skill view\|show <owner>/<skill> [--json] [--web]` | Show a single skill's details -- tags, license, homepage, repository, dates, and more -- without installing it (alias: ahood skill show). |
+| `ahood skill read <owner>/<skill> [--json]` | Print a skill's full SKILL.md content, without installing it. |
 | `ahood skill versions <owner>/<skill> [--json]` | List a skill's published-version history -- version, changelog, size, and publish date. |
 | `ahood skill list [--json]` | List your own skills, public and private. |
 | `ahood skill add <owner>/<skill>[@version]` | Install a skill into .claude/skills/, pinned in the lockfile. |
@@ -186,11 +217,26 @@ ahood skill publish alice/pdf-tools@1.5.1 --path ./pdf-tools --json
 | `ahood skill unpublish <owner>/<skill>[@version] [--yes]` | Delete a skill from the registry for every consumer, or yank a single version, not just your local install (prompts for confirmation unless --yes is passed). |
 | `ahood skill star <owner>/<skill>` | Star a skill. |
 | `ahood skill unstar <owner>/<skill>` | Remove your star from a skill. |
+| `ahood skill share <owner>/<skill> --group <group>` | Share a skill you own with a group, without changing its public/private visibility. |
+| `ahood skill unshare <owner>/<skill> --group <group>` | Stop sharing a skill you own with a group. |
 | `ahood skill init [name]` | Scaffold a new skill folder with a minimal, valid SKILL.md. |
 | `ahood skill publish <owner>/<skill>@<version> [--path <dir>] [--name <text>] [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--homepage <url>] [--repository <url>] [--json]` | Publish a new version of a skill from a folder containing SKILL.md, creating the skill first if it doesn't already exist. |
+
+### Group
+
+| Command | What it does |
+| --- | --- |
+| `ahood group create <name> [--description <text>]` | Create a private group, becoming its owner. |
+| `ahood group list [--json]` | List groups you own or belong to. |
+| `ahood group members <group> [--json]` | List a group's members and their role (owner-only visible to members). |
+| `ahood group invite-link <group> [--json]` | Create (or regenerate) a shareable invite link for a group you own. |
+| `ahood group join <invite-url-or-token>` | Join a group using an invite link or its raw token. |
+| `ahood group remove-member <group> <username>` | Remove a member from a group you own. |
+| `ahood group leave <group>` | Leave a group you belong to. |
+| `ahood group delete <group> [--yes]` | Permanently delete a group you own (prompts for confirmation unless --yes is passed). |
 <!-- COMMANDS_TABLE_END -->
 
-Run `ahood --help`, `ahood skill --help`, or `ahood <command> --help` (also `ahood help <command>` / `ahood help skill <verb>`) for the same reference — including per-command flags and examples — directly in your terminal. `ahood --version` prints the installed CLI version.
+Run `ahood --help`, `ahood skill --help`, `ahood group --help`, or `ahood <command> --help` (also `ahood help <command>` / `ahood help skill <verb>` / `ahood help group <verb>`) for the same reference — including per-command flags and examples — directly in your terminal. `ahood --version` prints the installed CLI version.
 
 ## Exit codes
 

package/dist/commands/group.js

@@ -0,0 +1,160 @@
+import { apiJson } from "../http.js";
+import { flagValue } from "../flags.js";
+import { confirm } from "../confirm.js";
+import { getApiUrl } from "../config.js";
+const CREATE_USAGE = "Usage: ahood group create <name> [--description <text>]";
+const LIST_USAGE = "Usage: ahood group list [--json]";
+const MEMBERS_USAGE = "Usage: ahood group members <group> [--json]";
+const INVITE_LINK_USAGE = "Usage: ahood group invite-link <group> [--json]";
+const JOIN_USAGE = "Usage: ahood group join <invite-url-or-token>";
+const REMOVE_MEMBER_USAGE = "Usage: ahood group remove-member <group> <username>";
+const LEAVE_USAGE = "Usage: ahood group leave <group>";
+const DELETE_USAGE = "Usage: ahood group delete <group> [--yes]";
+// Creates a group (caller becomes owner). Follows edit.ts's convention of
+// requiring the positional argument first, since --description takes a
+// value and a "find the first non---flag token" scan would misidentify a
+// bare description value (one that doesn't start with "--") as the name if
+// --description happened to come first.
+export async function createGroup(args) {
+    const name = args[0];
+    if (!name || name.startsWith("--"))
+        throw new Error(CREATE_USAGE);
+    const description = flagValue(args, "--description");
+    const body = { name };
+    if (description !== undefined)
+        body.description = description;
+    const created = await apiJson("/api/v1/groups", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    console.log(`Created group ${created.name} (${created.slug}).`);
+}
+// Lists the caller's own groups (owner or member).
+export async function listGroups(args = []) {
+    const jsonOutput = args.includes("--json");
+    const { groups } = await apiJson("/api/v1/groups");
+    if (jsonOutput) {
+        console.log(JSON.stringify(groups));
+        return;
+    }
+    if (groups.length === 0) {
+        console.log("You don't belong to any groups yet. Run `ahood group create <name>` to make one.");
+        return;
+    }
+    for (const g of groups) {
+        console.log(`${g.slug} - ${g.name}${g.description ? `: ${g.description}` : ""}`);
+    }
+}
+// Group detail + members -- 404s (mapped to exit code 5) if the caller
+// isn't a member, same as any other not-found.
+export async function groupMembers(args) {
+    const jsonOutput = args.includes("--json");
+    const slug = args.find((a) => !a.startsWith("--"));
+    if (!slug)
+        throw new Error(MEMBERS_USAGE);
+    const { group, members } = await apiJson(`/api/v1/groups/${encodeURIComponent(slug)}`);
+    if (jsonOutput) {
+        console.log(JSON.stringify({ group, members }));
+        return;
+    }
+    console.log(`${group.slug} - ${group.name}${group.description ? `: ${group.description}` : ""}`);
+    for (const m of members) {
+        console.log(`  ${m.username} (${m.role})`);
+    }
+}
+// Creates/regenerates an invite link (owner-only). The response's `token`
+// is raw and shown only this once server-side -- only its hash is stored,
+// so there is no way to retrieve it again later, hence the warning below.
+// The shareable URL is built from getApiUrl() (not a hardcoded prod host)
+// so it stays correct against a non-default AHOOD_API_URL, same reasoning
+// as view.ts's --web URL.
+export async function inviteLink(args) {
+    const jsonOutput = args.includes("--json");
+    const slug = args.find((a) => !a.startsWith("--"));
+    if (!slug)
+        throw new Error(INVITE_LINK_USAGE);
+    const { token, expiresAt } = await apiJson(`/api/v1/groups/${encodeURIComponent(slug)}/invites`, { method: "POST" });
+    const url = `${getApiUrl()}/groups/join?token=${encodeURIComponent(token)}`;
+    if (jsonOutput) {
+        console.log(JSON.stringify({ token, expiresAt, url }));
+        return;
+    }
+    console.log(url);
+    console.log(`Expires: ${expiresAt}`);
+    console.log("This link (and its token) is shown only this once -- save it now, it cannot be retrieved again.");
+}
+// Accepts either a full join URL (https://ahood.vercel.app/groups/join?token=...)
+// or a bare raw token, for convenience -- whatever a user pastes from
+// `ahood group invite-link` or forwards from someone else. Anything that
+// doesn't parse as a URL, or parses but has no `token` query param, is
+// treated as a raw token verbatim.
+function extractToken(input) {
+    try {
+        const url = new URL(input);
+        const token = url.searchParams.get("token");
+        if (token)
+            return token;
+    }
+    catch {
+        // Not a URL at all -- fall through and treat the whole input as the
+        // raw token.
+    }
+    return input;
+}
+export async function joinGroup(args) {
+    const input = args.find((a) => !a.startsWith("--"));
+    if (!input)
+        throw new Error(JOIN_USAGE);
+    const token = extractToken(input);
+    const { groupSlug, groupName } = await apiJson(`/api/v1/groups/invites/${encodeURIComponent(token)}/accept`, { method: "POST" });
+    console.log(`Joined ${groupName} (${groupSlug}).`);
+}
+// Removes a member (owner-only for someone else; see leaveGroup below for
+// "remove yourself"). No flags today, so plain positional filtering is
+// unambiguous.
+export async function removeMember(args) {
+    const positional = args.filter((a) => !a.startsWith("--"));
+    const [slug, username] = positional;
+    if (!slug || !username)
+        throw new Error(REMOVE_MEMBER_USAGE);
+    await apiJson(`/api/v1/groups/${encodeURIComponent(slug)}/members/${encodeURIComponent(username)}`, { method: "DELETE" });
+    console.log(`Removed ${username} from ${slug}.`);
+}
+// There's no cached username anywhere in credentials.ts (only the bearer
+// token itself is stored) and no endpoint that echoes an identity for a
+// bearer caller directly, so the caller's own username is resolved the
+// same way whoami.ts's profile enrichment does: GET /api/v1/profile.
+async function getOwnUsername() {
+    const profile = await apiJson("/api/v1/profile");
+    return profile.username;
+}
+// "Leave" is just "remove-member" targeting yourself -- the API route
+// handles both cases identically (DELETE .../members/{username} with your
+// own username removes you, same as an owner removing someone else).
+export async function leaveGroup(args) {
+    const slug = args.find((a) => !a.startsWith("--"));
+    if (!slug)
+        throw new Error(LEAVE_USAGE);
+    const username = await getOwnUsername();
+    await apiJson(`/api/v1/groups/${encodeURIComponent(slug)}/members/${encodeURIComponent(username)}`, { method: "DELETE" });
+    console.log(`Left ${slug}.`);
+}
+// Owner-only, deletes the group outright -- mirrors unpublish.ts's
+// confirmation-prompt pattern exactly (--yes bypasses it for scripts/CI,
+// otherwise a typed "yes" is required).
+export async function deleteGroup(args) {
+    const yes = args.includes("--yes");
+    const slug = args.find((a) => !a.startsWith("--"));
+    if (!slug)
+        throw new Error(DELETE_USAGE);
+    const confirmed = yes
+        ? true
+        : await confirm(`This will permanently delete the group "${slug}" for all members. Type "yes" to confirm: `);
+    if (!confirmed) {
+        console.log("Aborted.");
+        return;
+    }
+    await apiJson(`/api/v1/groups/${encodeURIComponent(slug)}`, { method: "DELETE" });
+    console.log(`Deleted group ${slug}.`);
+}

package/dist/commands/read.js

@@ -0,0 +1,32 @@
+import { apiJson } from "../http.js";
+import { parseOwnerSkill } from "../spec.js";
+const USAGE = "Usage: ahood skill read <owner>/<skill> [--json]";
+export async function read(args) {
+    const jsonOutput = args.includes("--json");
+    const spec = args.find((a) => !a.startsWith("--"));
+    if (!spec)
+        throw new Error(USAGE);
+    const { owner, skill } = parseOwnerSkill(spec, USAGE);
+    const detail = await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}`);
+    if (!detail.skill_versions) {
+        throw new Error(`${owner}/${skill} has no published version.`);
+    }
+    // Mirrors view.ts's exact wording/tone for the same warning -- this
+    // command reads straight from the same endpoint/version, so it must not
+    // be silent about handing back a yanked version's content.
+    if (detail.skill_versions.yanked_at) {
+        console.warn(`WARNING: ${detail.owner}/${detail.slug}@${detail.skill_versions.version} has been yanked${detail.skill_versions.yanked_reason ? `: ${detail.skill_versions.yanked_reason}` : "."}`);
+    }
+    const content = detail.skill_versions.skill_md_content;
+    if (!content) {
+        throw new Error(`${owner}/${skill}@${detail.skill_versions.version} has no SKILL.md content available.`);
+    }
+    if (jsonOutput) {
+        console.log(JSON.stringify({ version: detail.skill_versions.version, content }));
+        return;
+    }
+    // Plain mode prints the raw content verbatim -- no formatting/labels/
+    // trailing decoration -- since the whole point is fast/pipeable access to
+    // the exact prompt text (e.g. piping into a file or another tool).
+    console.log(content);
+}

package/dist/commands/share.js

@@ -0,0 +1,41 @@
+import { apiJson } from "../http.js";
+import { flagValue } from "../flags.js";
+import { parseOwnerSkill } from "../spec.js";
+// These are skill-entity verbs (reached as `ahood skill share`/`ahood skill
+// unshare`, registered in SKILL_COMMANDS in index.ts), not group verbs --
+// they mutate a skill's sharing, not a group. Grouped together in one file
+// the same way star.ts groups its own paired verbs (star/unstar).
+const SHARE_USAGE = "Usage: ahood skill share <owner>/<skill> --group <group>";
+const UNSHARE_USAGE = "Usage: ahood skill unshare <owner>/<skill> --group <group>";
+// Owner-of-the-skill-only server-side, and the caller must already be a
+// member of the target group -- both enforced by the API, not re-checked
+// here. Follows edit.ts's convention of requiring the owner/skill spec
+// first (before any flags), since --group takes a value and a "first
+// non---flag token" scan would misidentify the --group value as the spec
+// if --group happened to come first.
+export async function share(args) {
+    const spec = args[0];
+    if (!spec || spec.startsWith("--"))
+        throw new Error(SHARE_USAGE);
+    const { owner, skill } = parseOwnerSkill(spec, SHARE_USAGE);
+    const groupSlug = flagValue(args, "--group");
+    if (!groupSlug)
+        throw new Error(SHARE_USAGE);
+    await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}/share`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ group_slug: groupSlug }),
+    });
+    console.log(`Shared ${owner}/${skill} with ${groupSlug}.`);
+}
+export async function unshare(args) {
+    const spec = args[0];
+    if (!spec || spec.startsWith("--"))
+        throw new Error(UNSHARE_USAGE);
+    const { owner, skill } = parseOwnerSkill(spec, UNSHARE_USAGE);
+    const groupSlug = flagValue(args, "--group");
+    if (!groupSlug)
+        throw new Error(UNSHARE_USAGE);
+    await apiJson(`/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(skill)}/share/${encodeURIComponent(groupSlug)}`, { method: "DELETE" });
+    console.log(`Unshared ${owner}/${skill} from ${groupSlug}.`);
+}

package/dist/help.js

@@ -47,6 +47,15 @@ export const SKILL_COMMANDS_HELP = [
             "--web    Open the skill's page in your browser instead of printing.",
         ],
     },
+    {
+        usage: "ahood skill read <owner>/<skill> [--json]",
+        summary: "Print a skill's full SKILL.md content, without installing it.",
+        desc: "Print a skill's full SKILL.md content (the prompt itself) without installing it via `ahood skill add`. " +
+            "Plain mode prints the raw content verbatim to stdout -- no formatting, no labels -- so it's safe to pipe " +
+            "into a file or another tool.",
+        flags: ["--json    Emit {version, content} as a single line instead of the raw content."],
+        examples: ["ahood skill read alice/pdf-tools", "ahood skill read alice/pdf-tools --json"],
+    },
     {
         usage: "ahood skill versions <owner>/<skill> [--json]",
         summary: "List a skill's published-version history -- version, changelog, size, and publish date.",
@@ -110,6 +119,22 @@ export const SKILL_COMMANDS_HELP = [
         summary: "Remove your star from a skill.",
         desc: "Remove your star from a skill.",
     },
+    {
+        usage: "ahood skill share <owner>/<skill> --group <group>",
+        summary: "Share a skill you own with a group, without changing its public/private visibility.",
+        desc: "Share a skill you own with a group. Sharing is additive -- it doesn't change the skill's own " +
+            "public/private visibility, it just makes it visible to everyone in the group too. You must own the " +
+            "skill and already be a member of the target group.",
+        flags: ["--group <group>   The group's slug (from `ahood group list`)."],
+        examples: ["ahood skill share alice/pdf-tools --group design-team"],
+    },
+    {
+        usage: "ahood skill unshare <owner>/<skill> --group <group>",
+        summary: "Stop sharing a skill you own with a group.",
+        desc: "Stop sharing a skill you own with a group. Does not affect the skill's own visibility.",
+        flags: ["--group <group>   The group's slug."],
+        examples: ["ahood skill unshare alice/pdf-tools --group design-team"],
+    },
     {
         usage: "ahood skill init [name]",
         summary: "Scaffold a new skill folder with a minimal, valid SKILL.md.",
@@ -141,17 +166,89 @@ export const SKILL_COMMANDS_HELP = [
         ],
     },
 ];
+// Every group-entity verb, all reached as `ahood group <verb>` -- mirrors
+// SKILL_COMMANDS_HELP above, just for the "Groups" feature: private groups,
+// shareable invite links, and sharing your own skills with a group without
+// changing their public/private visibility.
+export const GROUP_COMMANDS_HELP = [
+    {
+        usage: "ahood group create <name> [--description <text>]",
+        summary: "Create a private group, becoming its owner.",
+        desc: "Create a private group. You become its owner.",
+        flags: ["--description <text>   Optional short description."],
+        examples: ['ahood group create "Design Team" --description "Shared skills for the design team"'],
+    },
+    {
+        usage: "ahood group list [--json]",
+        summary: "List groups you own or belong to.",
+        desc: "List groups you own or belong to.",
+        flags: ["--json    Emit the raw group objects instead of formatted lines."],
+    },
+    {
+        usage: "ahood group members <group> [--json]",
+        summary: "List a group's members and their role (owner-only visible to members).",
+        desc: "List a group's details and members. Member-only -- you must belong to the group. Returns not found " +
+            "(rather than a permission error) if you don't, so a group's existence isn't leaked to non-members.",
+        flags: ["--json    Emit the raw group/members objects instead of formatted lines."],
+    },
+    {
+        usage: "ahood group invite-link <group> [--json]",
+        summary: "Create (or regenerate) a shareable invite link for a group you own.",
+        desc: "Create or regenerate a shareable invite link for a group you own. Regenerating invalidates any " +
+            "previously issued link. The raw token is shown only this once -- only its hash is stored server-side, " +
+            "so it cannot be retrieved again later; save it (or the link) somewhere safe.",
+        flags: ["--json    Emit {token, expiresAt, url} instead of formatted lines."],
+    },
+    {
+        usage: "ahood group join <invite-url-or-token>",
+        summary: "Join a group using an invite link or its raw token.",
+        desc: "Join a group using an invite link (e.g. https://ahood.vercel.app/groups/join?token=...) or its bare " +
+            "raw token -- either form works.",
+        examples: [
+            "ahood group join https://ahood.vercel.app/groups/join?token=abc123",
+            "ahood group join abc123",
+        ],
+    },
+    {
+        usage: "ahood group remove-member <group> <username>",
+        summary: "Remove a member from a group you own.",
+        desc: "Remove a member from a group you own. The group's owner cannot be removed this way -- delete the " +
+            "group instead. Only the group's owner can remove someone other than themselves.",
+    },
+    {
+        usage: "ahood group leave <group>",
+        summary: "Leave a group you belong to.",
+        desc: "Leave a group you belong to. The group's owner cannot leave -- delete the group instead.",
+    },
+    {
+        usage: "ahood group delete <group> [--yes]",
+        summary: "Permanently delete a group you own (prompts for confirmation unless --yes is passed).",
+        desc: "Permanently delete a group you own, removing it for every member. Prompts for a typed \"yes\" unless " +
+            "--yes is passed.",
+        flags: ["--yes    Skip the interactive confirmation, for scripts/CI."],
+    },
+];
 // Exported so other consumers of the command list (e.g. shell completion) can
 // surface aliases without needing their own copy of this map. Aliases apply
 // at the skill-verb level today (e.g. "show" for "view"); nothing at the
 // top level currently has one.
 export const COMMAND_ALIASES = { show: "view" };
-// Two-token lookup for a skill-entity verb (findCommandHelp("skill", "search"))
-// or a single-token lookup for a top-level command (findCommandHelp("whoami")).
+// Entity-scoped command lists, keyed by the entity name as it appears right
+// after "ahood" in a usage string (e.g. "ahood skill <verb> ..."). Both
+// findCommandHelp and usageWithAliases key off this map so a future entity
+// only has to be added here once, not re-special-cased in both places.
+const ENTITY_COMMANDS_HELP = {
+    skill: SKILL_COMMANDS_HELP,
+    group: GROUP_COMMANDS_HELP,
+};
+// Two-token lookup for an entity verb (findCommandHelp("skill", "search"),
+// findCommandHelp("group", "create")) or a single-token lookup for a
+// top-level command (findCommandHelp("whoami")).
 export function findCommandHelp(command, subcommand) {
-    if (command === "skill" && subcommand !== undefined) {
+    const entityList = ENTITY_COMMANDS_HELP[command];
+    if (entityList && subcommand !== undefined) {
         const resolved = COMMAND_ALIASES[subcommand] ?? subcommand;
-        return SKILL_COMMANDS_HELP.find((c) => c.usage.startsWith(`ahood skill ${resolved} `) || c.usage === `ahood skill ${resolved}`);
+        return entityList.find((c) => c.usage.startsWith(`ahood ${command} ${resolved} `) || c.usage === `ahood ${command} ${resolved}`);
     }
     const resolved = COMMAND_ALIASES[command] ?? command;
     return TOP_LEVEL_COMMANDS_HELP.find((c) => c.usage.startsWith(`ahood ${resolved} `) || c.usage === `ahood ${resolved}`);
@@ -161,11 +258,11 @@ export function findCommandHelp(command, subcommand) {
 // -> "ahood skill view|show <owner>/<skill> ...". Used by the --help listings
 // so aliases (like "show" for "view") aren't invisible to users who only
 // skim `ahood --help` / `ahood skill --help`. The alias-carrying word is
-// parts[2] for a skill-entity usage string ("ahood skill <verb> ...") and
-// parts[1] for a top-level one ("ahood <command> ...").
+// parts[2] for an entity usage string ("ahood skill <verb> ..." / "ahood
+// group <verb> ...") and parts[1] for a top-level one ("ahood <command> ...").
 export function usageWithAliases(entry) {
     const parts = entry.usage.split(" ");
-    const idx = parts[1] === "skill" ? 2 : 1;
+    const idx = ENTITY_COMMANDS_HELP[parts[1]] ? 2 : 1;
     const name = parts[idx];
     const aliases = Object.keys(COMMAND_ALIASES).filter((alias) => COMMAND_ALIASES[alias] === name);
     if (aliases.length === 0)
@@ -194,16 +291,32 @@ export function formatSkillHelp() {
         "Run `ahood skill <command> --help` for a single command's flags and examples.",
     ].join("\n");
 }
+// `ahood group --help` -- the group-level listing for every group verb.
+export function formatGroupHelp() {
+    const width = Math.max(...GROUP_COMMANDS_HELP.map((c) => usageWithAliases(c).length));
+    const lines = GROUP_COMMANDS_HELP.map((c) => `  ${usageWithAliases(c).padEnd(width + 2)}${c.summary}`);
+    return [
+        "ahood group -- create private groups, invite members, and share skills with them",
+        "",
+        "Commands:",
+        ...lines,
+        "",
+        "Run `ahood group <command> --help` for a single command's flags and examples.",
+    ].join("\n");
+}
 // `ahood --help` -- the top-level listing: account commands rendered in
-// full, plus a single summary line pointing at `ahood skill --help` for
-// the (much longer) skill-entity command list.
+// full, plus a single summary line each pointing at `ahood skill --help`
+// and `ahood group --help` for their (much longer) entity command lists.
 export function formatHelp() {
     const skillGroupUsage = "ahood skill <command>";
     const skillGroupSummary = "Search, install, and publish skills -- run `ahood skill --help` for the full list.";
-    const width = Math.max(...TOP_LEVEL_COMMANDS_HELP.map((c) => usageWithAliases(c).length), skillGroupUsage.length);
+    const groupGroupUsage = "ahood group <command>";
+    const groupGroupSummary = "Create private groups and share skills with them -- run `ahood group --help` for the full list.";
+    const width = Math.max(...TOP_LEVEL_COMMANDS_HELP.map((c) => usageWithAliases(c).length), skillGroupUsage.length, groupGroupUsage.length);
     const lines = [
         ...TOP_LEVEL_COMMANDS_HELP.map((c) => `  ${usageWithAliases(c).padEnd(width + 2)}${c.summary}`),
         `  ${skillGroupUsage.padEnd(width + 2)}${skillGroupSummary}`,
+        `  ${groupGroupUsage.padEnd(width + 2)}${groupGroupSummary}`,
     ];
     return [
         "ahood -- CLI for the ahood skills registry (https://ahood.vercel.app)",
@@ -218,6 +331,7 @@ export function formatHelp() {
         "",
         "Run `ahood <command> --help` (or `ahood help <command>`) for a single command's flags and examples.",
         "Run `ahood skill --help` for the full list of skill commands.",
+        "Run `ahood group --help` for the full list of group commands.",
         "Run `ahood --version` to print the installed CLI version.",
         "",
         "Exit codes: 0 success, 1 general error, 2 usage/validation error,",

package/dist/index.js

@@ -13,11 +13,14 @@ import { edit } from "./commands/edit.js";
 import { unpublish } from "./commands/unpublish.js";
 import { listSkills } from "./commands/list.js";
 import { star, unstar } from "./commands/star.js";
+import { share, unshare } from "./commands/share.js";
 import { view } from "./commands/view.js";
+import { read } from "./commands/read.js";
 import { versions } from "./commands/versions.js";
 import { completion } from "./commands/completion.js";
 import { init } from "./commands/init.js";
-import { formatHelp, formatSkillHelp, formatCommandHelp, findCommandHelp } from "./help.js";
+import { createGroup, listGroups, groupMembers, inviteLink, joinGroup, removeMember, leaveGroup, deleteGroup, } from "./commands/group.js";
+import { formatHelp, formatSkillHelp, formatGroupHelp, formatCommandHelp, findCommandHelp } from "./help.js";
 import { ApiError } from "./http.js";
 import { exitCodeFor } from "./exit-code.js";
 import { CLI_NAME, CLI_VERSION } from "./version.js";
@@ -27,6 +30,7 @@ const SKILL_COMMANDS = {
     search,
     view,
     show: view,
+    read,
     versions,
     list: listSkills,
     add,
@@ -36,13 +40,29 @@ const SKILL_COMMANDS = {
     unpublish,
     star,
     unstar,
+    share,
+    unshare,
     init,
     publish,
 };
+// Every group-entity verb, reached only as `ahood group <verb>` -- see
+// dispatchGroup() below. Named GROUP_VERBS (not GROUP_COMMANDS) specifically
+// to avoid colliding with the pre-existing GROUP_COMMANDS Set below, which
+// means something unrelated ("entities that own their own sub-dispatch").
+const GROUP_VERBS = {
+    create: createGroup,
+    list: listGroups,
+    members: groupMembers,
+    "invite-link": inviteLink,
+    join: joinGroup,
+    "remove-member": removeMember,
+    leave: leaveGroup,
+    delete: deleteGroup,
+};
 // Top level is now just account/auth-scoped commands (not entity-specific --
 // same reasoning `gh auth login` isn't `gh account login`) plus the `skill`
-// entity group. Future entities (e.g. "personality", "protocols") get their
-// own entry here alongside "skill".
+// and `group` entity groups. Future entities (e.g. "personality",
+// "protocols") get their own entry here alongside these two.
 const COMMANDS = {
     login: () => login(),
     logout: () => logout(),
@@ -50,12 +70,16 @@ const COMMANDS = {
     token,
     completion,
     skill: dispatchSkill,
+    group: dispatchGroup,
 };
 // Commands whose handler owns its own --help handling (at both the group
-// level, e.g. `ahood skill --help`, and the per-verb level, e.g.
-// `ahood skill add --help`) instead of the generic top-level interception
-// in main().
-const GROUP_COMMANDS = new Set(["skill"]);
+// level, e.g. `ahood skill --help` / `ahood group --help`, and the per-verb
+// level, e.g. `ahood skill add --help` / `ahood group create --help`)
+// instead of the generic top-level interception in main(). Despite the
+// name, this Set has nothing to do with the "Groups" feature -- "group"
+// here just means "a command that owns its own sub-verb dispatch", the same
+// sense "skill" already used before "group" (the entity) existed.
+const GROUP_COMMANDS = new Set(["skill", "group"]);
 function levenshtein(a, b) {
     const dp = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
     for (let i = 0; i <= a.length; i++)
@@ -87,6 +111,9 @@ function closestCommand(input) {
 function closestSkillCommand(input) {
     return closestOf(input, Object.keys(SKILL_COMMANDS));
 }
+function closestGroupVerb(input) {
+    return closestOf(input, Object.keys(GROUP_VERBS));
+}
 // `ahood skill <verb> [...]` -- owns its own help handling at both the
 // group level (`ahood skill` / `ahood skill --help`) and the per-verb level
 // (`ahood skill <verb> --help`), since neither should fall through to
@@ -113,6 +140,31 @@ async function dispatchSkill(args) {
     }
     await handler(rest);
 }
+// `ahood group <verb> [...]` -- owns its own help handling at both the
+// group level (`ahood group` / `ahood group --help`) and the per-verb level
+// (`ahood group <verb> --help`), exactly mirroring dispatchSkill() above.
+async function dispatchGroup(args) {
+    const [sub, ...rest] = args;
+    if (!sub || sub === "--help" || sub === "-h") {
+        console.log(formatGroupHelp());
+        return;
+    }
+    const handler = GROUP_VERBS[sub];
+    if (!handler) {
+        console.error(`Unknown group command: ${sub}`);
+        const suggestion = closestGroupVerb(sub);
+        if (suggestion)
+            console.error(`Did you mean '${suggestion}'?`);
+        console.error("Run `ahood group --help` for a list of commands.");
+        process.exit(2);
+    }
+    if (rest.includes("--help") || rest.includes("-h")) {
+        const entry = findCommandHelp("group", sub);
+        console.log(entry ? formatCommandHelp(entry) : formatGroupHelp());
+        return;
+    }
+    await handler(rest);
+}
 async function main() {
     const [command, ...args] = process.argv.slice(2);
     if (command === "--version" || command === "-v") {
@@ -127,6 +179,12 @@ async function main() {
             console.log(entry ? formatCommandHelp(entry) : formatSkillHelp());
             return;
         }
+        if (sub === "group") {
+            const verb = args[1];
+            const entry = verb ? findCommandHelp("group", verb) : undefined;
+            console.log(entry ? formatCommandHelp(entry) : formatGroupHelp());
+            return;
+        }
         const entry = sub ? findCommandHelp(sub) : undefined;
         console.log(entry ? formatCommandHelp(entry) : formatHelp());
         return;
@@ -189,4 +247,4 @@ if (isEntrypoint) {
     main();
 }
 // Exported for tests only -- the CLI itself only ever calls main() above.
-export { main, dispatchSkill, COMMANDS, SKILL_COMMANDS };
+export { main, dispatchSkill, dispatchGroup, COMMANDS, SKILL_COMMANDS, GROUP_VERBS };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahood/cli",
-  "version": "0.4.2",
+  "version": "0.5.1",
   "description": "CLI for ahood, a registry for installing and publishing Claude Code skills.",
   "license": "MIT",
   "homepage": "https://github.com/AlexKay28/ahood-cli",