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

# Installation

> Install the Forst compiler via npm, .deb, Docker, or native binary.

Forst ships as a **native compiler** with an optional **npm wrapper** for Node/TypeScript workflows. Pick the path that matches how you deploy and develop: npm, Debian package, native binary, or Docker.

## npm (`@forst/cli`)

Best for teams already on Node.js, npm scripts, or monorepos with TypeScript clients.

Install the package:

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/languages/forst.json"]}}
npm install -D @forst/cli
```

After install, invoke the compiler via:

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/languages/forst.json"]}}
npx forst version
npx forst run path/to/file.ft
npx forst generate path/to/project
```

On first use, `@forst/cli` downloads the native `forst` binary for your platform from [GitHub Releases](https://github.com/forst-lang/forst/releases) and caches it locally.

### CI and offline environments

Set `FORST_BINARY` to a pre-installed executable path to skip the download step:

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/languages/forst.json"]}}
export FORST_BINARY=/usr/local/bin/forst
npx forst version
```

Other useful variables:

| Variable           | Purpose                                    |
| ------------------ | ------------------------------------------ |
| `FORST_BINARY`     | Path to a pre-installed `forst` executable |
| `FORST_CACHE_DIR`  | Override binary cache location             |
| `FORST_CLI_VERIFY` | Control checksum verification on download  |

Full details: [`@forst/cli` README](https://github.com/forst-lang/forst/tree/main/packages/cli#readme).

## Native binary

Download the release artifact for your OS/arch from [GitHub Releases](https://github.com/forst-lang/forst/releases), extract it, and add it to your `PATH`.

Verify the install:

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/languages/forst.json"]}}
forst version
forst run examples/in/basic.ft
```

Use this path when you do not need npm integration, for example pure Go modules or system wide installs.

## Debian / Ubuntu (.deb)

Best for system-wide installs on Debian or Ubuntu without npm. Installs `forst` to `/usr/bin`. Pick `amd64` or `arm64` from [GitHub Releases](https://github.com/forst-lang/forst/releases) when a compiler `v*` release ships.

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/languages/forst.json"]}}
wget https://github.com/forst-lang/forst/releases/download/v0.x.y/forst_0.x.y-1_amd64.deb
sudo apt install ./forst_0.x.y-1_amd64.deb
forst version
```

## Docker (GHCR)

Official multi-arch images are published on [GitHub Container Registry](https://github.com/orgs/forst-lang/packages) when a compiler `v*` release ships.

| Image                              | Use when                                                                      |
| ---------------------------------- | ----------------------------------------------------------------------------- |
| `ghcr.io/forst-lang/forst`         | Default — `forst` plus the Go toolchain (`run`, `test`, `generate`, `dev`, …) |
| `ghcr.io/forst-lang/forst-minimal` | Compiler only — smaller image when you do not need `go run` / `go test`       |

Pin the image tag to the compiler release (for example `v0.1.0`). `latest` tracks the latest stable compiler release.

**Generate TypeScript types in CI:**

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/languages/forst.json"]}}
docker run --rm -v "$PWD:/workspace" -w /workspace \
  ghcr.io/forst-lang/forst:v0.x.y generate ./my-service
```

**Run Forst tests:**

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/languages/forst.json"]}}
docker run --rm -v "$PWD:/workspace" -w /workspace \
  ghcr.io/forst-lang/forst:v0.x.y test ./...
```

**Dev server:**

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/languages/forst.json"]}}
docker run --rm -p 8080:8080 -v "$PWD:/workspace" -w /workspace \
  ghcr.io/forst-lang/forst:v0.x.y dev --port 8080 --root .
```

The default image includes Go for transpile-and-run workflows. Use `forst-minimal` only when you want a smaller image and will not call `forst run` or `forst test`. Generated Go for production deploys still requires `go build` in your own image if you only transpile to `.go` files.

## Editor support

For diagnostics, hover, go-to-definition, and formatting in VS Code, install the Forst extension and run the language server. See [Editor workflow](/docs/workflow/editor).

## Verify your install

Confirm the compiler is on your PATH:

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/languages/forst.json"]}}
forst version
forst run --help
```

You should see version output and subcommand help. If the npm wrapper fails to download, check network access to `github.com` or set `FORST_BINARY`.

## Next

<Card title="Quickstart" icon="rocket" href="/docs/quickstart">
  Write and run your first validated handler.
</Card>