@ahood/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ahood
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# ahood
+
+CLI for [ahood](https://ahood.vercel.app), a registry for installing and publishing Claude Code skills.
+
+## Quick start
+
+```
+npx @alexkay/ahood-cli@latest login
+npx @alexkay/ahood-cli@latest search <something>
+npx @alexkay/ahood-cli@latest add <owner>/<skill>
+```
+
+## Install
+
+```
+npx @alexkay/ahood-cli@latest <command>
+```
+
+or install it globally, so the plain `ahood` command works without `npx`:
+
+```
+npm i -g @alexkay/ahood-cli
+ahood <command>
+```
+
+For CI or any non-interactive environment, set `AHOOD_TOKEN` instead of running `login` -- every command checks it first.
+
+## Commands
+
+<!-- Kept in sync by hand with cli/src/help.ts's COMMANDS_HELP (the terminal
+     --help output's source) and app/docs/page.tsx's COMMANDS array -- update
+     all three when a command changes. -->
+
+| Command | What it does |
+| --- | --- |
+| `ahood login` | Device-code browser login, stores a token at `~/.config/ahood/credentials.json`. |
+| `ahood logout` | Removes the stored token. |
+| `ahood whoami` | Reports whether your stored token still authenticates. |
+| `ahood search <query>` | Search published skills. |
+| `ahood list-mine` | List your own skills, public and private, with their visibility and download/star counts. |
+| `ahood add <owner>/<skill>[@version]` | Install into `.claude/skills/<owner>/<skill>/`, pinned in `.claude/skills.lock.json`. |
+| `ahood update [<owner>/<skill>]` | Move the lockfile pin forward to the latest version. |
+| `ahood remove <owner>/<skill>` | Uninstall and unpin (local only -- does not affect the published skill). |
+| `ahood edit <owner>/<skill> [--tagline] [--tags] [--license] [--visibility]` | Update a skill you own. Only the flags you pass are changed; requires the `publish` scope. |
+| `ahood unpublish <owner>/<skill>` | Deletes the skill from the registry for every consumer, not just your local install -- prompts for a typed "yes" confirmation first. |
+| `ahood star <owner>/<skill>` | Star a skill. |
+| `ahood unstar <owner>/<skill>` | Remove your star from a skill. |
+| `ahood publish <path> --owner <owner> --slug <skill> --version <x.y.z>` | Publish a new version of an existing skill from a folder containing `SKILL.md`. The skill itself is created from the web UI first. |
+| `ahood token create\|list\|revoke` | Manage personal API tokens. Creating a token requires an existing logged-in session -- see the docs. |
+
+Run `ahood help` or `ahood <command> --help` for the same reference directly in your terminal.
+
+Full reference, including personal API tokens, CI usage, the public REST API, and the MCP server: **https://ahood.vercel.app/docs**

package/dist/commands/add.js

@@ -0,0 +1,120 @@
+import { createHash } from "node:crypto";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import * as tarStream from "tar-stream";
+import { gunzipSync } from "node:zlib";
+import { apiFetch, apiJson } from "../http.js";
+import { writeLockfileEntry } from "../lockfile.js";
+// GET /api/v1/skills/{owner}/{skill}/versions/{version} matches the version
+// string with an exact .eq() (verified live against this branch's route) --
+// there is no "latest" literal in skill_versions.version, so requesting
+// versions/latest 404s. Only the download endpoint has "latest" resolution
+// built in. For metadata (which we need up front, to verify the checksum
+// *before* trusting the download), we instead resolve "latest" through
+// GET /api/v1/skills/{owner}/{skill}, whose `skill_versions` field is already
+// joined against the skill's latest_version_id. That response has no
+// yanked_at (latest_version_id isn't expected to ever point at a yanked
+// version in this codebase), so the yanked-skill warning below only fires
+// for an explicit @version -- confirmed by reading both route.ts files
+// rather than assumed.
+async function fetchVersionMeta(owner, skill, version) {
+    if (version === "latest") {
+        const { skill_versions } = await apiJson(`/api/v1/skills/${owner}/${skill}`);
+        if (!skill_versions)
+            throw new Error(`${owner}/${skill} has no published version`);
+        return { ...skill_versions, yanked_at: null };
+    }
+    return apiJson(`/api/v1/skills/${owner}/${skill}/versions/${version}`);
+}
+function parseSpec(spec) {
+    const atIndex = spec.lastIndexOf("@");
+    const ownerSkill = atIndex > 0 ? spec.slice(0, atIndex) : spec;
+    const version = atIndex > 0 ? spec.slice(atIndex + 1) : "latest";
+    const [owner, skill] = ownerSkill.split("/");
+    if (!owner || !skill)
+        throw new Error("Usage: ahood add <owner>/<skill>[@version]");
+    return { owner, skill, version };
+}
+export async function extractTarGz(buffer, destDir) {
+    const tarBuffer = gunzipSync(buffer);
+    const extract = tarStream.extract();
+    const resolvedDest = resolve(destDir);
+    await new Promise((resolvePromise, reject) => {
+        extract.on("entry", (header, stream, next) => {
+            // Path containment, checked BEFORE anything is written. A tar entry
+            // name is attacker-controlled data in an archive we merely downloaded
+            // -- the server's publish-time validateEntries is supposed to have
+            // rejected `..` already, but a client that extracts a remote archive
+            // must not depend on a check it cannot see. resolve() collapses `..`
+            // segments (and, on Windows, drive-absolute and backslash-separated
+            // names) so the comparison catches every escape shape, not just a
+            // literal leading "../".
+            const entryPath = header.name.replace(/^\.\//, "");
+            const fullPath = resolve(destDir, entryPath);
+            if (fullPath !== resolvedDest && !fullPath.startsWith(resolvedDest + sep)) {
+                stream.resume();
+                reject(new Error(`Refusing to extract unsafe archive entry: ${header.name}`));
+                // next() is deliberately NOT called -- nothing further in this archive
+                // should be processed. destroy() tears the paused extractor down
+                // rather than leaving it stalled mid-entry.
+                extract.destroy();
+                return;
+            }
+            if (header.type !== "file") {
+                stream.resume();
+                next();
+                return;
+            }
+            const chunks = [];
+            stream.on("data", (chunk) => chunks.push(chunk));
+            stream.on("end", () => {
+                mkdirSync(join(fullPath, ".."), { recursive: true });
+                writeFileSync(fullPath, Buffer.concat(chunks));
+                next();
+            });
+            stream.on("error", reject);
+        });
+        extract.on("finish", () => resolvePromise());
+        extract.on("error", reject);
+        extract.end(tarBuffer);
+    });
+}
+export async function add(args) {
+    const spec = args[0];
+    if (!spec)
+        throw new Error("Usage: ahood add <owner>/<skill>[@version]");
+    const { owner, skill, version: requestedVersion } = parseSpec(spec);
+    const meta = await fetchVersionMeta(owner, skill, requestedVersion);
+    if (meta.yanked_at) {
+        console.warn(`WARNING: ${owner}/${skill}@${meta.version} has been yanked. Installing anyway.`);
+    }
+    // scripts/ warning: mirrors the web detail page's banner (platform ADR's
+    // Open Risk #7) -- a CLI-only user installing via `add` would otherwise
+    // never see this at all.
+    if (meta.manifest.some((f) => f.path.startsWith("scripts/"))) {
+        console.warn("WARNING: this skill includes a scripts/ directory. Review its contents before use.");
+    }
+    const downloadRes = await apiFetch(`/api/v1/skills/${owner}/${skill}/download?version=${meta.version}`, {
+        headers: { "X-Ahood-Source": "cli" },
+        redirect: "follow",
+    });
+    if (!downloadRes.ok)
+        throw new Error(`Download failed with status ${downloadRes.status}`);
+    const buffer = Buffer.from(await downloadRes.arrayBuffer());
+    const actualChecksum = createHash("sha256").update(buffer).digest("hex");
+    if (actualChecksum !== meta.checksum_sha256) {
+        throw new Error(`Checksum mismatch for ${owner}/${skill}@${meta.version}: expected ${meta.checksum_sha256}, got ${actualChecksum}. Refusing to install.`);
+    }
+    // Owner-namespaced on disk, mirroring npm's node_modules/@scope/package.
+    // Keyed on the slug alone, alice/utils and bob/utils were the same
+    // directory: installing one silently overwrote the other's files, and
+    // `remove` deleted whichever happened to be there. The lockfile key is
+    // already "owner/skill" and needs no change.
+    const destDir = join(".claude", "skills", owner, skill);
+    await extractTarGz(buffer, destDir);
+    writeLockfileEntry(join(".claude", "skills.lock.json"), `${owner}/${skill}`, {
+        version: meta.version,
+        checksum_sha256: meta.checksum_sha256,
+    });
+    console.log(`Installed ${owner}/${skill}@${meta.version} to ${destDir}`);
+}

package/dist/commands/edit.js

@@ -0,0 +1,41 @@
+import { apiJson } from "../http.js";
+function flagValue(args, flag) {
+    const index = args.indexOf(flag);
+    return index >= 0 ? args[index + 1] : undefined;
+}
+// Mirrors PATCH /api/v1/skills/{owner}/{skill}'s allow-list exactly
+// (lib/skills/mutations.ts's UpdateSkillInput) -- only a field the caller
+// explicitly passed a flag for is included in the body, so an omitted flag
+// never clobbers an existing value (the route only validates/writes keys
+// that are present on the body at all).
+export async function edit(args) {
+    const spec = args[0];
+    if (!spec || spec.startsWith("--")) {
+        throw new Error("Usage: ahood edit <owner>/<skill> [--tagline <text>] [--tags <comma,separated>] [--license <id>] [--visibility public|private]");
+    }
+    const [owner, skill] = spec.split("/");
+    if (!owner || !skill)
+        throw new Error("Usage: ahood edit <owner>/<skill> [--tagline ...] [--tags ...] [--license ...] [--visibility ...]");
+    const body = {};
+    const tagline = flagValue(args, "--tagline");
+    if (tagline !== undefined)
+        body.tagline = tagline;
+    const tags = flagValue(args, "--tags");
+    if (tags !== undefined)
+        body.tags = tags.split(",").map((t) => t.trim()).filter(Boolean);
+    const license = flagValue(args, "--license");
+    if (license !== undefined)
+        body.license = license;
+    const visibility = flagValue(args, "--visibility");
+    if (visibility !== undefined)
+        body.visibility = visibility;
+    if (Object.keys(body).length === 0) {
+        throw new Error("Nothing to update -- pass at least one of --tagline, --tags, --license, --visibility.");
+    }
+    const updated = await apiJson(`/api/v1/skills/${owner}/${skill}`, {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    console.log(`Updated ${owner}/${updated.slug}: tagline=${JSON.stringify(updated.tagline)}, license=${JSON.stringify(updated.license)}, visibility=${updated.visibility}, tags=[${updated.tags.join(", ")}]`);
+}

package/dist/commands/list-mine.js

@@ -0,0 +1,11 @@
+import { apiJson } from "../http.js";
+export async function listMine() {
+    const { skills } = await apiJson("/api/v1/skills?mine=true");
+    if (skills.length === 0) {
+        console.log("You haven't published any skills yet.");
+        return;
+    }
+    for (const skill of skills) {
+        console.log(`${skill.slug} (${skill.visibility}) — ${skill.name}${skill.tagline ? `: ${skill.tagline}` : ""} (${skill.downloads_count} downloads, ${skill.stars_count} stars)`);
+    }
+}

package/dist/commands/login.js

@@ -0,0 +1,42 @@
+import { apiJson } from "../http.js";
+import { writeCredentials } from "../credentials.js";
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export async function login() {
+    const { code, verification_url, expires_in } = await apiJson("/api/v1/auth/cli/device", {
+        method: "POST",
+    });
+    console.log(`First, confirm this code matches what you see in your browser: ${code}`);
+    console.log(`Open ${verification_url} to approve.`);
+    const deadline = Date.now() + expires_in * 1000;
+    while (Date.now() < deadline) {
+        await sleep(2000);
+        let res;
+        let body;
+        try {
+            res = await fetch(`${verification_url.split("?")[0].replace("/cli-auth", "")}/api/v1/auth/cli/device/${code}`);
+            body = await res.json();
+        }
+        catch (error) {
+            // A THROWN fetch (DNS blip, dropped socket, a body that isn't JSON) is
+            // transient by nature, and this loop runs for up to ten minutes while a
+            // human walks to their browser -- one bad network moment must not kill
+            // a login that is about to succeed. HTTP *statuses* are still decided
+            // below; only the transport failure is retried. The deadline is
+            // untouched, so this cannot loop forever.
+            console.error(`Polling failed (${error instanceof Error ? error.message : String(error)}); retrying...`);
+            continue;
+        }
+        if (res.status === 200 && body.status === "approved" && body.token) {
+            writeCredentials({ token: body.token });
+            console.log("Logged in.");
+            return;
+        }
+        if (res.status === 410 || res.status === 404) {
+            throw new Error("This login was cancelled or expired. Run `ahood login` again.");
+        }
+        // status === "pending" -- keep polling.
+    }
+    throw new Error("Login timed out. Run `ahood login` again.");
+}

package/dist/commands/logout.js

@@ -0,0 +1,5 @@
+import { clearCredentials } from "../credentials.js";
+export async function logout() {
+    clearCredentials();
+    console.log("Logged out.");
+}

package/dist/commands/publish.js

@@ -0,0 +1,104 @@
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { pack } from "tar-stream";
+import { createGzip } from "node:zlib";
+import { apiJson } from "../http.js";
+// Matched by ENTRY NAME at every depth, not by path prefix, so a nested
+// `vendor/thing/.git` is skipped the same as a top-level one. Not a
+// .gitignore parser (out of scope) -- just the fixed set of names that must
+// never end up in a published archive:
+//   .git      -- .git/config routinely carries a remote URL with embedded
+//                credentials (https://user:ghp_xxx@github.com/...), which the
+//                server-side secret scanner's regexes (AKIA, PEM headers,
+//                32+ hex) do not match.
+//   node_modules -- never part of a skill, and megabytes of it.
+//   .env / .env.* -- the single most likely place a real secret lives.
+//   .DS_Store -- noise.
+const EXCLUDED_NAMES = new Set([".git", "node_modules", ".DS_Store"]);
+function isExcluded(name) {
+    if (EXCLUDED_NAMES.has(name))
+        return true;
+    if (name === ".env" || name.startsWith(".env."))
+        return true;
+    return false;
+}
+async function tarGzDirectory(dir) {
+    const { readdirSync, statSync } = await import("node:fs");
+    const tar = pack();
+    const gzip = createGzip();
+    const chunks = [];
+    function addDir(current, prefix) {
+        for (const entry of readdirSync(current)) {
+            if (isExcluded(entry))
+                continue;
+            const fullPath = join(current, entry);
+            const relPath = prefix ? `${prefix}/${entry}` : entry;
+            const stat = statSync(fullPath);
+            if (stat.isDirectory()) {
+                addDir(fullPath, relPath);
+            }
+            else {
+                tar.entry({ name: relPath, size: stat.size }, readFileSync(fullPath));
+            }
+        }
+    }
+    addDir(dir, "");
+    tar.finalize();
+    return new Promise((resolve, reject) => {
+        gzip.on("data", (chunk) => chunks.push(chunk));
+        gzip.on("end", () => resolve(Buffer.concat(chunks)));
+        gzip.on("error", reject);
+        tar.pipe(gzip);
+    });
+}
+export async function publish(args) {
+    const path = args[0] ?? ".";
+    const skillMdPath = join(path, "SKILL.md");
+    if (!existsSync(skillMdPath)) {
+        throw new Error(`No SKILL.md found at ${skillMdPath} -- publish must point at a skill folder's root.`);
+    }
+    // A real ahood CLI would parse owner/slug/version/name out of SKILL.md
+    // frontmatter or a companion manifest -- this MVP takes them as explicit
+    // flags, matching how `versions/init`'s API itself requires them
+    // separately from the archive. Kept simple: --slug, --owner, --version are
+    // required; metadata creation (POST /skills) is assumed already done via
+    // the web UI or a prior publish -- this command only pushes a NEW VERSION
+    // of an existing skill, matching the ADR's "publish tars, calls
+    // versions/init -> upload -> versions/complete" description exactly (it
+    // does not create the skill's top-level metadata row).
+    const ownerIndex = args.indexOf("--owner");
+    const slugIndex = args.indexOf("--slug");
+    const versionIndex = args.indexOf("--version");
+    const owner = ownerIndex >= 0 ? args[ownerIndex + 1] : undefined;
+    const slug = slugIndex >= 0 ? args[slugIndex + 1] : undefined;
+    const version = versionIndex >= 0 ? args[versionIndex + 1] : undefined;
+    if (!owner || !slug || !version) {
+        throw new Error("Usage: ahood publish <path> --owner <owner> --slug <skill> --version <x.y.z>");
+    }
+    const archive = await tarGzDirectory(path);
+    const init = await apiJson(`/api/v1/skills/${owner}/${slug}/versions/init`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ version, package_size_bytes: archive.length }),
+    });
+    // TS's lib.dom BodyInit (in scope here since tsconfig has no explicit
+    // "lib" override, so DOM is included alongside the Node types) type-checks
+    // Buffer/Uint8Array against `Uint8Array<ArrayBuffer>` specifically as of
+    // TS 5.7+'s ArrayBufferLike generics, which a Node Buffer's
+    // `Uint8Array<ArrayBufferLike>` doesn't structurally satisfy even though
+    // it is a valid BufferSource at runtime (this is exactly what Node's own
+    // fetch/undici accepts) -- see undici-types' BodyInit, which includes
+    // `NodeJS.ArrayBufferView` (i.e. Buffer) directly with no such
+    // restriction. Asserting through BodyInit here, rather than reshaping
+    // tsconfig's "lib" for the whole package, keeps this fix local to the one
+    // call site.
+    const putRes = await fetch(init.upload_url, { method: "PUT", body: archive });
+    if (!putRes.ok)
+        throw new Error(`Upload failed with status ${putRes.status}`);
+    const complete = await apiJson(`/api/v1/skills/${owner}/${slug}/versions/complete`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ version_id: init.version_id }),
+    });
+    console.log(`Published ${owner}/${slug}@${complete.version} (${complete.status})`);
+}

