CLI Reference

The csreg CLI is the primary tool for interacting with the Skills Registry from the terminal.

Installation#

npm install -g @agent-nexus/csreg

Authentication#

login#

csreg login [--token <token>]

Prints a URL to authenticate with the registry. Visit the URL in your browser, then paste the auth token when prompted.

For CI environments or pre-generated tokens, use the --token flag to skip the interactive flow:

csreg login --token <token>

logout#

csreg logout

Removes stored credentials for the registry.

whoami#

csreg whoami

Prints the currently authenticated user and the registry URL.

Authoring#

init#

csreg init [directory]

Scaffolds a new skill directory with a SKILL.md file. Uses interactive prompts to gather the skill name, description, scope, and whether it should be user-invocable.

Created structure:

my-skill/
  SKILL.md

validate#

csreg validate [directory]
  --all    # Validate all skills in .claude/skills/

Validates the skill manifest (SKILL.md), checks that the entry file exists, and enforces size limits. Exits with code 0 if valid or 1 if errors are found.

pack#

csreg pack [directory]

Creates a .tar.gz archive of the skill without uploading it to the registry. Useful for inspecting what will be published or for manual distribution.

Publishing#

push#

csreg push [directory]
  --all    # Push all skills in .claude/skills/

Packs and uploads the skill to the registry. The publish flow runs through these steps:

1. Validate the manifest and entry file
2. Pack the skill files into an archive
3. Prepare the version on the registry (reserve the version number)
4. Upload the archive to storage
5. Finalize the version (mark as published)
6. Set the channel pointer (defaults to latest)

Installing#

pull#

csreg pull [ref]
  --all          # Pull all skills from .claude/skills.json
  --path <dir>   # Custom install directory

Downloads and extracts a skill into your project. By default, the latest channel is used. You can pin to a specific version or channel:

# Install the latest version
csreg pull @backend/code-reviewer

# Install a specific version
csreg pull @backend/code-reviewer@1.2.0

# Install from the stable channel
csreg pull @backend/code-reviewer@stable

# Install to a custom path
csreg pull @backend/code-reviewer --path ./tools

Inspection#

info#

csreg info <scope>/<name>

Prints skill metadata including the description, latest version, available channels, and total download count.

versions#

csreg versions <scope>/<name>

Lists all published versions of a skill with their publish dates and statuses.

search#

csreg search <query>
  -t, --type <type>     # Filter by skill type
  -l, --limit <limit>   # Max results (default: 20)

Searches the registry for skills matching the query. Example:

$ csreg search "code review"

@backend/code-reviewer    v2.1.0    Code review automation     12,340 downloads
@devtools/pr-reviewer     v1.5.2    Pull request reviewer       8,210 downloads
@qa/review-checklist      v3.0.1    Review checklist generator   5,890 downloads

Exit Codes#

All CLI commands use consistent exit codes:

Configuration#

The CLI reads configuration from multiple sources. Settings are resolved in the following order of precedence (highest to lowest):

1. CLI flags (e.g., --registry)
2. Environment variables
3. User configuration file

Config file locations:

Environment variables: