> ## 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.

# Installation Guide

> Install the FastSkill CLI: package manager and operational toolkit for Agent AI Skills (releases, installers, optional source build).

## System Requirements

Before installing FastSkill, ensure your system meets these requirements:

| Component          | Minimum Version          | Recommended                                               |
| ------------------ | ------------------------ | --------------------------------------------------------- |
| **OS**             | macOS, Linux, or Windows | Latest stable release                                     |
| **Memory**         | 512MB                    | 2GB+                                                      |
| **Storage**        | 100MB                    | 500MB+                                                    |
| **OpenAI API Key** | Optional                 | Required for embedding search / `reindex` with embeddings |

## CLI Installation

Pick one method. **Homebrew** (macOS and Linux) and **Scoop** (Windows) stay updated with releases; use **GitHub Releases** or the **install script** if you prefer a standalone binary.

<Tabs>
  <Tab title="Homebrew (macOS & Linux)">
    [Homebrew](https://brew.sh/) installs a pre-built `fastskill` on both **Apple Silicon** and **Intel** Macs, and on Linux where the tap ships bottles.

    ```bash theme={null}
    brew install gofastskill/cli/fastskill
    fastskill -V
    ```

    Details and formula updates live in the [gofastskill/homebrew-cli](https://github.com/gofastskill/homebrew-cli) tap repository.

    <Tip>
      If `brew install` fails with a tap error, run `brew update` and try again, or use the **GitHub Releases** or **install script** tab.
    </Tip>
  </Tab>

  <Tab title="Scoop (Windows)">
    [Scoop](https://scoop.sh/) installs `fastskill.exe` and keeps it on your PATH.

    ```powershell theme={null}
    scoop bucket add gofastskill https://github.com/gofastskill/scoop-bucket
    scoop install fastskill
    fastskill -V
    ```

    See [gofastskill/scoop-bucket](https://github.com/gofastskill/scoop-bucket) for manifest details.
  </Tab>

  <Tab title="Install script (Linux & macOS)">
    One-liner from the repository (detects OS, downloads a release binary, installs to `/usr/local/bin` or `~/.local/bin` if `sudo` is not available):

    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/gofastskill/fastskill/main/scripts/install.sh | bash
    ```

    Options (run `./install.sh --help` after downloading the script): `--user`, `--prefix DIR`, `--force`, and a version argument such as `./install.sh v0.9.16`.
  </Tab>

  <Tab title="GitHub Releases">
    Download a pre-built binary from [GitHub Releases](https://github.com/gofastskill/fastskill/releases). Replace `VERSION` with the tag you want (for example `0.9.16`; assets use `v${VERSION}` in the URL).

    <Steps>
      <Step title="macOS (Apple Silicon)">
        ```bash theme={null}
        VERSION="0.9.16"
        curl -fL "https://github.com/gofastskill/fastskill/releases/download/v${VERSION}/fastskill-aarch64-apple-darwin.tar.gz" -o fastskill.tgz
        tar -xzf fastskill.tgz
        sudo mv fastskill /usr/local/bin/
        fastskill -V
        ```

        Asset name: `fastskill-aarch64-apple-darwin.tar.gz`.
      </Step>

      <Step title="macOS (Intel)">
        ```bash theme={null}
        VERSION="0.9.16"
        curl -fL "https://github.com/gofastskill/fastskill/releases/download/v${VERSION}/fastskill-x86_64-apple-darwin.tar.gz" -o fastskill.tgz
        tar -xzf fastskill.tgz
        sudo mv fastskill /usr/local/bin/
        fastskill -V
        ```

        Asset name: `fastskill-x86_64-apple-darwin.tar.gz`.
      </Step>

      <Step title="Linux (x86_64, glibc, with git support)">
        ```bash theme={null}
        VERSION="0.9.16"
        curl -fL "https://github.com/gofastskill/fastskill/releases/download/v${VERSION}/fastskill-x86_64-unknown-linux-gnu.tar.gz" -o fastskill.tgz
        tar -xzf fastskill.tgz
        sudo mv fastskill /usr/local/bin/
        fastskill -V
        ```

        Requires a recent glibc (see release notes). For maximum portability (static binary, no bundled `git2`), use **`fastskill-x86_64-unknown-linux-musl.tar.gz`** instead and rely on system `git` for Git URLs.
      </Step>

      <Step title="Windows (zip)">
        Download `fastskill-x86_64-pc-windows-msvc.zip` from the release page, extract it, add the folder to **PATH**, then run:

        ```powershell theme={null}
        fastskill.exe -V
        ```
      </Step>
    </Steps>

    <Tip>
      Prefer a user-local path on macOS or Linux? Move `fastskill` to `~/.local/bin/` and ensure that directory is on your `PATH` instead of using `sudo`.
    </Tip>
  </Tab>
</Tabs>

**Skills Directory Resolution:**

The CLI automatically discovers the skills directory in this priority order:

1. `skills_directory` setting in `.fastskill/config.yaml`
2. Walk up directory tree to find existing `.claude/skills/`
3. Default to `.claude/skills/` in current directory

**Manifests and lockfiles:**

* Declare skills in `skill-project.toml` at project root (with `[dependencies]` section)
* Install with `fastskill install` (use `--without`/`--only` for groups)
* Lockfile is written to `skills.lock` at project root after installs
* Repository configuration is stored in `[tool.fastskill.repositories]` section of `skill-project.toml`

## Configuration

After installation, configure FastSkill by creating `.fastskill/config.yaml`:

```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"
```

**Note**: Service-level configuration (embedding settings) is stored in `.fastskill/config.yaml`. Project-level configuration (skill dependencies and repositories) is stored in `skill-project.toml` at your project root.

Set your OpenAI API key:

```bash theme={null}
export OPENAI_API_KEY="your-key-here"
```

## Docker (optional)

If you run tools in containers, install the same release archive inside your image (see the Linux steps above) or copy the `fastskill` binary into a minimal base image. Mount your project directory and set `OPENAI_API_KEY` when you use embedding search.

## Platform notes

### macOS

* **Recommended:** Homebrew tab above (`brew install gofastskill/cli/fastskill`) for both Apple Silicon and Intel.
* **Without Homebrew:** use the **GitHub Releases** tab for `aarch64` vs `x86_64` darwin archives, or the **install script** tab.

### Linux

* **Recommended:** Homebrew on Linux if you already use it, otherwise the **GitHub Releases** tab (`gnu` vs `musl` per release notes) or the **install script**.

### Windows

* **Recommended:** **Scoop** tab above.
* **Without Scoop:** download the **zip** from **GitHub Releases**, extract, add to PATH.
* **WSL:** install inside Ubuntu using the Linux or install-script options above.

## Verify the CLI

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

If you already have a project with `skill-project.toml`, try `fastskill list` or `fastskill install` from that directory.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Installation Issues">
    <Warning>
      **Homebrew**: If the tap is missing, install with `brew install gofastskill/cli/fastskill`. See [homebrew-cli](https://github.com/gofastskill/homebrew-cli) for issues.
    </Warning>

    <Warning>
      **Scoop**: Ensure the bucket was added (`scoop bucket list` should show `gofastskill`). See [scoop-bucket](https://github.com/gofastskill/scoop-bucket) if `scoop install fastskill` fails.
    </Warning>

    <Warning>
      **Binary not found in PATH**: After extracting a release archive, move `fastskill` (or add the folder containing `fastskill.exe`) to a directory on your PATH (`/usr/local/bin`, `~/.local/bin`, or Windows user PATH).
    </Warning>

    <Warning>
      **Permission denied (Linux)**: If you get permission errors, use `sudo` when moving to `/usr/local/bin/`, or install to `~/.local/bin/` instead and ensure it's in your PATH.
    </Warning>

    <Warning>
      **Windows security warning**: Windows may show a security warning for unsigned binaries. Click "More info" and then "Run anyway" if you trust the source.
    </Warning>
  </Accordion>

  <Accordion title="Configuration Issues">
    <Info>
      **Embedding configuration required**: Create `.fastskill/config.yaml` with OpenAI API configuration.
    </Info>

    <Info>
      **OpenAI API key not found**: Set `OPENAI_API_KEY` environment variable or configure in `.fastskill/config.yaml`.
    </Info>
  </Accordion>

  <Accordion title="Platform-Specific Problems">
    <Tip>
      **macOS security**: If you get security warnings, go to System Settings > Privacy & Security and allow the binary.
    </Tip>

    <Tip>
      **Windows antivirus**: If Windows blocks the downloaded binary, add an exception for the folder where you keep `fastskill.exe`.
    </Tip>
  </Accordion>
</AccordionGroup>

<Note>
  Still having issues? Check the [troubleshooting section](/troubleshooting).
</Note>