spb/skills-spboucher-ai

1---2title: CLI reference3description: Every command of the skills command line, its options, credential handling and exit codes.4order: 305section: Reference6---78# CLI reference910`skills` is the command-line client of the registry. It validates and packs locally with the same code the server uses, and it never executes anything from a package.1112## Getting it1314The CLI is a single dependency-free JavaScript file for Node.js 20 or newer. It is not yet published to npm; download it from the registry and verify it:1516```bash17curl -fsSLO https://skills.spboucher.ai/cli/skills.mjs18curl -fsSL https://skills.spboucher.ai/cli/skills.mjs.sha256 | shasum -a 256 -c -19chmod +x skills.mjs && mv skills.mjs ~/.local/bin/skills   # any directory on your PATH20skills --version21```2223From a checkout of the registry repository you can also run `pnpm skills <command>` (from source) or `pnpm cli:build` (rebuilds the bundle).2425The registry URL must be `https://`; plain `http://` is accepted only for `localhost` and `127.0.0.1`.2627## Global options2829| Option | Meaning |30|---|---|31| `--registry <url>` | Registry to talk to. Default `https://skills.spboucher.ai`; also `SKILLS_REGISTRY` |32| `--json` | Machine-readable output |33| `--yes` | Answer confirmations affirmatively. Use only after a human approved |3435Exit codes: `0` success · `1` error · `2` validation failed · `3` authentication or authorization problem.3637## Credentials3839Lookup order:40411. `SKILLS_TOKEN` environment variable (process-scoped use; do not export it in a profile).422. OS credential store — macOS Keychain, service `skills-registry`, account = registry host; `secret-tool` on Linux.433. `~/.config/skills/credentials.json` with mode `0600`, only when you opted in with `--insecure-file`.4445The CLI never prints a stored token.4647| Command | What it does |48|---|---|49| `skills login [--token-stdin] [--insecure-file]` | Reads a token from a hidden prompt or standard input, checks it against the registry, stores it |50| `skills logout` | Removes the stored credential for this registry |51| `skills whoami` | Identity, scopes, namespaces and expiry of the current credential |52| `skills auth status` | Whether a credential is stored, where, for which registry, and whether it is still valid |5354## Tokens5556| Command | What it does |57|---|---|58| `skills auth token create --name N --scopes a,b --namespace ns [--expires-in 90d] [--ip CIDR] [--store]` | Creates a token. Prints it once, or with `--store` saves it as the current credential without printing. Needs `tokens:write`; cannot grant more than the calling credential holds |59| `skills auth token list` (alias `skills token list`) | Lists your tokens: name, prefix, scopes, namespaces, expiry, status. Needs `tokens:read` |60| `skills auth token revoke <id\|prefix> [--yes]` | Revokes a token. The current token can always revoke itself |61| `skills auth token rotate [<id\|prefix>] [--yes]` | New secret, same grants; the old token stops working at once. Without an argument, rotates the current credential, stores the replacement and prints nothing |6263Durations: `30m`, `12h`, `90d`. Maximum 366 days. Scopes are listed in the [API reference](/docs/api#scopes).6465## Authoring6667| Command | What it does |68|---|---|69| `skills init [dir] --type <type> --name @ns/slug` | Creates a starter package with `agent-registry.json` and the entry file for the type |70| `skills validate <dir>` | Runs every local check and prints findings. Exit code 2 if any is blocking |71| `skills pack <dir> [-o file]` | Writes the deterministic `.tar.gz` and prints its SHA-256 and size |7273Files skipped when packing: `.git`, `node_modules`, `.DS_Store`, `Thumbs.db`, `__pycache__`, `.venv`, `.idea`, `.vscode`, anything matched by `.skillsignore`, and every symbolic link.7475`.skillsignore` takes one pattern per line: a name (`notes.txt`), a directory (`drafts/`), a path from the package root (`/data/raw`), or a `*` wildcard within one path segment (`*.csv`). Lines starting with `#` are comments.7677## Publishing7879```bash80skills publish <dir> [--visibility public|unlisted|private] [--dry-run] [--yes] [--notes TEXT | --notes-file F]81```82831. Collects and validates the directory. Stops on blocking findings.842. Prints the report: target `@ns/slug`, version, visibility, files and sizes, skipped files, declared permissions, findings, archive SHA-256 and size.853. With `--dry-run`, stops here. Nothing is uploaded and no credential is needed for local checks.864. Creates the artifact if it does not exist. A public artifact, or a change of visibility, asks for confirmation.875. Begins the upload, sends the archive, finalizes.886. Verifies the published checksum and prints the URL, version and state.8990If the server quarantines the release for review, the CLI says so; the release is not public yet.9192| Command | What it does |93|---|---|94| `skills deprecate @ns/slug --reason "…" [--yes]` | Marks the artifact deprecated with a public reason. Needs `artifacts:deprecate` |95| `skills revoke @ns/slug@<version> --reason "…" [--yes]` | Revokes a version permanently. Needs `releases:revoke` |9697## Discovering9899| Command | What it does |100|---|---|101| `skills search "<query>" [--type t] [--client c]` | Full-text search |102| `skills versions @ns/slug` | Release history with state and checksum |103| `skills inspect @ns/slug [--version v] [--file path]` | Metadata, permissions, files, findings; with `--file`, prints one text file of the release |104105## Downloading and installing106107```bash108skills download @ns/slug[@version] [-o file] [--extract dir]109skills install  @ns/slug[@version] --client claude-code|codex|cursor|generic-agent-skills|generic-mcp [--project] [--dir path] [--yes] [--force]110skills update   @ns/slug --client <client> [--project] [--yes]111```112113`download` fetches the archive, verifies its SHA-256 against the release metadata, and optionally extracts it into a new directory.114115`install`, for skills:1161171. Shows the version, publisher, declared permissions, findings and the destination.1182. Asks for confirmation.1193. Downloads, verifies the checksum, re-validates every path.1204. If the destination exists, stops unless `--force` is given; an existing copy is first moved to `~/.skills-registry/backups/`.1215. Copies the files and writes `.skills-registry.json` (name, version, checksum, registry, time).122123It never runs a script from the package.124125Destinations:126127| Client | User scope | `--project` |128|---|---|---|129| `claude-code` | `~/.claude/skills/<slug>` | `.claude/skills/<slug>` |130| `codex` | `~/.agents/skills/<slug>` | `.agents/skills/<slug>` |131| `cursor` | `~/.cursor/skills/<slug>` | `.cursor/skills/<slug>` |132| `generic-agent-skills` | `~/.agents/skills/<slug>` | `.agents/skills/<slug>` |133134`--dir` sets the parent skills directory: the skill is written to `<dir>/<slug>`, so the folder name always equals the skill name, as the Agent Skills specification requires. `update` accepts `--dir` too. For artifact types that are neither a skill nor an MCP server, `install` prints the matching `skills download … --extract` command and exits 1, because nothing was installed.135136For MCP servers, `install` prints the configuration for the chosen client and the environment variables to set. It does not start the server.137138`update` installs the current `latest` over an installed copy after showing what changes, keeping a backup.139140## Examples141142```bash143skills search "manuscript review" --type skill --client claude-code144skills inspect @research/citation-check --file SKILL.md145skills install @research/citation-check@1.2.0 --client claude-code --project146skills validate ./citation-check && skills publish ./citation-check --visibility public --dry-run147SKILLS_REGISTRY=http://localhost:8570 skills whoami148```149