package/dist/commands/remove.js

@@ -0,0 +1,25 @@
+import { rmSync, rmdirSync, readdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { removeLockfileEntry } from "../lockfile.js";
+export async function remove(args) {
+    const spec = args[0];
+    if (!spec)
+        throw new Error("Usage: ahood remove <owner>/<skill>");
+    const [owner, skill] = spec.split("/");
+    if (!owner || !skill)
+        throw new Error("Usage: ahood remove <owner>/<skill>");
+    // Must mirror add.ts's owner-namespaced destDir exactly -- keyed on the
+    // slug alone, `remove bob/utils` deleted alice/utils' files.
+    const dir = join(".claude", "skills", owner, skill);
+    if (existsSync(dir))
+        rmSync(dir, { recursive: true, force: true });
+    // Sweep the owner directory once it holds nothing, so uninstalling an
+    // owner's last skill doesn't leave an empty namespace folder behind (npm
+    // does the same with node_modules/@scope). Guarded on emptiness, so another
+    // skill by the same owner is never touched.
+    const ownerDir = join(".claude", "skills", owner);
+    if (existsSync(ownerDir) && readdirSync(ownerDir).length === 0)
+        rmdirSync(ownerDir);
+    removeLockfileEntry(join(".claude", "skills.lock.json"), spec);
+    console.log(`Removed ${spec}`);
+}

package/dist/commands/search.js

@@ -0,0 +1,14 @@
+import { apiJson } from "../http.js";
+export async function search(args) {
+    const query = args.join(" ");
+    if (!query)
+        throw new Error("Usage: ahood search <query>");
+    const { skills } = await apiJson(`/api/v1/skills?q=${encodeURIComponent(query)}`);
+    if (skills.length === 0) {
+        console.log("No skills found.");
+        return;
+    }
+    for (const skill of skills) {
+        console.log(`${skill.profiles.username}/${skill.slug} — ${skill.name}${skill.tagline ? `: ${skill.tagline}` : ""} (${skill.downloads_count} downloads)`);
+    }
+}

package/dist/commands/star.js

@@ -0,0 +1,26 @@
+import { apiJson } from "../http.js";
+// Mirrors POST/DELETE /api/v1/skills/{owner}/{skill}/star -- both are
+// idempotent server-side (POST upserts on the stars table's
+// unique(skill_id, user_id) constraint with ignoreDuplicates, DELETE just
+// deletes any matching row), so starring an already-starred skill or
+// unstarring one you never starred is a no-op 200, not an error.
+export async function star(args) {
+    const spec = args[0];
+    if (!spec)
+        throw new Error("Usage: ahood star <owner>/<skill>");
+    const [owner, skill] = spec.split("/");
+    if (!owner || !skill)
+        throw new Error("Usage: ahood star <owner>/<skill>");
+    await apiJson(`/api/v1/skills/${owner}/${skill}/star`, { method: "POST" });
+    console.log(`Starred ${owner}/${skill}.`);
+}
+export async function unstar(args) {
+    const spec = args[0];
+    if (!spec)
+        throw new Error("Usage: ahood unstar <owner>/<skill>");
+    const [owner, skill] = spec.split("/");
+    if (!owner || !skill)
+        throw new Error("Usage: ahood unstar <owner>/<skill>");
+    await apiJson(`/api/v1/skills/${owner}/${skill}/star`, { method: "DELETE" });
+    console.log(`Unstarred ${owner}/${skill}.`);
+}

package/dist/commands/token.js

@@ -0,0 +1,51 @@
+import { apiJson } from "../http.js";
+export async function token(args) {
+    const [subcommand, ...rest] = args;
+    switch (subcommand) {
+        case "create":
+            return tokenCreate(rest);
+        case "list":
+            return tokenList();
+        case "revoke":
+            return tokenRevoke(rest);
+        default:
+            throw new Error("Usage: ahood token create|list|revoke");
+    }
+}
+async function tokenCreate(args) {
+    const name = args[0];
+    if (!name)
+        throw new Error("Usage: ahood token create <name>");
+    // Note: this itself requires an existing session-backed token or a
+    // browser login -- per docs/adr/backend/0001-backend-services.md's Phase
+    // 3 section, tokens can't mint tokens (POST /auth/tokens is session-only,
+    // enforced server-side in Task 3). A CLI-only user with no browser access
+    // at all cannot bootstrap their very first token through this command;
+    // `ahood login`'s device-code flow is the only bootstrap path, which
+    // is by design -- see the ADR's "login: device-code flow" as the sole
+    // credential-issuing entry point for a CLI-only session.
+    const result = await apiJson("/api/v1/auth/tokens", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ name }),
+    });
+    console.log(`Created token "${result.name}": ${result.token}`);
+    console.log("Copy this now -- it will not be shown again.");
+}
+async function tokenList() {
+    const { tokens } = await apiJson("/api/v1/auth/tokens");
+    if (tokens.length === 0) {
+        console.log("No tokens.");
+        return;
+    }
+    for (const t of tokens) {
+        console.log(`${t.id}  ${t.name}  ${t.token_prefix}…  ${t.scopes.join(",")}${t.revoked_at ? "  (revoked)" : ""}`);
+    }
+}
+async function tokenRevoke(args) {
+    const id = args[0];
+    if (!id)
+        throw new Error("Usage: ahood token revoke <id>");
+    await apiJson(`/api/v1/auth/tokens/${id}`, { method: "DELETE" });
+    console.log(`Revoked ${id}`);
+}

