Skip to content
Anvil Anvil

CLI Reference

Install the Anvil CLI from the main module:

Terminal window
go install github.com/TDB-Group/anvil/cmd/anvil@latest
anvil --help

generate

Section titled “generate”
Terminal window
anvil generate [project-dir] [output-file] [package-pattern...]

Reads anvil.yaml, scans configured packages, validates the graph, and writes generated Go code.

Use --profile <name>, --profile=<name>, or -p <name> to apply profiles.<name>. ANVIL_PROFILE can also select a profile; the CLI flag wins when both are present.

The command runs parser diagnostics, compiles the manifest, runs built-in manifest rules and configured Starlark rules, then writes generated code. Rule errors fail the command. Rule warnings are not printed during generate; run anvil lint when you want warning output.

Parser diagnostics are stricter than rule diagnostics for this command. If the scan stage reports any diagnostic, including a warning, generate stops before the manifest and generated file are written.

On success, the command prints:

generated <output-file>

Usage errors exit with code 2. Runtime or compiler failures exit with code 1.

Package patterns after [output-file] override configured scan patterns for that run.

If [output-file] ends with .go, Anvil writes exactly that file. Otherwise the value is treated as an output directory and the generated file is named anvil_autogenerated.go.

generator.package in anvil.yaml wins when Anvil chooses the generated Go package name. If it is not set, the package name is derived from the output directory.

scan

Section titled “scan”
Terminal window
anvil scan [project-dir]

Runs package loading and parser diagnostics without writing generated files. Use it when you want fast feedback while changing route declarations.

scan is a direct parser check for the supplied directory. It does not apply anvil.yaml scan patterns or profiles. Use generate, manifest, or lint when you need the full config-aware compiler pipeline.

scan prints parser warnings and exits successfully when there are no parser errors. It reads only the first positional directory argument.

manifest

Section titled “manifest”
Terminal window
anvil manifest [project-dir] [package-pattern...]

Produces deterministic route manifest output for tooling.

Package patterns after [project-dir] override configured scan patterns.

manifest is config-aware and supports --profile. It compiles the manifest but does not run built-in or Starlark rules. It also overlays a minimal generated package while loading packages so imports of the generated package can resolve without writing files.

The command stops when package loading fails or the parser reports any diagnostic, including warnings. It only writes manifest JSON from a clean scan.

Profile forms are --profile <name>, --profile=<name>, -p <name>, and ANVIL_PROFILE.

openapi

Section titled “openapi”
Terminal window
anvil openapi [project-dir] [package-pattern...] > openapi.json

Produces OpenAPI output from the compiled manifest.

Package patterns after [project-dir] override configured scan patterns.

The command uses the same manifest pipeline as anvil manifest, then converts HTTP routes to OpenAPI 3.1.0 JSON and validates the document before writing it. The CLI has no title or version flags. It writes Anvil API as the document title and 0.0.0 as the document version. It does not run built-in or Starlark compiler rules.

Like manifest, openapi stops on any parser diagnostic before producing JSON.

Profile forms are --profile <name>, --profile=<name>, -p <name>, and ANVIL_PROFILE.

lint

Section titled “lint”
Terminal window
anvil lint [project-dir] [--rule file.star...]

Runs built-in manifest rules, configured Starlark rules, and extra --rule files. --rule uses the separated form, such as --rule ./rules/team.star. It prints warnings and errors, then exits non-zero when at least one error exists.

lint still needs a valid manifest. Package loading failures and parser diagnostics stop the command before manifest rules run. Rule warnings print and exit successfully when there are no rule errors.

Rule order is deterministic: built-in rules first, compiler.rules next, stage rules in sorted stage-name order, then extra --rule files in CLI order.

Profile forms are --profile <name>, --profile=<name>, -p <name>, and ANVIL_PROFILE.

testbed

