# CLI Reference

```
skilllane <command> [options]
```

## Global Options

| Option | Description |
|--------|-------------|
| `-h, --help` | Show help message |
| `-v, --version` | Show version number |
| `--json` | Output as JSON (where applicable) |
| `--strict` | Strict validation mode |

---

## Commands

### `init`

Initialize the `~/.skilllane` directory.

```bash
skilllane init
```

Creates `~/.skilllane/`, `~/.skilllane/skills/`, and `~/.skilllane/runs/`.

---

### `create <name>`

Create a new skill from a template.

```bash
skilllane create <name> [options]
```

| Option | Description |
|--------|-------------|
| `--title <title>` | Skill display title |
| `--description <desc>` | Skill description |
| `--category <cat>` | Category: engineering, marketing, design, writing, devops, research, general |
| `--tags <t1,t2,...>` | Comma-separated tags |
| `--targets <t1,t2,...>` | Comma-separated targets: codex, opencode, codra, tera, mcp, clipboard, stdout |
| `--template <name>` | Template: basic, debugging, writing, product-launch |
| `--out <dir>` | Output directory |

**Examples:**

```bash
skilllane create my-skill
skilllane create my-skill --title "My Skill" --category engineering
skilllane create debug-helper --template debugging --tags "debug,troubleshoot"
skilllane create content-writer --template writing --out ./skills
```

---

### `validate <path>`

Validate a skill directory for correctness and completeness.

```bash
skilllane validate <path> [options]
```

| Option | Description |
|--------|-------------|
| `--strict` | Fail immediately on first error |
| `--json` | Output results as JSON |

**Output:** Score out of 100, list of errors and warnings.

```bash
skilllane validate ./my-skill
skilllane validate ./my-skill --strict
skilllane validate ./my-skill --json
```

---

### `install <source>`

Install a skill from a local path, git URL, or built-in skills.

```bash
skilllane install <source> [options]
```

| Option | Description |
|--------|-------------|
| `--builtin` | Install from built-in skills directory |
| `--name <name>` | Custom name for the installed skill |
| `--force` | Overwrite existing installation |

**Examples:**

```bash
skilllane install ./my-skill
skilllane install --builtin systematic-debugging
skilllane install https://github.com/user/repo.git
skilllane install ./my-skill --force --name custom-name
```

**Install sources:**
- **Local path:** `./my-skill` or `/absolute/path/to/skill`
- **Git URL:** `https://github.com/user/repo.git` (clones shallow, looks for `metadata.json` or `skills/` directory)
- **Built-in:** `--builtin <name>` (installs from bundled skills)

---

### `list`

List installed skills.

```bash
skilllane list [options]
```

| Option | Description |
|--------|-------------|
| `--tag <tag>` | Filter by tag |
| `--category <cat>` | Filter by category |
| `--json` | Output as JSON |

**Examples:**

```bash
skilllane list
skilllane list --category engineering
skilllane list --tag debugging
skilllane list --json
```

---

### `search <query>`

Search installed skills by name, title, description, or tags.

```bash
skilllane search <query>
```

**Example:**

```bash
skilllane search debug
skilllane search "code review"
```

---

### `show <name>`

Show detailed information about an installed skill.

```bash
skilllane show <name>
```

**Example:**

```bash
skilllane show systematic-debugging
```

---

### `run <name>`

Run a skill to generate a structured prompt.

```bash
skilllane run <name> [task] [options]
```

| Option | Description |
|--------|-------------|
| `--task <task>` | Task description |
| `--context <text>` | Context string |
| `--target <target>` | Target runtime: codex, opencode, codra, tera, mcp, clipboard, stdout, all |
| `--out <path>` | Save output to file |

**Examples:**

```bash
skilllane run systematic-debugging --task "Fix the login bug"
skilllane run agent-code-review --task "Review PR #42" --context "src/auth.ts"
skilllane run systematic-debugging --task "Debug error" --target opencode --out result.json
```

---

### `remove <name>`

Remove an installed skill.

```bash
skilllane remove <name>
```

**Example:**

```bash
skilllane remove systematic-debugging
```

---

### `export <name>`

Export a skill to a `.tar.gz` archive.

```bash
skilllane export <name> [--out <path>]
```

**Examples:**

```bash
skilllane export my-skill
skilllane export my-skill --out ./backup.tar.gz
```

---

### `serve`

Start the HTTP API server.

```bash
skilllane serve [--port <port>]
```

| Option | Description |
|--------|-------------|
| `--port <port>` | Port number (default: 3000) |

**Environment variables:**

| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | `3080` | Server port |
| `SKILLLANE_REQUIRE_AUTH` | `false` | Require auth for write operations |
| `SKILLLANE_API_AUTH_TOKEN` | (none) | Bearer token for auth |

```bash
skilllane serve
skilllane serve --port 8080
SKILLLANE_REQUIRE_AUTH=true SKILLLANE_API_AUTH_TOKEN=mytoken skilllane serve
```

---

### `mcp`

Start the MCP (Model Context Protocol) server over stdio.

```bash
skilllane mcp
```

Reads JSON-RPC messages from stdin and writes responses to stdout. Used by MCP-compatible clients.

---

### `doctor`

Check system health.

```bash
skilllane doctor
```

Checks: Node.js version, storage directory, config file, registry, built-in skills.

---

### `demo`

Run the deterministic demo.

```bash
skilllane demo
```

Validates the `systematic-debugging` skill, installs it, runs it with a sample TypeScript error, and saves output to `demo/demo-output.json`.

---

### `registry <subcommand>`

Manage the local registry.

```bash
skilllane registry path       # Show registry file path
skilllane registry rebuild    # Rebuild from installed skills
skilllane registry stats      # Show statistics
```

---

### `config <subcommand>`

Manage configuration.

```bash
skilllane config get <key>            # Get a config value
skilllane config set <key> <value>    # Set a config value
skilllane config list                 # List all config values
```

**Config keys:**

| Key | Default | Description |
|-----|---------|-------------|
| `defaultTarget` | `opencode` | Default agent target |
| `outputMode` | `prompt` | Default output mode |
| `authToken` | `null` | API auth token |
| `registryUrl` | `https://registry.skilllane.dev` | Remote registry URL |
| `requireAuth` | `false` | Require auth for API |
| `builtinDir` | `null` | Custom built-in skills dir |
| `skillsDir` | (empty) | Custom skills directory |