package/dist/commands/unpublish.js

@@ -0,0 +1,32 @@
+import { createInterface } from "node:readline/promises";
+import { apiJson } from "../http.js";
+// Confirmation is required and has no --yes/--force bypass -- this deletes
+// the skill for every consumer who has ever `ahood add`ed it, not just the
+// local install (that's `ahood remove`). If a non-interactive/CI use case
+// shows up later, add an explicit --yes flag then; defaulting to one now
+// would make the destructive path the easy one.
+async function confirm(promptText) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await rl.question(promptText);
+        return answer.trim().toLowerCase() === "yes";
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function unpublish(args) {
+    const spec = args[0];
+    if (!spec)
+        throw new Error("Usage: ahood unpublish <owner>/<skill>");
+    const [owner, skill] = spec.split("/");
+    if (!owner || !skill)
+        throw new Error("Usage: ahood unpublish <owner>/<skill>");
+    const confirmed = await confirm(`This will permanently delete ${owner}/${skill} for everyone who has installed it. Type "yes" to confirm: `);
+    if (!confirmed) {
+        console.log("Aborted.");
+        return;
+    }
+    await apiJson(`/api/v1/skills/${owner}/${skill}`, { method: "DELETE" });
+    console.log(`Unpublished ${owner}/${skill}. Run \`ahood remove ${owner}/${skill}\` to also remove your local copy.`);
+}

