# @skillsmith/cli

> **Important:** The bare `skillsmith` package on npm is **not** this project. Install `@skillsmith/cli` for the CLI or configure [`@skillsmith/mcp-server`](https://www.npmjs.com/package/@skillsmith/mcp-server) for MCP integration.

Command-line interface for Skillsmith — publish, manage, and author agent skills.

Part of Skillsmith: a registry for sharing, scanning, and tracking agent skills across teams.

## Contents

- [What's New](#whats-new-in-v0812)
- [Installation](#installation)
- [Commands](#commands)
  - [inventory](#inventory)
- [Configuration](#configuration)
- [Examples](#examples)
- [Privacy & Data Handling](#privacy--data-handling)

## What's New in v0.8.12

- **Multi-client targeting fixed across the board**: `install`, `list`, `remove`, `update`, `sync`, and `search -i`'s install action now all honor `SKILLSMITH_CLIENT`/`--client` consistently — previously several of these silently acted on the Claude Code directory regardless of the flag or env var.
- **`update` no longer fails after a fresh install**: now resolves the installed skill's registry source from the manifest `install` already writes, instead of a dead-code path that could never find it.
- **New `skillsmith registry install <skillId>`**: pulls a skill previously published to your team's Enterprise private registry and installs it locally.
- **New security-acceptance workflow**: `sklx audit security --accept/--revoke/--candidates/--list-accepted` lets you mark a reviewed false-positive as accepted so it stops re-surfacing, without affecting rug-pull/hostile-update detection.
- **`recommend --installed` actually used now**: an explicit `--installed` list is fed into the recommendation query instead of being silently ignored on an empty-derived-stack workspace.
- **Security-status coloring corrected**: a borderline-safe scan result no longer renders identically bright-green to a comfortably-safe one.

See [CHANGELOG.md](./CHANGELOG.md) for previous releases.

**Local-first by design.** Skillsmith caches the registry in a local SQLite database at `~/.skillsmith/skills.db`, shared across the MCP server, the CLI, and the VS Code extension. Search is FTS5 (SQLite's built-in keyword search) by default; semantic search is opt-in (`SKILLSMITH_USE_HNSW=true`) and runs over local ONNX embeddings (an open ML model format that runs on CPU — no API call). [Inside the Local Skill Database](https://skillsmith.app/blog/inside-the-local-skill-database) walks through the schema, the FTS5 / HNSW search paths, and how `sync` keeps the cache fresh.

## Installation

```bash
npm install -g @skillsmith/cli
```

Or use directly with npx:

```bash
npx @skillsmith/cli search "testing"
```

## Updating the CLI

Check your current version:

```bash
skillsmith --version
```

Update to the latest version:

```bash
# If installed globally
npm update -g @skillsmith/cli

# Or reinstall to specific version
npm install -g @skillsmith/cli@latest

# Using npx always gets the latest
npx @skillsmith/cli@latest --version
```

## Command Alias

The CLI provides two command names:
- `skillsmith` - Full command name
- `sklx` - Short alias for faster typing

Both commands are identical:

```bash
# These are equivalent
skillsmith search "testing"
sklx search "testing"
```

## Commands

### search

Search for skills with optional interactive mode.

```bash
# Basic search
skillsmith search "git commit"

# With filters
skillsmith search "testing" --category testing --trust verified

# Interactive mode
skillsmith search --interactive
```

**Options:**
- `-c, --category <category>` - Filter by category
- `-t, --trust <tier>` - Filter by trust tier (verified, community, experimental)
- `-l, --limit <n>` - Maximum results (default: 10)
- `-i, --interactive` - Interactive selection mode

### list

List installed skills.

```bash
skillsmith list

# With details
skillsmith list --verbose
```

**Options:**
- `-v, --verbose` - Show detailed information

### install

Install a skill (alias for MCP server's install_skill).

```bash
skillsmith install author/skill-name
```

### remove

Remove an installed skill.

```bash
skillsmith remove author/skill-name

# Skip confirmation
skillsmith remove author/skill-name --force
```

**Options:**
- `-f, --force` - Skip confirmation prompt

### update

Update installed skills. Requires an explicit selector — a skill name, several
names, or `--all` — bare `skillsmith update` with none of those prints usage
guidance instead of updating anything.

```bash
# Preview what --all would change before applying it
skillsmith update --all --dry-run

# Update one skill
skillsmith update skill-name

# Update a specific set of skills
skillsmith update skill-name another-skill

# Preview changes without applying them
skillsmith update skill-name --dry-run
```

**Options:**
- `-a, --all` - Update all installed skills
- `-n, --dry-run` - Show what would update without installing
- `-d, --db <path>` - Database file path

### inventory

Cross-machine skill inventory for viewing which agent skills are installed across your machines and harnesses. Requires `skillsmith login` and opt-in via the [Cross-machine skill inventory toggle](https://www.skillsmith.app/account/telemetry) at skillsmith.app/account/telemetry (off by default). Once enabled, view your inventory at [skillsmith.app/account/skills](https://www.skillsmith.app/account/skills).

**Privacy:** Only skill IDs, versions, content hashes, declared SKILL.md front-matter fields (author, license, repository), and device platform metadata are uploaded. File contents, paths, and your raw hostname are never transmitted. Set `SKILLSMITH_INVENTORY_DISABLE=1` to hard-disable, or run `skillsmith inventory purge` to delete everything already stored.

#### inventory push

Push this device's installed-skill snapshot to your Skillsmith account.

```bash
skillsmith inventory push
```

Requires:
- Active authentication via `skillsmith login`
- "Cross-machine skill inventory" toggle enabled at skillsmith.app/account/telemetry

#### inventory status

Show local device inventory status (read-only, no network call).

```bash
skillsmith inventory status

# Verbose output
skillsmith inventory status --verbose
```

**Options:**
- `--verbose` - List the individual skill IDs found under each harness

#### inventory forget-device

Clear the local device registration; the next push creates a fresh device ID and registers as a new machine.

```bash
skillsmith inventory forget-device
```

#### inventory purge

Permanently delete this account's entire stored cross-machine inventory from Skillsmith's servers (all devices and their skill rows). Irreversible. Prompts for confirmation unless `--yes` is passed.

```bash
skillsmith inventory purge
skillsmith inventory purge --yes
```

**Options:**
- `-y, --yes` - Skip the confirmation prompt (for scripts)

See [Cross-machine skill inventory](https://www.skillsmith.app/docs/inventory) for details.

### init

Initialize a new skill project.

```bash
# Interactive mode
skillsmith init

# With name
skillsmith init my-skill

# In specific directory
skillsmith init my-skill --path ./skills/my-skill
```

**Options:**
- `-p, --path <path>` - Directory to create skill in
- `--template <template>` - Skill template (basic, advanced)

### create

Scaffold a new agent skill at `~/.claude/skills/<name>/`.

```bash
# Interactive mode
skillsmith create

# With name
skillsmith create my-skill

# Non-interactive
skillsmith create my-skill --description "Git workflow helper" --author myuser --type basic

# Preview without writing
skillsmith create my-skill --dry-run
```

**Options:**
- `-o, --output <dir>` - Output directory (default: `~/.claude/skills`)
- `--type <type>` - Skill type: `basic`, `intermediate`, `advanced`
- `--behavior <behavior>` - Behavioral classification: `autonomous`, `guided`, `interactive`, `configurable`
- `-d, --description <description>` - Skill description (skips prompt)
- `-a, --author <author>` - Author GitHub username (skips prompt)
- `-c, --category <category>` - Category: `development`, `productivity`, `communication`, `data`, `security`, `other`
- `--scripts` - Include a `scripts/` directory
- `-y, --yes` - Auto-confirm overwrite if skill directory exists
- `--dry-run` - Preview scaffold output without writing files

**Generated Structure:**
```
~/.claude/skills/my-skill/
├── SKILL.md           # Skill definition
├── README.md          # Documentation
├── CHANGELOG.md       # Version history
├── .gitignore
└── resources/         # Supporting files
```

### validate

Validate a skill's SKILL.md file.

```bash
# Validate current directory
skillsmith validate

# Validate specific path
skillsmith validate ./path/to/skill

# Strict mode (warnings as errors)
skillsmith validate --strict
```

**Options:**
- `-s, --strict` - Treat warnings as errors

### publish

Prepare a skill for publishing/sharing.

```bash
skillsmith publish

# Dry run (no changes)
skillsmith publish --dry-run
```

**Options:**
- `-d, --dry-run` - Preview without making changes

### author subagent

Generate a companion specialist agent for parallel skill execution.

```bash
# Generate subagent for current directory
skillsmith author subagent

# Generate for specific skill
skillsmith author subagent ./my-skill

# Override detected tools
skillsmith author subagent --tools "Read,Write,Bash"

# Use different model
skillsmith author subagent --model haiku
```

**Options:**
- `-o, --output <path>` - Output directory (default: ~/.claude/agents)
- `--tools <tools>` - Override detected tools (comma-separated)
- `--model <model>` - Model: sonnet, opus, haiku (default: sonnet)
- `--skip-claude-md` - Skip CLAUDE.md snippet generation
- `--force` - Overwrite existing subagent

**Output:**
- Creates `~/.claude/agents/[skill-name]-specialist.md`
- Displays CLAUDE.md integration snippet

### author transform

Upgrade existing skills with subagent configuration (non-destructive).

```bash
# Preview what would be generated
skillsmith author transform ./my-skill --dry-run

# Generate subagent for existing skill
skillsmith author transform ./my-skill

# Process multiple skills at once
skillsmith author transform ~/.claude/skills --batch
```

**Options:**
- `--dry-run` - Preview without creating files
- `--force` - Overwrite existing subagent
- `--batch` - Process directory of skills
- `--tools <tools>` - Override detected tools
- `--model <model>` - Model: sonnet, opus, haiku (default: sonnet)

### author mcp-init

Scaffold a new MCP server project with TypeScript and stdio transport.

```bash
# Interactive mode
skillsmith author mcp-init

# With name
skillsmith author mcp-init my-mcp-server

# With pre-defined tools
skillsmith author mcp-init my-server --tools "greet,search,process"

# Custom output directory
skillsmith author mcp-init my-server --output ./servers
```

**Options:**
- `-o, --output <path>` - Output directory (default: current directory)
- `--tools <tools>` - Initial tool names (comma-separated)
- `--force` - Overwrite existing directory

**Generated Structure:**
```
my-mcp-server/
├── package.json         # npm package with MCP SDK
├── tsconfig.json        # TypeScript configuration
├── src/
│   ├── index.ts         # Entry point (npx-ready)
│   ├── server.ts        # MCP server setup
│   └── tools/
│       ├── index.ts     # Tool definitions
│       └── example.ts   # Example tool implementation
├── README.md            # Usage documentation
└── .gitignore
```

**After Generation:**
```bash
cd my-mcp-server
npm install
npm run dev  # Start in development mode
```

**Configure in your MCP client settings** (`~/.claude/settings.json`):
```json
{
  "mcpServers": {
    "my-mcp-server": {
      "command": "npx",
      "args": ["tsx", "/path/to/my-mcp-server/src/index.ts"]
    }
  }
}
```

### import

Import skills from GitHub (for populating local database).

```bash
# Import from default topic
skillsmith import

# Custom topic and limits
skillsmith import --topic claude-skill --max 500
```

**Options:**
- `-t, --topic <topic>` - GitHub topic to search (default: claude-skill)
- `-m, --max <n>` - Maximum skills to import
- `-d, --db <path>` - Database path
- `-v, --verbose` - Verbose output

### sync

Synchronize your local skill database with the live Skillsmith registry (Team+ tier). The registry holds hundreds of thousands of skills, so `sync` shows a live record count and asks for confirmation before downloading — pass `-y`/`--yes` to skip the prompt for scripted or automated use (e.g. running the CLI on a Team's own cloud instance to maintain a shared local mirror).

```bash
# Sync skills from registry (differential - only changes)
skillsmith sync

# Skip the confirmation prompt (automation)
skillsmith sync --yes

# Force full sync (ignore last sync time)
skillsmith sync --force

# Preview what would be synced
skillsmith sync --dry-run
```

**Options:**
- `-f, --force` - Force full sync, ignore last sync timestamp
- `--dry-run` - Preview changes without writing to database
- `-y, --yes` - Skip the confirmation prompt (for automation; also implied by `--json`)
- `-d, --db <path>` - Database path
- `--json` - Output results as JSON

#### sync status

Show sync status and statistics.

```bash
skillsmith sync status
```

**Output includes:**
- Auto-sync enabled/disabled
- Sync frequency (daily/weekly)
- Last sync time
- Next scheduled sync
- Last run statistics

#### sync history

View sync operation history.

```bash
# Show recent sync history
skillsmith sync history

# Show more entries
skillsmith sync history --limit 20
```

**Options:**
- `-l, --limit <n>` - Number of history entries (default: 10)

#### sync config

Configure automatic sync settings.

```bash
# Show current configuration
skillsmith sync config --show

# Enable automatic background sync (Team+ tier)
skillsmith sync config --enable

# Disable automatic sync
skillsmith sync config --disable

# Set sync frequency
skillsmith sync config --frequency daily
skillsmith sync config --frequency weekly

# Combine options
skillsmith sync config --enable --frequency weekly
```

**Options:**
- `--show` - Display current configuration
- `--enable` - Enable automatic background sync
- `--disable` - Disable automatic sync
- `--frequency <freq>` - Set frequency: `daily` or `weekly`

### audit

#### audit advisories

Check installed skills against known security advisories (Team+ tier). Use `--fix` to attempt updating skills with available patches.

```bash
# Check all installed skills
skillsmith audit advisories

# Output as JSON
skillsmith audit advisories --json

# Auto-update skills with patches
skillsmith audit advisories --fix
```

**Options:**
- `--json` - Emit results as JSON
- `--fix` - Attempt `skillsmith update` for each advisory with a patch available

#### audit collisions

Audit installed skills for namespace collisions — duplicate tool names across multiple skills that could cause invocation conflicts (Community+).

```bash
# Interactive audit (prompts for each collision)
skillsmith audit collisions

# Include semantic-overlap detector pass
skillsmith audit collisions --deep

# Output raw JSON (no prompts, no file writes)
skillsmith audit collisions --json

# Accept every suggestion automatically (requires typing APPLY ALL)
skillsmith audit collisions --apply-all

# Write report only, no interactive prompts
skillsmith audit collisions --report-only

# Clear the namespace-override ledger (requires typing RESET LEDGER)
skillsmith audit collisions --reset-ledger
```

**Options:**
- `--deep` - Enable semantic-overlap detector pass
- `--json` - Emit `RunInventoryAuditResult` as JSON; bypasses prompts and file mutation
- `--apply-all` - Accept every rename suggestion; requires typing `APPLY ALL` to confirm
- `--report-only` - Write audit report without prompts or apply
- `--reset-ledger` - Clear `~/.skillsmith/namespace-overrides.json` (backs up first); requires typing `RESET LEDGER`

### config

Get or set Skillsmith configuration values in `~/.skillsmith/config.json`.

#### config get

Print the resolved value of a configuration key.

```bash
skillsmith config get audit_mode
```

**Supported keys:** `audit_mode`

The resolved value reflects the config-file entry when set, else the tier default:
- `community` / `individual` → `preventative`
- `team` → `power_user`
- `enterprise` → `governance`

#### config set

Write a configuration value. Tier-revalidated on write — `community` and `individual` users cannot select `power_user` or `governance`.

```bash
skillsmith config set audit_mode preventative
skillsmith config set audit_mode power_user    # team/enterprise only
skillsmith config set audit_mode governance    # enterprise only
skillsmith config set audit_mode off
```

**Valid values for `audit_mode`:** `preventative`, `power_user`, `governance`, `off`

**Error codes (stderr, exit 1):**
- `audit.mode.invalid_value` — value not in the supported set
- `audit.mode.tier_ineligible` — your tier cannot select the requested mode

### login

Authenticate the Skillsmith CLI with your API key. Opens your browser to [skillsmith.app/account/cli-token](https://skillsmith.app/account/cli-token), where you generate and copy a key, then paste it into the terminal prompt.

```bash
skillsmith login
```

```
Opening https://skillsmith.app/account/cli-token in your browser...

After authenticating, copy the API key shown and paste it below.
? Paste your API key: [input is masked]

✓ Logged in successfully.
  Note: your API key may still be in your clipboard. Clear it when done.
```

**Options:**
- `--no-browser` — Print the URL instead of opening a browser (for headless/CI/SSH environments)

**Headless/CI environments:** Use `SKILLSMITH_API_KEY` as an environment variable — no browser needed.

**Key storage:** Keys are stored in your OS keyring (macOS Keychain, GNOME Keyring, Windows Credential Store) when available, with `~/.skillsmith/config.json` as fallback.

### logout

Remove the stored API key.

```bash
skillsmith logout
```

```
? Log out and remove stored API key? (y/N) y
✓ Logged out. Key removed from OS keyring.
```

### whoami

Show current authentication status.

```bash
skillsmith whoami
```

```
Skillsmith CLI
  Key:    sk_live_xxxx...
  Source: OS keyring
  Format: valid
```

**Source** indicates where the active key was read from:
- `OS keyring` — stored by `skillsmith login` (most secure)
- `config file (~/.skillsmith/config.json)` — file-based fallback
- `environment variable (SKILLSMITH_API_KEY)` — injected at runtime

## Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `SKILLSMITH_API_KEY` | API key for authenticated requests (alternative to `skillsmith login`) | - |
| `SKILLSMITH_DB_PATH` | Database file location | `~/.skillsmith/skills.db` |
| `SKILLSMITH_IMPORT_DELAY_MS` | Delay between GitHub API calls during import | `150` |
| `GITHUB_TOKEN` | GitHub token for imports | - |

### Database Location

By default, the CLI uses `~/.skillsmith/skills.db`. Override with:

```bash
SKILLSMITH_DB_PATH=/custom/path/skills.db skillsmith search "testing"
```

### Error Logging

Structured error logs are automatically persisted to disk for debugging and diagnostics.

**Log Location:** `~/.skillsmith/logs/skillsmith-cli-<YYYY-MM-DD>.jsonl`

**Log Format:** One JSON-line record per error, with fields:
- `ts` — ISO 8601 timestamp
- `level` — log level (`debug`, `info`, `warn`, `error`)
- `surface` — invocation surface (`cli`, `mcp`, or `vscode`)
- `event` — short machine-readable category tag
- `msg` — human-readable message (redacted)
- `err` — normalized error object with `name`, `message`, and first 20 stack frames (all redacted)
- `correlationId` — trace ID linking related log entries and telemetry events
- `toolOrCommand` — CLI command name or MCP tool name
- `skillId` — skill ID when applicable
- `version` — package version
- `pid` — process ID
- `details` — additional structured context beyond the fields above, when provided (redacted)

**Redaction:** Secrets, tokens, API keys, passwords, connection strings, and PEM keys are automatically redacted before any record is written to disk — this applies to the message, error stack, and any structured context. Redaction happens synchronously at the call site, so disk logs are already safe to inspect or share.

**Rotation & Retention:** Log files rotate daily (new file per UTC calendar date) and are capped at ~10MB with `.1`, `.2` continuation files. Files older than 14 days are automatically deleted on startup (CLI or MCP server, whichever runs first).

**Control Logging:**

| Variable | Default | Description |
|----------|---------|-------------|
| `SKILLSMITH_ERROR_LOG_DISABLE` | unset (logging ON) | Set to `'1'` or `'true'` to disable error logging entirely |
| `SKILLSMITH_LOG_LEVEL` | `warn` | Filter log verbosity: `debug`, `info`, `warn`, or `error` |

Examples:

```bash
# Turn off error logging
SKILLSMITH_ERROR_LOG_DISABLE=1 skillsmith search "testing"

# Enable debug-level verbosity (noisier, more detailed logs)
SKILLSMITH_LOG_LEVEL=debug skillsmith search "testing"
```

**Inspect Logs:** Run `skillsmith diagnose` to view a redacted summary of recent error records, or `skillsmith logs --tail` to follow logs in real-time. Both commands redact secrets inline, so output is always safe to paste in chat or share.

## Privacy & Data Handling

Skillsmith is designed with privacy as a core principle.

### What Stays on Your Computer (Never Transmitted)

| Data | Location | Purpose |
|------|----------|---------|
| Skill usage history | `~/.skillsmith/analytics.db` | Personal ROI tracking |
| Time saved metrics | `~/.skillsmith/analytics.db` | Your productivity insights |
| Value calculations | Computed locally | ROI dashboard |
| Project context | Hashed locally | Anonymous grouping |

**The ROI Dashboard feature is 100% local.** Your usage patterns, time saved, and value metrics never leave your computer. This data exists solely for your benefit.

### What Is Transmitted (Required for Functionality)

| Data | When | Why |
|------|------|-----|
| Search queries | When you search | To return matching skills |
| Skill IDs | When viewing/installing | To fetch skill details |

### Optional Telemetry (Opt-In)

Anonymous product analytics (search counts, feature usage) are **opt-in only**. Telemetry is disabled by default and requires explicit configuration (`SKILLSMITH_TELEMETRY_ENABLED=true`).

To run fully offline: Set `SKILLSMITH_OFFLINE_MODE=true` to disable all network calls.

## Examples

### Discover and Install Skills

```bash
# Search for testing-related skills
skillsmith search "jest testing" --category testing

# Get more details on a skill
skillsmith search "jest-helper" --verbose

# Install a skill
skillsmith install community/jest-helper

# List installed skills
skillsmith list
```

### Create a New Skill

```bash
# Scaffold with interactive prompts
skillsmith create my-awesome-skill

# Or fully non-interactive
skillsmith create my-awesome-skill \
  --description "Automates deployment checks" \
  --author myuser \
  --type intermediate \
  --behavior guided \
  --yes
```

### Author a New Skill

```bash
# Initialize new skill
skillsmith init my-awesome-skill

# Edit the generated SKILL.md...

# Validate your skill
skillsmith validate ./my-awesome-skill

# Generate companion subagent for parallel execution
skillsmith author subagent ./my-awesome-skill

# Prepare for publishing
skillsmith publish ./my-awesome-skill
```

### Upgrade Existing Skills with Subagents

```bash
# Preview subagent generation (dry run)
skillsmith author transform ~/.claude/skills/docker --dry-run

# Generate subagent for a skill
skillsmith author transform ~/.claude/skills/docker

# Batch upgrade all skills
skillsmith author transform ~/.claude/skills --batch --force
```

### Create an MCP Server

```bash
# Scaffold a new MCP server
skillsmith author mcp-init my-slack-integration --tools "send_message,list_channels"

# Navigate and install dependencies
cd my-slack-integration
npm install

# Start development server
npm run dev

# Add to MCP client settings
# Edit ~/.claude/settings.json to include the server
```

### Manage Skills

```bash
# Preview updates to all installed skills, then update one at a time
skillsmith update --all --dry-run

# Remove a skill
skillsmith remove community/old-skill

# Interactive search and install
skillsmith search --interactive
```

### Keep Skills Up-to-Date

`sync` and background auto-sync require Team+ tier — see [sync](#sync) above.

```bash
# Sync with the live registry
skillsmith sync

# Check sync status
skillsmith sync status

# Enable daily auto-sync
skillsmith sync config --enable --frequency daily

# View sync history
skillsmith sync history
```

## License

[Elastic License 2.0](https://www.elastic.co/licensing/elastic-license)

## Links

- [GitHub](https://github.com/smith-horn/skillsmith)
- [Issues](https://github.com/smith-horn/skillsmith/issues)