SPB Git
spboucher.ai

Repository Public MIT

spbskills-spboucher-ai

cli.md 7.5 KB

# title: CLI reference description: Every command of the skills command line, its options, credential handling and exit codes. order: 30 section: Reference

# CLI reference

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.

# Getting it

The 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:

bash
curl -fsSLO https://skills.spboucher.ai/cli/skills.mjs
curl -fsSL https://skills.spboucher.ai/cli/skills.mjs.sha256 | shasum -a 256 -c -
chmod +x skills.mjs && mv skills.mjs ~/.local/bin/skills   # any directory on your PATH
skills --version

From a checkout of the registry repository you can also run pnpm skills <command> (from source) or pnpm cli:build (rebuilds the bundle).

The registry URL must be https://; plain http:// is accepted only for localhost and 127.0.0.1.

# Global options

Option Meaning
--registry <url> Registry to talk to. Default https://skills.spboucher.ai; also SKILLS_REGISTRY
--json Machine-readable output
--yes Answer confirmations affirmatively. Use only after a human approved

Exit codes: 0 success · 1 error · 2 validation failed · 3 authentication or authorization problem.

# Credentials

Lookup order:

  1. SKILLS_TOKEN environment variable (process-scoped use; do not export it in a profile).
  2. OS credential store — macOS Keychain, service skills-registry, account = registry host; secret-tool on Linux.
  3. ~/.config/skills/credentials.json with mode 0600, only when you opted in with --insecure-file.

The CLI never prints a stored token.

Command What it does
skills login [--token-stdin] [--insecure-file] Reads a token from a hidden prompt or standard input, checks it against the registry, stores it
skills logout Removes the stored credential for this registry
skills whoami Identity, scopes, namespaces and expiry of the current credential
skills auth status Whether a credential is stored, where, for which registry, and whether it is still valid

# Tokens

Command What it does
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
skills auth token list (alias skills token list) Lists your tokens: name, prefix, scopes, namespaces, expiry, status. Needs tokens:read
skills auth token revoke <id|prefix> [--yes] Revokes a token. The current token can always revoke itself
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

Durations: 30m, 12h, 90d. Maximum 366 days. Scopes are listed in the API reference.

# Authoring

Command What it does
skills init [dir] --type <type> --name @ns/slug Creates a starter package with agent-registry.json and the entry file for the type
skills validate <dir> Runs every local check and prints findings. Exit code 2 if any is blocking
skills pack <dir> [-o file] Writes the deterministic .tar.gz and prints its SHA-256 and size

Files skipped when packing: .git, node_modules, .DS_Store, Thumbs.db, __pycache__, .venv, .idea, .vscode, anything matched by .skillsignore, and every symbolic link.

.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.

# Publishing

bash
skills publish <dir> [--visibility public|unlisted|private] [--dry-run] [--yes] [--notes TEXT | --notes-file F]
  1. Collects and validates the directory. Stops on blocking findings.
  2. Prints the report: target @ns/slug, version, visibility, files and sizes, skipped files, declared permissions, findings, archive SHA-256 and size.
  3. With --dry-run, stops here. Nothing is uploaded and no credential is needed for local checks.
  4. Creates the artifact if it does not exist. A public artifact, or a change of visibility, asks for confirmation.
  5. Begins the upload, sends the archive, finalizes.
  6. Verifies the published checksum and prints the URL, version and state.

If the server quarantines the release for review, the CLI says so; the release is not public yet.

Command What it does
skills deprecate @ns/slug --reason "…" [--yes] Marks the artifact deprecated with a public reason. Needs artifacts:deprecate
skills revoke @ns/slug@<version> --reason "…" [--yes] Revokes a version permanently. Needs releases:revoke

# Discovering

Command What it does
skills search "<query>" [--type t] [--client c] Full-text search
skills versions @ns/slug Release history with state and checksum
skills inspect @ns/slug [--version v] [--file path] Metadata, permissions, files, findings; with --file, prints one text file of the release

# Downloading and installing

bash
skills download @ns/slug[@version] [-o file] [--extract dir]
skills install  @ns/slug[@version] --client claude-code|codex|cursor|generic-agent-skills|generic-mcp [--project] [--dir path] [--yes] [--force]
skills update   @ns/slug --client <client> [--project] [--yes]

download fetches the archive, verifies its SHA-256 against the release metadata, and optionally extracts it into a new directory.

install, for skills:

  1. Shows the version, publisher, declared permissions, findings and the destination.
  2. Asks for confirmation.
  3. Downloads, verifies the checksum, re-validates every path.
  4. If the destination exists, stops unless --force is given; an existing copy is first moved to ~/.skills-registry/backups/.
  5. Copies the files and writes .skills-registry.json (name, version, checksum, registry, time).

It never runs a script from the package.

Destinations:

Client User scope --project
claude-code ~/.claude/skills/<slug> .claude/skills/<slug>
codex ~/.agents/skills/<slug> .agents/skills/<slug>
cursor ~/.cursor/skills/<slug> .cursor/skills/<slug>
generic-agent-skills ~/.agents/skills/<slug> .agents/skills/<slug>

--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.

For MCP servers, install prints the configuration for the chosen client and the environment variables to set. It does not start the server.

update installs the current latest over an installed copy after showing what changes, keeping a backup.

# Examples

bash
skills search "manuscript review" --type skill --client claude-code
skills inspect @research/citation-check --file SKILL.md
skills install @research/citation-check@1.2.0 --client claude-code --project
skills validate ./citation-check && skills publish ./citation-check --visibility public --dry-run
SKILLS_REGISTRY=http://localhost:8570 skills whoami
Files main
Menu

Theme
↑↓navigate ↵open escclose /⌘Kanywhere