> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gofastskill.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference Overview

> CLI for the FastSkill package manager: installs, manifests, validation, evals, search, and serve.

## Overview

The FastSkill CLI is how you **install and operate** skills: manifests and `skills.lock`, validation and `fastskill eval`, search, plus `serve` when you want a local HTTP surface.

<Info>
  The CLI supports both interactive and scripting use cases, with comprehensive help text and validation for all commands.
</Info>

## Installation

Use the same install method as the [Installation](/installation) guide (release binary recommended). After install, confirm the CLI is on your PATH:

```bash theme={null}
fastskill -V
```

For Git-based skill sources, use a build that includes Git support if your distribution splits binaries that way. See [Installation](/installation) for details.

## Basic Usage

### Get Help

<Steps>
  <Step title="General help">
    ```bash theme={null}
    fastskill --help
    ```

    This shows all available commands and global options.
  </Step>

  <Step title="Command-specific help">
    ```bash theme={null}
    fastskill serve --help        # Help for serve command
    fastskill add --help          # Help for add command
    fastskill list --help         # Help for list command
    ```
  </Step>
</Steps>

### Global Options

| Option                | Description                                                     | Example                                                  |
| --------------------- | --------------------------------------------------------------- | -------------------------------------------------------- |
| `-V, --version`       | Print the `fastskill` binary version and exit                   | `fastskill -V`                                           |
| `--verbose`, `-v`     | Enable verbose logging                                          | `fastskill -v list`                                      |
| `--repositories-path` | Override path to `repositories.toml`                            | `fastskill --repositories-path ./repositories.toml list` |
| `--global`            | Use the user-level global skills directory                      | `fastskill --global list`                                |
| Positional `SKILL_ID` | Shorthand for `fastskill read <id>` when no subcommand is given | `fastskill pptx`                                         |
| `--help`, `-h`        | Help                                                            | `fastskill --help`                                       |

## Command Categories

### Project and lifecycle

<CardGroup cols={2}>
  <Card title="fastskill init" icon="play">
    Create `skill-project.toml` for a skill (authors). See [init Command](/cli-reference/init-command).
  </Card>

  <Card title="fastskill install" icon="download">
    Install skills from `skill-project.toml` (supports groups and `--lock`). See [install Command](/cli-reference/install-command).
  </Card>

  <Card title="fastskill update" icon="edit">
    Update skills to latest from source with version strategies. See [update Command](/cli-reference/update-command).
  </Card>

  <Card title="fastskill reindex" icon="refresh-cw">
    Rebuild the search index for semantic discovery. See [reindex Command](/cli-reference/reindex-command).
  </Card>

  <Card title="fastskill serve" icon="server">
    Start the HTTP server (`--host`, `--port`). Web UI and API routes are served with the process. See [serve Command](/cli-reference/serve-command).
  </Card>
</CardGroup>

### Skills

