CLI reference

Install @forst/cli or a native binary (Installation), then compile a file:

npx forst path/to/hello.ft

The forst CLI transpiles .ft sources, runs programs, generates the TypeScript client package, and starts development services. Node apps that import @forst/gen also need the postinstall generate script. See Installation § Generated TypeScript client.

Default compile and run

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

Forst
Generated Go

package main

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

func main() {
	println(greet())
}

// forst build
package main

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

func main() {
	println(greet())
}

Run it with:

forst path/to/file.ft          # compile (same as run without executing)
forst run path/to/file.ft      # compile and run (go run)
forst build -o <dir> path/to/file.ft   # native program binary + manifest.json

Each command below writes a different artifact. Use this table to pick the workflow that matches what you need in your repo or container image.

Command	Output
`forst generate`	`@forst/gen` TypeScript client (default). Optional Go sources with `--go`
`forst build -o <dir>`	`bin/<entryStem>` + `manifest.json` (linked program binary)
`forst run`	Execute via `go run` (development / hostMode)
`forst dev` / `@forst/sidecar`	Live HTTP invoke with reload (development 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 a TypeScript client package from Forst sources:

forst generate .
forst generate ./my-service
forst generate -config ./ftconfig.json ./my-service
forst generate --watch .
forst generate --list --json .

Uses the same file discovery rules as forst dev. Import from @forst/gen/<package> after generate (and after postinstall on a fresh machine). Each directory holds one Forst package name, matching Go. You may put many .ft files in that directory when they share the same package line. files.include globs select which .ft files are discovered. They do not allow multiple package names in one folder or the same package name in sibling folders.

`--allow-stem-package-mismatch`

By default, forst generate expects the file stem or parent folder name to match the package line. Use this flag when legacy files break that rule and you cannot rename or move them yet.

Allows	Does not allow
`legacy_login.ft` with `package auth` when neither stem nor folder matches	Multiple package names in one directory
Skipping stem checks for the whole boundary	The same package name in sibling directories

Normal colocation does not need the flag. Put files under a folder named for the package (for example auth/login.ft with package auth). See Call Forst over HTTP § Colocate Forst with TypeScript. --list (with optional --json) prints a machine-readable manifest of packages and exported functions without writing client output. Use it for IDE plugins, codegen pipelines, or CI introspection. --watch regenerates when .ft files change. Use it when the dev server runs separately, or rely on regenerate-on-save from Dev server.

Output modes

Mode	`outDir`	Committed	Linked into `node_modules`
Ephemeral (default)	`.forst/client`	No	Yes (`node_modules/@forst/gen` → outDir)
Committed	for example `packages/forst-client`	Yes	No (`link: "auto"` skips linking outside `.forst`)

Ephemeral output is removed by forst clean and restored by the next generate. Committed mode is a normal workspace package you check in. See Plugins to configure JSON Schema, RPC contracts, file routes, or custom generators during forst generate. Plugins are work in progress—see that page for versioning and coverage limits.

Generate configuration

Set these under "generate" in ftconfig.json:

{
  "generate": {
    "packageName": "@forst/gen",
    "outDir": ".forst/client",
    "link": "auto",
    "emit": "js",
    "testingSubpath": "$testing",
    "effect": false,
    "ssrModule": ""
  }
}

Field	Type	Default	Purpose
`packageName`	`string`	`"@forst/gen"`	Name written into the generated `package.json` and used as the `node_modules` link name
`outDir`	`string`	`.forst/client`	Single output directory relative to the ftconfig boundary root
`link`	`"auto"` \| `"always"` \| `"never"`	`"auto"`	Whether to write the `node_modules` link. `auto` links when `outDir` is inside `.forst`
`emit`	`"js"`	`"js"`	Always emit built JS. `"ts"` is rejected
`testingSubpath`	`string`	`"$testing"`	Subpath key for the test scope (`@forst/gen/$testing`). Must start with `$` so it cannot collide with Forst package names
`effect`	`bool`	`false`	When `true`, every generated function returns an `Effect` instead of a `Promise`. See Effect mode
`ssrModule`	`string`	`""` (off)	Optional path for a legacy SSR wrapper module. Empty means do not write one
`go.entry`	`string`	`""`	Entry `.ft` for Go source emission (requires `go.out`)
`go.out`	`string`	`""`	Output `.go` path relative to the boundary root (requires `go.entry`)
`go.root`	`string`	`""`	Optional package root for Go source emission
`skipClient`	`bool`	`false`	Skip TypeScript client generation
`plugins`	`array`	`[]`	Semantic plugin executables run after typecheck (work in progress). See Plugins

Each plugin entry:

Field	Type	Required	Purpose
`name`	`string`	yes	Identifier passed to the plugin in the snapshot
`cmd`	`string`	yes	Executable name (`PATH`) or path (`./bin/...` relative to boundary root)
`out`	`string`	yes	Output directory relative to the boundary root
`opt`	`object`	no	Plugin-specific JSON options

Optional Go sources (`generate.go`)

By default, forst generate writes only the TypeScript client (postinstall safe). Go sources run when generate.go.entry and generate.go.out are set in ftconfig.json, or when you override on the CLI with matching flag names. TS client + Go sources (default):

forst generate --go-entry=./main.ft --go-out=./out/main.go .

Writes @forst/gen and transpiled .go beside the output path. Go sources only:

forst generate --go-out=./out/main.go --go-entry=./main.ft --skip-client .

Skips TypeScript client generation. Use when you only want inspectable Go for go build or review. CLI flags mirror ftconfig fields (--go-entry, --go-out, --go-root, --skip-client). Unset flags fall back to ftconfig.json. Or configure in ftconfig.json:

{
  "generate": {
    "skipClient": true,
    "go": {
      "entry": "./main.ft",
      "out": "./out/main.go",
      "root": "."
    }
  }
}

Go source emission does not link a native binary. Use forst build for production linked programs.

Native program build (`forst build`)

Build a linked program binary and manifest.json for slim container images (similar to go build -o bin/main). Local build (writes under .forst/, removed by forst clean):

forst build -root . -o .forst/build -- ./app/main.ft

Cross-compile for Linux containers (writes to a path you copy into the image):

forst build -root . -o dist --goos linux --goarch amd64 -- ./app/main.ft

-o is the output directory. Forst writes manifest.json and bin/<entryStem> directly inside it. No extra subfolder is required. Output layout (entry ./app/main.ft → bin/main):

.forst/build/
  manifest.json
  bin/main

Requires server.embedded: true in ftconfig.json. At runtime, run the linked binary with FORST_ROOT set to your project root (read binary from manifest.json):

FORST_ROOT=/app /app/.forst/build/bin/main

How the binary fits with Node

When bridge.hostMode is enabled, the built binary can run Forst and talk to Node in one of two layouts. All-in-one (default): One process runs your Forst entry point, starts the small HTTP server that @forst/gen uses to call Forst functions, and starts your Node app (for example remix-serve) as a child process:

bin/main
  ├─ HTTP server for @forst/gen (.forst/invoke.ready)
  └─ Node app child (bridge.binary + bridge.args)
       └─ @forst/gen calls Forst over HTTP

Split layout (FORST_SKIP_NODE_HOST=1): Use the same binary when Node already runs somewhere else (another container, systemd unit, or local dev process). Set FORST_SKIP_NODE_HOST=1 so the binary runs embedded invoke and your entry point but does not spawn the Node host. Your Node app runs on its own and connects using @forst/gen and the URL in .forst/invoke.ready. forst build does not wait for the Node HTTP app to finish starting.

`manifest.json` (build output)

manifest.json sits beside the linked binary under your -o directory. Use these fields to verify how the program was built and which executable to run in production.

Field	Meaning
`kind`	`"program"` — embedded program binary, not a separate invoke daemon
`binary`	Relative path to the linked executable (from entry stem)
`hostMode`	`bridge.hostMode` from `ftconfig.json` at build time
`embeddedInvoke`	Always `true` for `forst build`
`boundaryRoot`	Project root used at build time
`needsBridgeRuntime`	`true` when the program embeds bridge interop
`compiledModulesDir`	Relative compiled modules path when bridge imports use compiled format
`legacyModuleFormat`	`compiled` or `typescript` from `bridge.legacyModules.format` at build time
`contractVersion`	Invoke HTTP contract version

Older manifests may show "kind": "invoke" and "binary": "bin/forst-invoke". Task pages link here instead of repeating this table.

`forst dev`

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

forst dev -root ./my-service -port 8080
forst dev -config ./ftconfig.json -root .

See Dev server.

`forst lsp`

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

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:

forst fmt path/to/file.ft

`forst test`

Run Forst tests (discovery and emit bridge):

forst test ./...

`forst dump`

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

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, the generated client, native build output under .forst/build/, test emit dirs, executor temp modules, nodert sockets, invoke ready markers). User config such as .forst-gomod/ is not removed.

