forge(1)

General Commands Manual

forge(1)

forge

A build tool that understands your project.

curl -fsSL https://forge.dev/install | sh

Synopsis

forge [command] [flags]
forge build [--target <name>] [--watch] [--release]
forge test [--parallel] [--coverage]
forge run <script> [args...]
forge clean [--all]

Description

forge is a polyglot build tool that reads your project structure and does the right thing. No config files for common cases. Convention over configuration, escape hatches when you need them.

It handles dependency resolution, incremental builds, parallel test execution, and artifact caching. Under the hood, it builds a DAG of your project's build graph and executes it with maximum parallelism.

Commands

build

Compile the project. Detects language and toolchain automatically. Supports Go, Rust, TypeScript, and C. Incremental by default — only rebuilds what changed.

--target <name> Build a specific target instead of the default
--watch Rebuild on file changes
--release Optimized build with stripping and LTO
--verbose, -v Print the full build graph and timing

test

Run project tests. Discovers test files by convention. Parallel by default with isolation between test suites.

--parallel <n> Max parallel test processes (default: CPU count)
--coverage Generate coverage report
--filter <pattern> Run only tests matching the pattern

run

Execute a project script or binary. Scripts are defined in forge.toml or auto-detected from ./scripts/.

<script> Name of the script or binary to run
[args...] Arguments passed through to the script

clean

Remove build artifacts. By default, keeps the dependency cache.

--all Also remove dependency cache and lockfiles

Configuration

Most projects need no configuration. For custom setups, create a forge.toml in your project root:

# forge.toml
[build]
target = "./cmd/server"
output = "./bin/server"

[build.flags]
ldflags = "-s -w"

[test]
parallel = 8
timeout  = "5m"

[scripts]
dev    = "forge build --watch & forge run server"
deploy = "./scripts/deploy.sh"

Examples

Build and run in watch mode:

$ forge build --watch

Run tests with coverage for a specific package:

$ forge test --coverage --filter "storage/*"

Release build with verbose output:

$ forge build --release -v

Environment

FORGE_CACHE_DIR Override the default cache directory (~/.cache/forge)
FORGE_JOBS Max parallel build jobs
FORGE_NO_COLOR Disable colored output