<CardGroup cols={2}>
  <Card title="fastskill add" icon="plus">
    Add skills from registry ID, git, zip, or local folder (supports `-r` for recursive folder add, `--branch`, `--tag`, `-e`, `--group`). See [skill commands](/cli-reference/skill-commands#add).
  </Card>

  <Card title="fastskill read" icon="book-open">
    Retrieve skill documentation and base directory path in agent-optimized format. See [skill commands](/cli-reference/skill-commands#fastskill-read).
  </Card>

  <Card title="fastskill list" icon="list">
    List locally installed skills with reconciliation status (supports `--format table|json|grid|xml`, `--json`). See [skill commands](/cli-reference/skill-commands#list).
  </Card>

  <Card title="fastskill remove" icon="trash">
    Remove skills by ID. See [skill commands](/cli-reference/skill-commands#fastskill-remove).
  </Card>
</CardGroup>

### Registry & search

<CardGroup cols={2}>
  <Card title="fastskill search" icon="search">
    Search remote catalogs by default; use `--local` for embedding search on installed skills. See [search Command](/cli-reference/search-command).
  </Card>

  <Card title="fastskill repos" icon="book">
    Manage repositories (list/add/remove/info/update/test/refresh) and browse remote skill catalog with authentication and priority. See [repos Command](/cli-reference/repository-command).
  </Card>
</CardGroup>

### Diagnostics and tooling

<CardGroup cols={2}>
  <Card title="fastskill version" icon="info">
    Show CLI version.
  </Card>

  <Card title="fastskill eval" icon="check">
    Validate and run skill evaluation suites. See [eval Command](/cli-reference/eval-command).
  </Card>

  <Card title="fastskill analyze" icon="chart-network">
    Similarity matrix, clusters, duplicates. See [tooling commands](/cli-reference/tooling-commands#fastskill-analyze).
  </Card>

  <Card title="fastskill doctor" icon="stethoscope">
    Check environment readiness (skills directory, embedding provider, auth). See [tooling commands](/cli-reference/tooling-commands#fastskill-doctor).
  </Card>
</CardGroup>

## Version Command

### fastskill version

Display the FastSkill CLI version information.

```bash theme={null}
fastskill version
```

**What it shows:**

* CLI version number (e.g., `fastskill 0.9.3`)
* Based on the version defined in Cargo.toml

**Use cases:**

* Verify FastSkill installation
* Check version for compatibility
* Include in bug reports

**Example output:**

```bash theme={null}
$ fastskill version
fastskill 0.9.3
```

## Configuration

### Configuration Files

The CLI uses `.fastskill/config.yaml` for service-level configuration:

```yaml .fastskill/config.yaml theme={null}
embedding:
  openai_base_url: "https://api.openai.com/v1"
  embedding_model: "text-embedding-3-small"

# Optional: Custom skills directory
skills_directory: ".claude/skills"
```

Project-level configuration (skill dependencies and repositories) is stored in `skill-project.toml` at your project root:

```toml skill-project.toml theme={null}
[dependencies]
web-scraper = { source = "git", url = "https://github.com/org/web-scraper.git" }

[tool.fastskill.repositories]
[[tool.fastskill.repositories]]
name = "public-registry"
type = "http-registry"
index_url = "https://api.fastskill.io/index"
priority = 0
```

For opt-in registry publishing builds, see the platform-managed deploy workflow. Skill distribution is handled by the platform operator rather than a self-hosted CLI publish path.

### Environment Variables

## Scripting and automation

Use the CLI in scripts the same way you would run `git` or `uv`: non-interactive flags (`--yes`, `--force`, `--json`) are preferred for automation.

### Batch operations

```bash theme={null}
# Add multiple local skills (editable) and install
for dir in ./skills/*; do
  fastskill add "$dir" -e --group dev
done

# Alternative: use recursive add for all skills under a directory
fastskill add ./skills -r -e --group dev

fastskill install
fastskill reindex
```

### JSON Output

```bash theme={null}
# Get machine-readable search results
fastskill search "text processing" --format json > skills.json

# Parse count
count=$(jq length skills.json)
echo "Total matches: $count"
```

### Exit Codes

The CLI returns appropriate exit codes for scripting:

| Code | Meaning          | Example                            |
| ---- | ---------------- | ---------------------------------- |
| `0`  | Success          | Command completed successfully     |
| `1`  | General error    | Invalid arguments or configuration |
| `2`  | Validation error | Invalid skill definition           |
| `3`  | Network error    | Cannot connect to service          |
| `4`  | Timeout error    | Command timed out                  |
| `5`  | Permission error | Insufficient permissions           |

```bash theme={null}
#!/bin/bash
# Minimal install + search smoke test

set -e
fastskill install
fastskill reindex
fastskill search "smoke test"
```

## Examples

### Example: local project

```bash theme={null}
# 1. Add a skill you are iterating on (optional group)
fastskill add ./skills/my-skill -e --group dev

# 2. Apply the manifest and refresh the local index
fastskill install
fastskill reindex

# 3. Browse with the bundled web UI
fastskill serve --port 8080

# 4. Try search (remote catalog by default; add --local for installed skills)
fastskill search "text processing"
```

### Example: reproducible install

```bash theme={null}
fastskill install --lock
fastskill reindex
fastskill serve --port 8080
```

For running `fastskill` in automation (build machines, sandboxes), install the CLI in the job image, check out your repo, then run the same commands with secrets injected for registry tokens and `OPENAI_API_KEY` when needed.

## Troubleshooting

### Common Issues

<AccordionGroup>
  <Accordion title="Command Not Found">
    <Warning>
      **Path issue**: Ensure FastSkill is installed and in your PATH.

      ```bash theme={null}
      which fastskill
      fastskill -V
      ```
    </Warning>
  </Accordion>

  <Accordion title="Permission Errors">
    <Tip>
      **File permissions**: Ensure you have read/write permissions for skill directories.

      ```bash theme={null}
      # Fix permissions
      chmod 755 ./skills/
      chmod 644 ./skills/*.json
      ```
    </Tip>

    <Tip>
      **Service permissions**: Run with appropriate privileges for system-wide operations.
    </Tip>
  </Accordion>

  <Accordion title="Network Issues">
    <Info>
      **Port conflicts**: Check if the default port (8080) is available.

      ```bash theme={null}
      # Check port usage
      netstat -tlnp | grep :8080

      # Use different port
      fastskill serve --port 9000
      ```
    </Info>
  </Accordion>
</AccordionGroup>

### More verbose output

```bash theme={null}
fastskill -v install
```

Some distributions document extra logging variables; check your install notes if you need trace-level diagnostics.

## Best Practices

<Steps>
  <Step title="Commit manifest and lock">
    Commit `skill-project.toml` and `skills.lock` together for reproducible installs.
  </Step>

  <Step title="Reindex after changes">
    Run `fastskill reindex` after adding or updating skills so search stays fresh.
  </Step>

  <Step title="Use groups for optional skills">
    Use groups (for example `--group dev`) and install with `--without dev` when you want a smaller production skill set.
  </Step>

  <Step title="Check the server when you use serve">
    Confirm `http://<host>:<port>/` responds after upgrades or config changes.
  </Step>

  <Step title="Back up manifests before big changes">
    Keep copies of `skill-project.toml`, `skills.lock`, and any custom `.fastskill` config before bulk edits.
  </Step>
</Steps>

<Warning>
  Commands can change installed skills and manifest files. Try changes on a copy of the project or a branch first if you are unsure.
</Warning>