CLI Reference

Forge ships as a single binary: forge. All subcommands follow the form forge <subcommand> [flags].

A global --log-level flag (values: trace, debug, info, warn, error) is accepted by every subcommand and overrides the config file value. The default is info.

Exit codes: 0 for success, 1 for any error (the error message is printed to stderr).

forge index

Index a repository. Performs an incremental index by default; use --full to wipe and re-index from scratch.

forge index <path> [flags]

Flag	Type	Default	Description
`path`	string (positional)	—	Path to the repository root. Required.
`--full`	bool	false	Wipe the existing index and re-index from scratch.
`--with-search`	bool	false	Build the Tantivy full-text search index after AST indexing. Required before `forge search` and `forge_search` work.
`--with-git`	bool	false	Ingest git commit history after AST indexing. Equivalent to running `forge ingest-git` afterward.
`--max-commits`	integer	1000	Maximum git commits to ingest when `--with-git` is set.
`--with-embeddings`	bool	false	Generate vector embeddings for semantic search. Requires `--with-search`. Embedding failure is non-fatal. (Requires `embeddings` build feature.)
`--cache-to`	string	—	Push the built index to R2 team cache. Format: `r2://<team_id>/<cache-key>`. Requires Team tier.
`--use-cache`	string	—	Fetch index from R2 team cache before indexing; skips rebuild on hit. Format: `r2://<team_id>/<cache-key>`. Requires Team tier.

Examples:

# Incremental index with search support
forge index . --with-search

# Full re-index including git history
forge index /my/repo --full --with-search --with-git

# CI: use cached index if available, push new cache after
forge index . --use-cache r2://team_abc123/main --cache-to r2://team_abc123/main

Expected output:

Indexed 622 files in 2.6s (incremental)
Search index built: 622 chunks

forge serve

Start the Forge MCP stdio server. Exposes all tools over JSON-RPC 2.0 on stdin/stdout.

forge serve [path] [flags]

Flag	Type	Default	Description
`path`	string (positional)	current directory	Path to the repository root.
`--watch`	bool	false	Enable background file watching; triggers incremental re-index on file save.
`--dashboard`	bool	false	Start the local web dashboard alongside the MCP server. Requires Solo tier or higher.

Examples:

forge serve .
forge serve /my/repo --watch

forge status

Show current index statistics for a repository.

forge status [flags]

Flag	Type	Default	Description
`--repo`	string	current directory	Path to the repository.

Expected output:

Repository: /my/repo
Files indexed: 622
Last indexed: 2026-04-16 10:30 UTC
Stale files: 0
Git history: available (1000 commits)
License: Solo — p***[email protected] (expires 2027-04-15)

forge health

Run health checks and print findings grouped by severity.

forge health [flags]

Flag	Type	Default	Description
`--repo`	string	current directory	Path to the repository.
`--no-secret-scan`	bool	false	Disable the secret-scanning health check.

Exit codes: 0 for no findings or warnings/info only; 1 for any P0 (critical) or P1 (error) findings.

Expected output:

P0 Critical: 0
P1 Error:    1
  [ERROR] broken_imports: src/api/handler.ts imports '../models/user' which does not exist
P2 Warning:  3
P3 Info:     5

forge map

Generate an architecture map for a repository.

forge map [flags]

Flag	Type	Default	Description
`--repo`	string	current directory	Path to the repository.
`--output`	string	stdout	Output file path.

Example:

forge map --repo . --output terrain/ironpine-labs/architecture.md

forge search

Full-text search across indexed code chunks. Understands camelCase and snake_case: searching payment finds processPayment, payment_handler, and PaymentService.

Requires the search index (run forge index --with-search first).

forge search <query> [flags]

Flag	Type	Default	Description
`query`	string (positional)	—	Keywords. Supports AND/OR and quoted phrases.
`--repo`	string	current directory	Path to the repository.
`--language`	string	—	Restrict to a language: `typescript`, `rust`, `python`, `go`.
`--chunk-type`	string	—	Restrict to a chunk type: `function`, `class`, `interface`, `module_header`.
`--limit`	integer	10	Maximum results to return.

Example:

forge search "payment handler" --language typescript --limit 5

forge pattern

Structural AST pattern search using $VAR wildcards for single-node matches and $$$VAR for multi-node spreads.

forge pattern <pattern> [flags]

Flag	Type	Default	Description
`pattern`	string (positional)	—	Code pattern to search for.
`--repo`	string	current directory	Path to the repository.
`--language`	string	—	Restrict to a language.
`--limit`	integer	20	Maximum results to return.

Examples:

forge pattern 'console.log($$$ARGS)'
forge pattern 'async function $NAME($$$PARAMS) { $$$BODY }'
forge pattern 'fn $NAME($$$) -> Result<$$$, $$$> { $$$BODY }' --language rust

forge ingest-scip

Ingest a SCIP index file. Upgrades heuristic import edges to compiler-resolved edges. Requires Pro tier or higher.

forge ingest-scip <path> [flags]

Flag	Type	Default	Description
`path`	string (positional)	—	Path to the SCIP index file (typically `index.scip`).
`--repo`	string	directory containing the SCIP file	Repository root path.

forge ingest-coverage

Ingest test coverage data. Auto-detects LCOV, Istanbul JSON, or Cobertura XML.

forge ingest-coverage <path> [flags]

Flag	Type	Default	Description
`path`	string (positional)	—	Path to the coverage file.
`--repo`	string	current directory	Repository root, used to resolve relative file paths in the report.

forge ingest-git

Ingest git commit history. Populates the commits and file_changes tables; enables forge_git_history, forge_git_blame, and hotspot analysis.

forge ingest-git [flags]

Flag	Type	Default	Description
`--repo`	string	current directory	Path to the repository.
`--max-commits`	integer	1000	Maximum commits to ingest.

forge git-blame

Show git blame for a file, grouped by commit section.

forge git-blame <file> [flags]

Flag	Type	Default	Description
`file`	string (positional)	—	File path (relative to the repository root or absolute).
`--repo`	string	current directory	Repository path.

forge warmup-model

Pre-download the embedding model without running inference. Run once before forge index --with-embeddings to avoid blocking on a download. (Requires embeddings build feature.)

forge warmup-model [flags]

Flag	Type	Default	Description
`--model`	string	`nomic-embed-text-v1.5`	Model name to download and verify.

forge setup

Set up the embedding runtime. Downloads and configures Ollama and the embedding model automatically. Safe to re-run. (Requires embeddings build feature.)

forge setup [flags]

Flag	Type	Default	Description
`--bundle-path`	string	—	Path to an offline bundle directory. When provided, installs from the bundle instead of downloading from the internet.

forge bundle

Create or install an offline embedding bundle for air-gapped installations. (Requires embeddings build feature.)

forge bundle create

forge bundle create [flags]

Flag	Type	Default	Description
`--output`	string	`forge-embedding-bundle.tar.gz`	Output path for the bundle tarball.

forge bundle install

forge bundle install <path>

Argument	Type	Description
`path`	string (positional)	Path to a bundle tarball produced by `forge bundle create`.

forge activate

Activate a Forge license key or team invite token. License key validation is performed entirely offline (Ed25519 signature check); no network call is made. Team invite activation exchanges the token with the admin portal API.

forge activate [<key>] [flags]

Flag	Type	Default	Description
`key`	string (positional)	—	License key from your purchase email. Mutually exclusive with `--team`.
`--team`	string	—	Team invite token provided by your team admin.

Example:

forge activate eyJrZXkiOi....<signature>
forge activate --team invite_abc123

Expected output:

License activated.
  Tier:     Solo
  Email:    p***[email protected]
  Features: dashboard, plugins, semantic_search, workflow_tools
  Expires:  2027-04-15

forge license

Show the current license status, masked email, features, and expiry date.

forge license

No flags. Shows community-mode feature summary if no license is installed.

forge update

Check for or install binary updates from https://downloads.forge.ironpinelabs.com.

forge update [flags]

Flag	Type	Default	Description
`--check`	bool	false	Only print the available version and URL; do not download.

forge stats

Show local usage statistics from ~/.forge/stats.json. Data never leaves the machine.

forge stats [flags]

Flag	Type	Default	Description
`--json`	bool	false	Output raw JSON instead of a human-readable table.
`--reset`	bool	false	Reset all statistics (prompts for confirmation).

forge ci

Run Forge in CI mode: index, health check, output annotations in CI platform formats, exit non-zero on P0 findings. Requires Pro tier or higher.

forge ci [flags]

Flag	Type	Default	Description
`--repo`	string	`.`	Repository path.
`--format`	string	`auto`	Output format: `github`, `gitlab`, `azure`, or `auto` (detects from CI environment variables).
`--fail-on-p0`	bool	false	Exit with code 1 if any P0 finding is present.
`--team`	string	—	Team ID for automatic R2 index cache usage. Requires Team tier.

forge upgrade

Open the pricing and trial page in the default browser. On headless systems (no DISPLAY or WAYLAND_DISPLAY), prints the URL to stdout instead.

forge upgrade

No flags.

forge deactivate

Remove this machine’s license association. Use when replacing a laptop or decommissioning a development machine.

forge deactivate [flags]

Flag	Type	Default	Description
`--yes`	bool	false	Confirm deactivation without an interactive prompt.

forge config heartbeat show

Display the heartbeat status, last check time, cached result, and the exact payload transmitted. Nothing is sent by running this command.

forge config heartbeat show

forge config heartbeat now

Force an immediate heartbeat, bypassing the weekly schedule. Use after re-subscribing or to test connectivity. Exits non-zero if the heartbeat fails.

forge config heartbeat now

forge licenses

Display or export third-party software attribution notices.

forge licenses [flags]

Flag	Type	Default	Description
`--html`	bool	false	Write the full `LICENSES.html` attribution document to disk.
`--text`	bool	false	Print condensed text attribution (license names and crate counts).
`--output`	string	`./LICENSES.html`	Output path for `--html` mode.

Examples:

forge licenses                         # Print summary to stdout
forge licenses --text                  # Condensed attribution text
forge licenses --html                  # Write LICENSES.html to current directory
forge licenses --html --output /tmp/   # Write to a specific path