CLI Reference

Complete reference for all spm commands.

Overview

The spm CLI manages the full lifecycle of AI skills — from creation to publishing.

spm <command> [options]

Manage skills

spm add

Add a skill to your environment.

spm add <skill> [options]

Flag	Description
`-g, --global`	Install globally instead of project-local
`-v, --version <v>`	Specific version to install
`--github <token>`	GitHub token for private repos
`--for [personas]`	Add skill reference to persona file(s) (comma-separated; interactive multiselect if omitted)

Sources:

spm add author/skill-name          # From registry
spm add ./my-skill                 # Local directory
spm add github:user/repo           # From GitHub
spm add author/skill --for my-persona   # Add ref to persona (no install)
spm add author/skill --for p1,p2        # Add to multiple personas

When run inside a project (with .spm/ directory), skills are installed locally and the dependency is added to skillbase.json.

spm install

Install all skill dependencies from skillbase.json.

spm install

Flag	Description
`-g, --global`	Install to global skills directory

This is analogous to yarn install — it reads skillbase.json and installs all listed dependencies.

spm remove

Remove a skill or a skill reference from a persona.

spm remove <name> [options]

Flag	Description
`--from [persona]`	Remove skill reference from persona file(s) (comma-separated; interactive multiselect if omitted)

spm remove author/skill             # Uninstall skill
spm remove frontend-developer       # Also works with bare name
spm remove author/skill --from rev  # Remove ref from rev's SOUL.md
spm remove author/skill --from      # Interactive persona selection

spm link

Link a local skill directory for development (like yarn link).

spm link <path>

Creates a symlink from the global skills directory to your local skill, so changes are picked up immediately.

spm list

List all installed skills.

spm list [-v, --verbose]

spm info

Show detailed information about a skill.

spm info <name>

spm update

Update installed skills to latest versions from the registry (like npm update).

spm update [skill] [options]

Flag	Description
`-g, --global`	Update globally installed skills
`-f, --force`	Re-install even if version matches (useful when content changed without version bump)

spm update                    # Check all installed skills for updates
spm update author/skill       # Update a specific skill
spm update -g                 # Update global skills
spm update --force            # Force re-install all, even if versions match

Search & discovery

spm search

Search for skills locally and in remote registries.

spm search <query> [options]

Flag	Description
`--remote`	Search remote registries only
`--all`	Search both local and remote

spm stats

Show feedback statistics for installed skills.

spm stats

spm rate

Provide explicit feedback for a skill.

spm rate <name> --score <1-5> [--comment <text>]

Personas

spm persona create

Create a new persona scaffold.

spm persona create <name>

Generates a SOUL.md scaffold in the current directory.

spm persona list

List all installed personas.

spm persona list

spm persona activate

Activate a persona and auto-install any missing skills.

spm persona activate <name>

This sets the persona as active in config, checks all skill refs in SOUL.md, auto-installs any missing skills, and confirms activation. If the persona is not installed but a SOUL.md file exists in the current directory, it will be installed automatically.

spm persona deactivate

Deactivate the current persona.

spm persona deactivate

spm persona info

Show detailed information about a persona.

spm persona info <name>

spm persona remove

Remove a persona from global installation. If the persona is currently active, it is automatically deactivated.

spm persona remove <name>

spm persona validate

Validate a SOUL.md file.

spm persona validate <path>

spm persona export

Export a persona to an external platform format.

spm persona export <name> -f <format> [options]

Flag	Description
`-f, --format <format>`	Target format (e.g. `openclaw`)
`-o, --output <dir>`	Output directory (default: `./<name>-<format>/`)
`--overwrite`	Overwrite existing files

spm persona export my-agent -f openclaw
spm persona export my-agent -f openclaw -o ./custom-dir --overwrite

spm persona deploy

Deploy a persona to an external platform.

spm persona deploy <name> -t <target> [options]

Flag	Description
`-t, --target <target>`	Target platform (e.g. `openclaw`)
`-a, --agent-id <id>`	Agent ID on target (default: persona name)
`-c, --bind-channel <channel>`	Messaging channel to bind
`--bind-account <id>`	Account within channel
`--openclaw-config <path>`	Custom openclaw.json path
`--overwrite`	Overwrite existing workspace

spm persona deploy my-agent -t openclaw
spm persona deploy my-agent -t openclaw -c telegram
spm persona deploy my-agent -t openclaw -c whatsapp --bind-account personal