Section titled “testbed”
Terminal window
anvil testbed [project-dir] [flags]
anvil testbed [project-dir] --base-url http://127.0.0.1:8080
anvil testbed [project-dir] --script ./tools/anvil/projects.yaml
anvil testbed [project-dir] --stress 25 --seed 42

Generates or runs testbed cases from the manifest and optional scripts. It does not run built-in or Starlark compiler rules.

The command compiles a clean manifest first. Package loading failures and parser diagnostics stop the command before generated or scripted cases are created.

--base-url executes HTTP and GraphQL cases against a running server. The CLI runner does not execute WebSocket, gRPC, or queue cases directly; those execution paths live in the matching driver packages because they need protocol-specific clients and descriptors.

--run-generated includes generated shape cases when executing scripts. --stress <n> appends deterministic generated HTTP cases per route and must be non-negative. --seed <n> controls the deterministic stress input generator. Additional --script <file> values are appended after configured testbed.scripts. Stress cases are added before user scripts are merged.

Accepted flag forms:

  • --script <file> only. --script=<file> is not accepted.
  • --base-url <url> and --base-url=<url>.
  • --stress <n> and --stress=<n>.
  • --seed <n> and --seed=<n>.
  • --run-generated.

Profile forms are inherited from the manifest parser: --profile <name>, --profile=<name>, -p <name>, and ANVIL_PROFILE.

dev

Section titled “dev”
Terminal window
anvil dev [project-dir] [flags]

Runs the configured development command from anvil.yaml.

Flags:

  • --once: Generate once and run the command once.
  • --no-generate: Run without regenerating first.
  • --poll <duration>: Set the file-watch polling interval. The default is 1s. The value must be a positive Go duration, such as 500ms, 1s, or 2m.

--poll uses the separated form. --poll=1s is not accepted.

Profile forms are --profile <name>, --profile=<name>, -p <name>, and ANVIL_PROFILE.

When no dev command is configured, Anvil runs go run <main package>.

Command selection order:

  1. commands.dev from anvil.yaml
  2. dev.run or dev.argv
  3. go run <main package>

Watch mode skips .git, vendor, node_modules, bin, dist, and the configured generated output directory. Watched extensions default to .go, .yaml, .yml, and .env.

build

Section titled “build”
Terminal window
anvil build [project-dir] [flags]

Generates wiring and builds the configured main package.

Flags:

  • --output <path> or -o <path>: Override build.output.
  • --tags <a,b>: Append Go build tags to build.tags.

--output and --tags use separated values. --output=... and --tags=... are not accepted.

Profile forms are --profile <name>, --profile=<name>, -p <name>, and ANVIL_PROFILE.

The build command always regenerates wiring before invoking go build. Output path precedence is --output, then build.output, then bin/<project-name> under the configured work directory.

On Windows, the default binary name receives .exe when the project name has no file extension.

run

Section titled “run”
Terminal window
anvil run <command> [project-dir]

Runs a named command from anvil.yaml.

Command arguments are executed exactly as configured. argv runs without a shell. run executes through cmd /C on Windows and sh -c elsewhere.

A named command must define exactly one of argv or run. It can also define environment variables that are merged into the process environment.

anvil run supports profiles through --profile <name>, --profile=<name>, -p <name>, and ANVIL_PROFILE before loading the named command.

anvil run does not forward extra positional arguments to the named command. Put command arguments in commands.<name>.argv or commands.<name>.run.

new

Section titled “new”
Terminal window
anvil new <dir> [module]

Creates a starter project using the active Anvil module path.

The target directory must be new or empty. The optional module argument must be a valid Go module path containing a dot, such as example.com/portal.

The generated project includes go.mod, anvil.yaml, a standard-library HTTP driver setup, health and project routes, a memory store, environment config, and a small error observer.

On success, the command prints:

created <dir>
module <module>

Anvil uses github.com/TDB-Group/anvil as its module path by default. Forks and local development builds can set ANVIL_MODULE_PATH before running the CLI when generated imports need to point at another module path.

Keep this page aligned with anvil --help. When help text changes, update the docs in the same change.