package/dist/commands/update.js

@@ -0,0 +1,20 @@
+import { readLockfile } from "../lockfile.js";
+import { add } from "./add.js";
+// `update` is the only command that moves the lockfile pin forward -- `add`
+// always resolves and pins whatever version it's given (or latest, once,
+// at install time), matching the ADR's "reproducible by default" design.
+export async function update(args) {
+    const lockfile = readLockfile(".claude/skills.lock.json");
+    const targets = args.length > 0 ? args : Object.keys(lockfile);
+    if (targets.length === 0) {
+        console.log("No installed skills to update.");
+        return;
+    }
+    for (const ownerSlashSkill of targets) {
+        if (!lockfile[ownerSlashSkill]) {
+            console.warn(`Skipping ${ownerSlashSkill}: not currently installed.`);
+            continue;
+        }
+        await add([ownerSlashSkill]); // no @version -- resolves to latest again
+    }
+}

package/dist/commands/whoami.js

@@ -0,0 +1,36 @@
+import { ApiError, apiJson } from "../http.js";
+import { resolveToken } from "../credentials.js";
+export async function whoami() {
+    const token = resolveToken();
+    if (!token) {
+        console.log("Not logged in. Run `ahood login`.");
+        return;
+    }
+    // There is no endpoint that returns an identity for a bearer caller yet, so
+    // whoami can only answer "does this token still authenticate?". It probes
+    // /api/v1/auth/tokens, which is deliberately session-only (Task 3), and
+    // reads the STATUS to tell the two failure modes apart -- swallowing every
+    // error and printing "Authenticated." unconditionally (as this did) meant a
+    // revoked token and a garbage token both reported success with exit code 0.
+    //   403 -> resolveCaller accepted the token, the route then rejected it for
+    //          being a token rather than a session. The token is valid.
+    //   401 -> resolveCaller could not resolve the token at all: unknown,
+    //          revoked, or expired.
+    try {
+        await apiJson("/api/v1/auth/tokens");
+        // A session-backed caller (only reachable if this ever runs against a
+        // cookie-bearing client) -- the token list came back.
+        console.log("Authenticated.");
+    }
+    catch (error) {
+        if (error instanceof ApiError && error.status === 403) {
+            console.log("Authenticated with a personal API token.");
+            return;
+        }
+        // 401 and anything else (network failure, 5xx) are both "we could not
+        // confirm this token works" -- exit non-zero so `ahood whoami` is
+        // usable as a scriptable auth check.
+        console.error("Not authenticated -- your token is invalid or has been revoked.");
+        process.exitCode = 1;
+    }
+}

package/dist/config.js

@@ -0,0 +1,7 @@
+const DEFAULT_API_URL = "https://ahood.vercel.app";
+export function getApiUrl() {
+    const configured = process.env.AHOOD_API_URL;
+    if (!configured)
+        return DEFAULT_API_URL;
+    return configured.endsWith("/") ? configured.slice(0, -1) : configured;
+}

package/dist/credentials.js

@@ -0,0 +1,43 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, chmodSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+function credentialsPath() {
+    return join(homedir(), ".config", "ahood", "credentials.json");
+}
+export function readCredentials() {
+    const path = credentialsPath();
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function writeCredentials(creds) {
+    const path = credentialsPath();
+    const dir = join(homedir(), ".config", "ahood");
+    // The `mode` option on mkdirSync/writeFileSync only applies when the
+    // directory/file is actually created (POSIX O_CREAT semantics) -- if
+    // either already exists with looser permissions (manual chmod, a restored
+    // backup, etc.), `mode` is silently ignored and the looser bits persist.
+    // chmodSync is unconditional, so every write re-asserts 0700/0600
+    // regardless of what was there before.
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    chmodSync(dir, 0o700);
+    writeFileSync(path, JSON.stringify(creds, null, 2), { mode: 0o600 });
+    chmodSync(path, 0o600);
+}
+export function clearCredentials() {
+    const path = credentialsPath();
+    if (existsSync(path))
+        unlinkSync(path);
+}
+// AHOOD_TOKEN always wins -- this is what lets CI use a token without
+// ever running the interactive device-code `login` flow.
+export function resolveToken() {
+    if (process.env.AHOOD_TOKEN)
+        return process.env.AHOOD_TOKEN;
+    return readCredentials()?.token ?? null;
+}

package/dist/help.js

@@ -0,0 +1,43 @@
+export const COMMANDS_HELP = [
+    { usage: "ahood login", desc: "Device-code browser login, stores a token locally." },
+    { usage: "ahood logout", desc: "Removes the stored token." },
+    { usage: "ahood whoami", desc: "Reports whether your stored token still authenticates." },
+    { usage: "ahood search <query>", desc: "Search published skills." },
+    { usage: "ahood list-mine", desc: "List your own skills, public and private." },
+    { usage: "ahood add <owner>/<skill>[@version]", desc: "Install a skill into .claude/skills/, pinned in the lockfile." },
+    { usage: "ahood update [<owner>/<skill>]", desc: "Move the lockfile pin forward to the latest version." },
+    { usage: "ahood remove <owner>/<skill>", desc: "Uninstall and unpin (local only)." },
+    {
+        usage: "ahood edit <owner>/<skill> [--tagline] [--tags] [--license] [--visibility]",
+        desc: "Update a skill you own.",
+    },
+    { usage: "ahood unpublish <owner>/<skill>", desc: "Delete a skill from the registry (asks for confirmation)." },
+    { usage: "ahood star <owner>/<skill>", desc: "Star a skill." },
+    { usage: "ahood unstar <owner>/<skill>", desc: "Remove your star from a skill." },
+    {
+        usage: "ahood publish <path> --owner <owner> --slug <skill> --version <x.y.z>",
+        desc: "Publish a new version of an existing skill.",
+    },
+    { usage: "ahood token create|list|revoke", desc: "Manage personal API tokens (requires a browser session)." },
+];
+export function findCommandHelp(command) {
+    return COMMANDS_HELP.find((c) => c.usage === command || c.usage.startsWith(`ahood ${command} `) || c.usage === `ahood ${command}`);
+}
+export function formatHelp() {
+    const width = Math.max(...COMMANDS_HELP.map((c) => c.usage.length));
+    const lines = COMMANDS_HELP.map((c) => `  ${c.usage.padEnd(width + 2)}${c.desc}`);
+    return [
+        "ahood -- CLI for the ahood skills registry (https://ahood.vercel.app)",
+        "",
+        "Quick start:",
+        "  ahood login",
+        "  ahood search <something>",
+        "  ahood add <owner>/<skill>",
+        "",
+        "Commands:",
+        ...lines,
+        "",
+        "Run `ahood <command> --help` for a single command's usage.",
+        "Full reference: https://ahood.vercel.app/docs",
+    ].join("\n");
+}

package/dist/http.js

@@ -0,0 +1,24 @@
+import { getApiUrl } from "./config.js";
+import { resolveToken } from "./credentials.js";
+export class ApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+export async function apiFetch(path, init = {}) {
+    const token = resolveToken();
+    const headers = new Headers(init.headers);
+    if (token)
+        headers.set("Authorization", `Bearer ${token}`);
+    return fetch(`${getApiUrl()}${path}`, { ...init, headers });
+}
+export async function apiJson(path, init = {}) {
+    const res = await apiFetch(path, init);
+    const body = await res.json().catch(() => ({}));
+    if (!res.ok) {
+        throw new ApiError(res.status, body.error ?? `Request failed with status ${res.status}`);
+    }
+    return body;
+}

package/dist/index.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+import { login } from "./commands/login.js";
+import { logout } from "./commands/logout.js";
+import { whoami } from "./commands/whoami.js";
+import { search } from "./commands/search.js";
+import { add } from "./commands/add.js";
+import { update } from "./commands/update.js";
+import { remove } from "./commands/remove.js";
+import { publish } from "./commands/publish.js";
+import { token } from "./commands/token.js";
+import { edit } from "./commands/edit.js";
+import { unpublish } from "./commands/unpublish.js";
+import { listMine } from "./commands/list-mine.js";
+import { star, unstar } from "./commands/star.js";
+import { formatHelp, findCommandHelp } from "./help.js";
+const COMMANDS = {
+    login: () => login(),
+    logout: () => logout(),
+    whoami: () => whoami(),
+    search: (args) => search(args),
+    add: (args) => add(args),
+    update: (args) => update(args),
+    remove: (args) => remove(args),
+    publish: (args) => publish(args),
+    token: (args) => token(args),
+    edit: (args) => edit(args),
+    unpublish: (args) => unpublish(args),
+    "list-mine": () => listMine(),
+    star: (args) => star(args),
+    unstar: (args) => unstar(args),
+};
+async function main() {
+    const [command, ...args] = process.argv.slice(2);
+    // Bare invocation and an explicit help request both just want to see
+    // what's available -- neither is an error.
+    if (!command || command === "help" || command === "--help" || command === "-h") {
+        console.log(formatHelp());
+        return;
+    }
+    const handler = COMMANDS[command];
+    if (!handler) {
+        console.error(`Unknown command: ${command}\n`);
+        console.error(formatHelp());
+        process.exit(1);
+    }
+    if (args.includes("--help") || args.includes("-h")) {
+        const entry = findCommandHelp(command);
+        console.log(entry ? `${entry.usage}\n\n${entry.desc}` : formatHelp());
+        return;
+    }
+    try {
+        await handler(args);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(message);
+        // "Unauthorized" is the exact, literal body every resolveCaller-gated
+        // route returns on a 401 (see lib/resolve-caller.ts's callers) -- the
+        // one signal worth appending a next-step to, since every other error
+        // message is already command-specific.
+        if (/^unauthorized$/i.test(message)) {
+            console.error("Run `ahood login` first (or set AHOOD_TOKEN).");
+        }
+        process.exit(1);
+    }
+}
+main();

package/dist/lockfile.js

@@ -0,0 +1,26 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+export function readLockfile(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        return JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch {
+        return {};
+    }
+}
+function writeLockfile(path, lockfile) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(lockfile, null, 2) + "\n");
+}
+export function writeLockfileEntry(path, ownerSlashSkill, entry) {
+    const lockfile = readLockfile(path);
+    lockfile[ownerSlashSkill] = entry;
+    writeLockfile(path, lockfile);
+}
+export function removeLockfileEntry(path, ownerSlashSkill) {
+    const lockfile = readLockfile(path);
+    delete lockfile[ownerSlashSkill];
+    writeLockfile(path, lockfile);
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@ahood/cli",
+  "version": "0.1.0",
+  "description": "CLI for ahood, a registry for installing and publishing Claude Code skills.",
+  "license": "MIT",
+  "homepage": "https://github.com/AlexKay28/ahood-cli",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AlexKay28/ahood-cli.git"
+  },
+  "keywords": [
+    "ahood",
+    "claude",
+    "claude-code",
+    "cli",
+    "skills"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "ahood": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "tar-stream": "^3.2.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "@types/tar-stream": "^3.1.4",
+    "typescript": "^5",
+    "vitest": "^4.1.11"
+  }
+}