spm persona import

Import a persona from an external platform.

spm persona import --from <platform> [options]

Flag	Description
`--from <platform>`	Source platform (e.g. `openclaw`)
`--agent-id <id>`	Agent ID to import from
`--workspace <path>`	Direct path to workspace directory
`-o, --output <path>`	Output SOUL.md path

spm persona import --from openclaw --workspace ~/.openclaw/workspace-my-bot
spm persona import --from openclaw --agent-id my-bot

See Deploy Targets for full documentation.

Adding skills to personas

Use spm add with the --for flag to add skill references to persona files:

spm add community/code-review --for my-persona
spm add community/testing --for reviewer,writer
spm add community/code-review --for           # interactive multiselect
spm remove community/code-review --from my-persona

The --for flag only writes a reference to the SOUL.md file — it does not install the skill. Skills are installed automatically when you run spm persona activate.

Publishing

spm publish

Publish a skill to a registry.

spm publish [source] [options]

Flag	Description
`--registry <name>`	Target registry
`--github`	Source is a GitHub URL
`--dry-run`	Preview without executing
`--all`	Publish all skills found in subdirectories (max 1000)

Batch publish all skills from the current directory:

spm publish --all
spm publish --all --dry-run
spm publish --all --registry my-registry

Processes each subdirectory containing SKILL.md sequentially. Failures are logged but don't stop the batch — a summary is shown at the end.

Authenticate with a registry.

spm login [registry-url] [options]

Flag	Description
`--name <name>`	Author name (direct API token registration)
`--github`	Authenticate via GitHub OAuth device flow

spm registry add

Add a remote registry.

spm registry add <url> [options]

Flag	Description
`--name <name>`	Registry name (auto-generated if omitted)
`--token <token>`	API token

System

spm init

Initialize the skills directory.

spm init [--project]

Flag	Description
`--project`	Initialize in current directory (`.spm/` + `skillbase.json`) instead of global (`~/.spm/`)

spm create

Create a new skill scaffold.

spm create <name>

Creates a directory with a SKILL.md template. Edit the YAML frontmatter to set the author, description, trigger, and tags.

spm validate

Validate a skill directory against the schema.

spm validate <path>

Checks JSON Schema compliance, required files, name format, and semver validity.

spm convert

Convert prompt files to skill scaffolds.

spm convert <source> [options]

Flag	Description
`--author <name>`	Author name
`--scope <scope>`	Skill scope (default: `user`)
`--license <license>`	License (default: `MIT`)
`-o, --output <dir>`	Output directory

Supports .md, .txt, and .prompt files.

spm connect

Connect spm to an AI client.

spm connect <client>

Supported clients: claude, claude-code, cursor, vscode, windsurf, jetbrains, zed, cline, roo-code, continue, amazonq, gemini, opencode, openclaw

spm disconnect

Remove spm from an AI client.

spm disconnect <client>

spm serve

Start the MCP server on stdio.

spm serve [--stdio]

Used by AI clients to communicate with spm via the Model Context Protocol.

spm reindex

Rebuild the skill index.

spm reindex [--project]

spm protocol register / unregister

Register or remove the spm:// protocol handler with the operating system. This enables one-click install from the website.

spm protocol register
spm protocol unregister

Runs automatically on npm install -g @skillbase/spm.

spm migrate

Detect and run format migrations.

spm migrate detect    # Show what would be migrated
spm migrate run       # Run the migration

Converts skill.json → SKILL.md and .person.json → SOUL.md automatically.

spm connections

Manage remote connections.

spm connections list
spm connections test <name>
spm connections default <name>
spm connections remove <name>

Documentation

spm docs sync

Re-fetch and re-index documentation for a skill. Without arguments, syncs all skills with docs.

spm docs sync [skill] [--force]

Flag	Description
`--force`	Force re-fetch even if cache is valid

spm docs status

Show documentation cache status for all skills with docs configured.

spm docs status

Displays chunks count, indexed pages, cache size, and navigation map per skill.

spm docs search

Search indexed documentation from the command line.

spm docs search <query> [options]

Flag	Description
`-s, --skill <name>`	Limit search to a specific skill
`-n, --limit <number>`	Max results (default: 5)

spm docs clear

Clear the documentation cache. Without arguments, clears all caches.

spm docs clear [skill]

PreviousSecurity & Permissions

NextMCP Integration