CLI Reference

Installation

Homebrew:

brew install forgecroft/tap/forgecroft

curl:

curl -sSfL https://install.forgecroft.com | sh

Both install the forgecroft-gate command onto your PATH. Verify with forgecroft-gate --version.

Authentication

The gate reads your API key from the FORGECROFT_API_KEY environment variable:

export FORGECROFT_API_KEY=fc_live_...

Create the key in the Forgecroft console under Settings → API keys. There is no login command — the environment variable is the only credential the gate needs. In continuous integration, store the key as a secret named FORGECROFT_API_KEY.

To point the gate at a non-default API base URL, pass --api-url or set api_url in a .forgecroft config file (see Configuration). To read the key from a different environment variable, set key_env in .forgecroft.

Usage

forgecroft-gate [flags]

With no diff-source flag, the gate evaluates your staged changes (git diff --cached) against your organization’s Controls and prints the verdict. It exits 0 unless the verdict is no_go or a finding is a blocker (then exit 1).

forgecroft-gate                        # evaluate staged changes (default)
forgecroft-gate --staged               # same, explicit
forgecroft-gate --range main..HEAD     # evaluate a commit range
forgecroft-gate --json                 # emit the verdict as JSON

Diff sources

At most one diff source may be given. If none is passed, --staged is the default.

Flag	Evaluates
--staged	git diff --cached — the staged changes (default)
--range <expr>	git diff <expr> — an arbitrary commit range, e.g. main..HEAD
--diff <file>	A unified diff read from a file, or - for stdin
--pre-push	The outgoing diff, reading the pushed refs from git’s pre-push hook stdin

Flags

Flag	Description
--staged	Evaluate the staged diff (the default when no source flag is given)
--range <expr>	Evaluate a commit range (e.g. main..HEAD)
--diff <file>	Evaluate a unified diff from a file, or - for stdin
--pre-push	Evaluate the diff from git’s pre-push hook stdin
--json	Emit the full verdict as JSON to stdout
--strict	Treat Forgecroft being unreachable as a failure (exit 2) instead of failing open
--autonomous	For unattended-agent use: same fail-closed-on-unreachable behavior as --strict, and a conditional_go verdict (needs human judgment) also exits non-zero, so an unattended run halts and surfaces instead of merging on a verdict that needed a human. A human running the gate at commit time doesn’t need this — they’re already the review. Also enabled by the FORGECROFT_AUTONOMOUS environment variable
--warn-only	Report the verdict but never exit non-zero on findings
--offline	Evaluate against the embedded best-practice packs only — no network call, no API key
--summary-file <path>	Write a Markdown summary of the verdict to a file (for a CI step summary or PR comment)
--api-url <url>	Override the API base URL (default https://api.forgecroft.com)
--config <path>	Path to the .forgecroft config file (default .forgecroft)
--version	Print the gate version

The key is resolved from FORGECROFT_API_KEY, or from the environment variable named by key_env in a .forgecroft file. Required scope: evaluate:read. Setting mode = warn in .forgecroft has the same effect as --warn-only.

Exit codes

Code	Meaning
0	Pass — go, conditional_go, or insufficient_context (unless --autonomous escalates a conditional_go, below)
1	Block — a no_go verdict, a finding at or above the severity floor, or (with --autonomous) a conditional_go verdict
2	Forgecroft was unreachable while --strict or --autonomous is set (fail-closed)

By default the gate fails open: if Forgecroft is unreachable, it passes rather than blocking. Pass --strict (or --autonomous) to fail closed (exit 2) instead. --autonomous additionally exits non-zero on a conditional_go verdict — --strict alone does not.

Configuration

The gate reads an optional .forgecroft file from the repository root (override the path with --config). It is a simple key = value file; every key is optional and absent keys fall back to the default. The API key is never stored here — it lives in an environment variable or CI secret.

# .forgecroft — all keys optional; shown with their defaults
# api_url = https://api.forgecroft.com   # Forgecroft API base URL
# key_env = FORGECROFT_API_KEY           # env var holding the API key
# mode = block                           # block (default) or warn (non-blocking)
# severity_floor = blocker               # blocker (default) or concern

JSON output

--json emits the full verdict to stdout. Read the top-level decision with jq:

# Evaluate the staged diff and read the verdict
forgecroft-gate --json | jq -r '.decision.verdict'

The verdict is one of go, conditional_go, no_go, or insufficient_context.

Gating CI on the verdict

Use forgecroft-gate to fail a CI job when a change violates a Control. It exits non-zero on a no_go verdict or a blocker finding:

# In a GitHub Actions step, on a pull request:
forgecroft-gate --range origin/${{ github.base_ref }}...HEAD

For a turn-key pull-request gate that also posts a sticky verdict comment, use the Forgecroft Gate GitHub Action — see CI Gate or CI Usage.

Ingesting evidence

The gate evaluates changes; it does not ingest evidence into your system map. To build or extend the map your Controls are checked against, ingest evidence through the Forgecroft console, or call the ontologize tool from a coding agent over MCP (Model Context Protocol). See Coding Agents.

Related

• API-First Quickstart — full curl-based setup walkthrough
• Go SDK — build custom integrations in Go
• API Keys — scope types, verb scopes, and key lifecycle