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

# CLI reference

> forst run, build, generate, dev, lsp, and other commands.

The **`forst`** CLI transpiles `.ft` sources, runs programs, generates TypeScript output, and starts development services. Install via [`@forst/cli`](/docs/installation) or a native binary.

## Default compile and run

With no subcommand, `forst` compiles a single `.ft` file. Given `hello.ft`:

<Tabs>
  <Tab title="Forst">
    ```ft theme={"languages":{"custom":["/languages/forst.json"]}} theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/languages/forst.json"]}} theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/languages/forst.json"]}} theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/languages/forst.json"]}} theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/languages/forst.json"]}} theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/languages/forst.json"]}} theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/languages/forst.json"]}}
    package main

    func greet(): String {
    	return "Hello, World!"
    }

    func main() {
    	println(greet())
    }
    ```
  </Tab>

  <Tab title="Generated Go">
    ```go theme={"languages":{"custom":["/languages/forst.json"]}} theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/languages/forst.json"]}} theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/languages/forst.json"]}} theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/languages/forst.json"]}} theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/languages/forst.json"]}} theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/languages/forst.json"]}} theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/languages/forst.json"]}}
    // forst build
    package main

    func greet() string {
    	return "Hello, World!"
    }

    func main() {
    	println(greet())
    }
    ```
  </Tab>
</Tabs>

Run it with:

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/languages/forst.json"]}}
forst path/to/file.ft          # compile
forst run path/to/file.ft      # compile, build, and run
forst build path/to/file.ft    # compile and build only
```

Common flags (see `forst --help`):

| Flag                    | Purpose                                                          |
| ----------------------- | ---------------------------------------------------------------- |
| `-root <dir>`           | Merge same-package `.ft` files under a directory tree            |
| `-export-struct-fields` | Emit exported struct fields with `json` tags for `encoding/json` |
| `-log-level`            | `trace`, `debug`, `info`, `warn`, `error`                        |
| `-watch`                | Recompile on file changes                                        |

## `forst generate`

Emit TypeScript declarations and client stubs from Forst sources:

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/languages/forst.json"]}}
forst generate ./my-service
forst generate ./handlers/orders.ft
forst generate -config ./ftconfig.json ./my-service
```

Uses the same file discovery rules as `forst dev`. Output typically lands in `generated/` and `client/` relative to the target.

## `forst dev`

Start the HTTP development server for function discovery, invocation, and types:

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/languages/forst.json"]}}
forst dev -root ./my-service -port 8080
forst dev -config ./ftconfig.json -root .
```

See [Dev server](/docs/workflow/dev-server).

## `forst lsp`

Start the language server (JSON-RPC over HTTP on `POST /`):

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/languages/forst.json"]}}
forst lsp -port 8081 -log-level info
```

Used by the VS Code extension. This is HTTP LSP rather than stdio. Other editors need a similar bridge.

## `forst fmt`

Format `.ft` sources:

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

## `forst test`

Run Forst tests (discovery and emit bridge):

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

## `forst dump`

Debug compiler phases (lexer, parser, typechecker, transformer):

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/languages/forst.json"]}}
forst dump --file path/to/file.ft --format pretty
forst dump --file path/to/file.ft --phase typechecker
```

Useful when reporting compiler bugs.

## `forst clean`

Remove compiler-generated artifacts under `.forst/` (run sandboxes, test emit dirs, executor temp modules, nodert sockets, invoke ready markers). User config such as `.forst-gomod/` is not removed.

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/languages/forst.json"]}}
forst clean
forst clean -root ./my-service
forst clean -dry-run
```

## `forst version`

Print compiler version info:

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

Prints semver, commit, and build date.

## npm wrapper

When installed via `@forst/cli`:

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/languages/forst.json"]}}
npx forst run hello.ft
npx forst --forst-cli-info    # package version, binary path, compiler version
```

Set **`FORST_BINARY`** to skip download in CI.

## Related

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/docs/quickstart">
    First commands in context.
  </Card>

  <Card title="Editor workflow" icon="code" href="/docs/workflow/editor">
    LSP integration in VS Code.
  </Card>
</CardGroup>