forst clean
forst clean -root ./my-service
forst clean -dry-run

After forst clean, run forst generate (or rely on postinstall) to restore @forst/gen.

`forst version`

Print compiler version info:

forst version
forst --version

Prints semver, commit, and build date.

npm wrapper

When installed via @forst/cli:

npx forst run hello.ft
npx forst --forst-cli-info    # package version, binary path, compiler version

Set FORST_BINARY to skip download in CI.

Installation

npm, binary, Docker, and the generated client setup.

Generate a TypeScript client

@forst/gen imports and layout.

Dev server

HTTP contract and regenerate on save.

Quickstart

First commands in context.

Editor workflow

LSP integration in VS Code.

Overview

Getting started

Data validation

Behavior

Interoperability

Workflow

CLI reference

Default compile and run

`forst generate`

`--allow-stem-package-mismatch`

Output modes

Generate configuration

Optional Go sources (`generate.go`)

Native program build (`forst build`)

How the binary fits with Node

`manifest.json` (build output)

`forst dev`

`forst lsp`

`forst fmt`

`forst test`

`forst dump`

`forst clean`

`forst version`

npm wrapper

Installation

Generate a TypeScript client

Dev server

Quickstart

Editor workflow

​Default compile and run

​forst generate

​--allow-stem-package-mismatch

​Output modes

​Generate configuration

​Optional Go sources (generate.go)

​Native program build (forst build)

​How the binary fits with Node

​manifest.json (build output)

​forst dev

​forst lsp

​forst fmt

​forst test

​forst dump

​forst clean

​forst version

​npm wrapper

​Related

Installation

Generate a TypeScript client

Dev server

Quickstart

Editor workflow

Default compile and run

`forst generate`

`--allow-stem-package-mismatch`

Output modes

Generate configuration

Optional Go sources (`generate.go`)

Native program build (`forst build`)

How the binary fits with Node

`manifest.json` (build output)

`forst dev`

`forst lsp`

`forst fmt`

`forst test`

`forst dump`

`forst clean`

`forst version`

npm wrapper

Related