CLI reference
This reference describes CLI 1.4.22 and later. Older releases can have different
flags and tool-version requirements; check the installed command's
--help. See Release channels.
Start with Setup to connect a coding tool.
Getting help
Every command accepts --help.
forgebench --help
forgebench run --helpTo check the installed version, run forgebench --version.
See Release channels for the
stable and preview channels. Guided setup and automatic-linking
options described here depend on the installed version and deployment.
Setup
Run forgebench setup in a terminal to select tools, then choose
session sync, model routing or MCP tools by number. Routing reuses a matching
chat:write credential or offers browser authorization. If browser
authorization fails or is declined, enter a key privately or leave it blank to
skip routing.
No --gateway flag or separate gateway command is needed.
Guided, opt-in setup. In a terminal with no flags, with any of --mcp,
--dry-run, --fresh or --verify-inference, or with --url, --since,
--funding or --paid-fallback-max-usd alone, it runs the guided journey in
Setup. Passing any of --tool,
--install-hooks, --sync-now, --gateway, --gateway-only,
--opencode-gateway, --associate-sessions, --advanced, --no-preview,
--key or --capture without a guided flag (--mcp, --dry-run, --fresh,
--verify-inference) keeps the scripted path.
# Guided setup
forgebench setup
# Preview the changes without making them
forgebench setup --dry-run
# Ask about automatic sync and the first upload separately
forgebench setup --advanced
# Non-interactive: sign in first, then configure one tool and upload
forgebench login
forgebench setup --tool claude_code --since 30d --install-hooks --sync-now| Flag | Description |
|---|---|
--tool claude_code | Select a tool. Repeat it to select several. Required when setup is not run in an interactive terminal. Accepted values: claude_code, codex, cursor, antigravity, github_copilot, opencode. |
--url https://app.forgebench.ai | The ForgeBench app URL for your environment. The guided flow asks for it on the first screen. Changing the URL clears saved selections and verification for the new URL; changing the workspace clears previous verification while keeping your selections. A URL that contains a username or password is refused with exit code 2 on every guided run, before anything changes. |
--since 7d | History to preview and upload once. Accepted values: 3d, 7d (default), 30d, 90d. |
--key | Enter an API key privately and check it against the setup URL. |
--opencode-gateway | Configure OpenCode to use the ForgeBench gateway models available to you. |
--associate-sessions | With a guided flag, selects Sync coding sessions. Opt in to automatic sync and native usage setup. For Claude Code it also adds optional context hooks that never block a session. |
--no-preview | Skip the local preview. |
--sync-now | Upload the selected tools after the preview. Requires a stored login. |
--install-hooks | With a guided flag, selects Sync coding sessions. Enable automatic session-end sync for the selected tools. Antigravity has no session-end hook; use schedule for it. |
--gateway | With a guided flag, selects Use ForgeBench for model requests. Requires chat:write. Funding is api-only unless you also pass --funding, with --paid-fallback-max-usd for subscription-first. |
--funding MODE | Gateway funding mode: api-only (default), subscription-only, or subscription-first. subscription-only and subscription-first require --gateway (exits with 2 without it); --funding api-only on its own is accepted and changes nothing. Subscription modes (subscription-only and subscription-first) are refused with exit code 2 for tools other than Claude Code and Codex. |
--paid-fallback-max-usd USD | Positive USD cap for paid fallback when --funding subscription-first is selected. Requires --gateway and --funding subscription-first (exits with 2 otherwise). |
--gateway-profile PROFILE | Gateway routing profile name. Requires --gateway (exits with 2 without it). |
--mcp | Connect ForgeBench tools (the hosted MCP server) to the selected tools. |
--dry-run | Preview the guided setup changes and write nothing. Makes read-only requests with the saved gateway key for the routing policy and model list. |
--fresh | Discard saved guided-setup answers; installed setup is left alone. |
--verify-inference | Send one one-token model request to confirm routing works. |
--advanced | Choose automatic sync and upload separately instead of the single yes/no prompt. |
--status | Show the selected tools and hook status, plus the guided-setup state when there is any. |
--uninstall | Remove the session-end hooks, clear the selected tools and, when hook uninstall succeeds, delete the saved guided-setup answers. |
In the guided journey, preflight asks Apply these changes? [y/N] only when at
least one row will apply; when everything selected is already set up, it prints
Nothing to do: everything selected is already set up and skips the prompt.
Deselecting an already-installed feature on a rerun leaves it installed and
prints its exact removal command:
forgebench hooks uninstall --tool <tool>,
forgebench gateway remove --tool <tool> --forgebench-url <url>, or
forgebench mcp remove --tool <tool> --scope user --forgebench-url <url>.
When a step fails, Not completed: prints its fix command and lists the
steps that remain applied. Next: prints the recovery command or console
link. The link uses the workspace URL when its name is available.
First use: keeps configuration and delivery separate. Sync is verified from the server's per-tool upload count for the signed-in person; it does not identify the uploading device or CLI build. The optional inference test checks the gateway. It does not prove that a native client loaded its routing settings. Plain guided setup does not enable native OpenTelemetry; use the capture options in Setup.
The guided journey exits with:
| Exit code | Meaning |
|---|---|
0 | Every selected item was applied or is waiting for first use. Stopping at a prompt without changes also returns 0. |
1 | A failure, an unsupported item, or a failed inference test. |
2 | Invalid flags or selection. |
3 | Not signed in, or no gateway key. |
4 | Nothing selected. |
5 | The service could not be reached. |
Run
Parses local session logs, scores them, and optionally submits the result.
# First run: process all historical sessions and submit the result
forgebench run --all --push
# Daily check: local only, nothing submitted
forgebench run --since 24h| Flag | Description |
|---|---|
--all | Process all historical sessions, not only recent ones. Use it on the first run. |
--since 7d | Limit processing to sessions started within this window. Accepts values such as 7d, 24h, and 2w. |
--push | Submit the result to Forgebench. Without this flag, the command only writes a local file. |
--tool claude_code | Restrict processing to a single tool. Accepted values: claude_code, codex, cursor, antigravity, github_copilot, opencode. |
--output path.json | File path to write the result to. Defaults to profile.json in the current directory. |
--no-usage | Exclude token counts and collect only the working-style profile. |
--no-repo | Skip reading git history entirely. |
--no-meta | Omit the git branch associated with each session. |
--machine-name office-mac | Label this machine's usage with a name, so an administrator can identify the source. |
--team platform | Tag this machine's usage with a team name. |
--no-ai-analysis | Skip the written summary of working style. Faster, and costs nothing. |
--clear-cache | Clear any results that previously failed to submit and are queued for retry. |
--project value | Restrict processing to one project, for scripted use. The value is a hash, not a folder name. |
Login / logout
# Sign in through a browser (also available inside setup)
forgebench login
# On a remote machine without browser access, sign in with a key provided by an administrator
forgebench login --key
# Remove the stored key from this machine
forgebench logout| Command | Description |
|---|---|
login | Sign in through a browser for the selected environment. --sso is also accepted. |
login --key | Enter an API key privately, useful on SSH. |
logout | Remove the stored key from this machine. |
Reporting login does not authorize model requests. Gateway setup needs
a key with chat:write. Guided setup can obtain gateway access
through browser approval when your administrator has provided a key for
gateway authorization. It saves that credential separately for the selected Forgebench URL.
See Authorize model requests.
Schedule
Runs run --all on a recurring interval.
# Run automatically once a day
forgebench schedule enable --interval daily
# Disable the schedule
forgebench schedule disable| Command | Description |
|---|---|
schedule enable --interval daily | Enable a recurring run. Accepted values: hourly, daily (default), weekly. |
schedule disable | Disable the recurring run. |
Sync
The command the session-end hook runs. Run it yourself if the hook appears stuck.
forgebench sync --quiet| Flag | Description |
|---|---|
--quiet | Suppress output. This is the flag the hook itself passes. |
--tool claude_code | Sync a single tool instead of everything the hook normally covers. |
--foreground | Run in the current terminal instead of in the background. Useful for confirming the command works. |
Hooks
Enables automatic reporting whenever a session ends. This is the recommended configuration, and the one Setup uses.
For Claude Code, hooks install installs the forgebench plugin from the
seedlinglabs/forgebench-cli marketplace. Once the plugin is installed, enabled
and configured, it replaces the session-start, session-end and skill-load hooks
previously written to settings.json. The Stop hook
from --on-stop and the optional context hooks stay in settings.json. The
plugin needs Claude Code 2.1.292 or later on macOS or Linux. On an older or
missing claude, hooks install writes the settings.json hooks and says
so; run it again once a supported claude is on PATH to move to the
plugin. Windows is not supported yet: hooks install refuses the Claude
Code step before changing anything, prints why, and exits with 1. Existing
Claude hooks and settings are left as they are, and other selected tools
still install. If the plugin install fails, the settings.json hooks
stay and the command prints the claude plugin commands to run by hand.
If a marketplace named forgebench is already configured from another
source, forgebench does not install from it. If the forgebench plugin was
installed by someone else, hooks install never changes its options. When
they already match, forgebench uses the plugin. Otherwise the settings.json
hooks stay and the command prints the claude plugin configure ... --values-stdin
command you can run to set it up yourself. If a failed install prints
recovery commands for a plugin that already existed, they do not turn sync off.
hooks status keeps showing the failure until a later run succeeds.
The plugin stays enabled while either session sync or MCP is on. Claude Code's
/mcp view lists the plugin even when MCP is not configured. It sends nothing
to MCP until mcp_url is set. If the plugin was disabled inside Claude Code, run
claude plugin enable forgebench@forgebench --scope user to re-enable it (and
resume session sync when sync is on).
# Enable automatic reporting
forgebench hooks install
# Also report after every response, not only when a session ends
forgebench hooks install --on-stop
# Only one tool (repeat --tool to pick several)
forgebench hooks install --tool codex
forgebench hooks install --tool opencode
# Check whether the hook is enabled and when it last ran
forgebench hooks status
# Disable automatic reporting
forgebench hooks uninstall
# Disable it for one tool only
forgebench hooks uninstall --tool claude_code| Command | Description |
|---|---|
hooks install | Enable automatic reporting for selected tools. OpenCode 2.x enables sync in the pinned @forgebench/opencode entry in opencode.json or opencode.jsonc. If the pinned version is unpublished or the registry is unreachable, the CLI keeps the existing idle-sync plugin and explains the fallback. OpenCode below 2.x installs nothing and the command says 2.x is required. |
hooks install --on-stop | Also report after every response, not only when a session ends. Increases reporting frequency. |
hooks install --tool codex | Enable reporting for one tool only: claude_code, codex, cursor, github_copilot, or opencode. Repeat to pick several. |
hooks install --print-managed | Print the configuration for MDM distribution instead of installing it locally. For admins deploying fleet-wide. |
hooks status | Check whether the hook is enabled and when it last reported. For Claude Code it shows installed and required plugin versions. It reports disabled, outdated, failed or restart-pending plugins and prints a fix command. |
hooks uninstall | Disable automatic session reporting. For OpenCode this turns off the plugin's sync option only; its gateway and MCP options stay, and the entry is removed when none is left. For the Claude plugin this turns off session sync only; an MCP connection you set up stays. When neither is left, the plugin and marketplace are removed if forgebench installed them. A plugin you installed yourself is left exactly as it is, sync option included, and the command says so. |
hooks uninstall --tool claude_code | Disable it for one tool only. |
hooks manages session reporting only. To connect Claude Code to the hosted MCP server, see Installation & Setup.
Gateway
Routes coding tools through ForgeBench, so every model call is metered,
budgeted and audited. This needs an API key with the chat:write scope,
not the sign-in from forgebench setup. Install takes the key from
FORGEBENCH_GATEWAY_KEY or asks for it once.
# Route Claude Code and Codex, plus Gemini CLI and OpenCode if installed
forgebench gateway install
# Only one tool (repeat --tool to pick several)
forgebench gateway install --tool codex
# Show what each tool points at
forgebench gateway status
# Take out only what install wrote
forgebench gateway remove| Command or flag | Description |
|---|---|
gateway install | Point the selected tools at ForgeBench. Settings you already set, such as a model, are left as they are. |
gateway status | Show whether each tool points at ForgeBench, at something else, or at its own vendor. |
gateway remove | Remove only what install wrote, including the key it saved for Codex. For OpenCode it turns off the plugin's gateway option and keeps sync and mcp with their URL and executable settings. |
--tool codex | Select one tool. Repeat it to select several. Accepted values: claude, codex, gemini, opencode, agy, cline, kilocode, continue, hermes, droid, crush, qwen, zed, goose, aider, copilot. |
--forgebench-url https://api.forgebench.ai | The ForgeBench API URL. Defaults to the one this CLI uses. |
--codex-model MODEL | The model Codex uses by default. Without it, install picks one from the key's models. |
--funding | Choose api-only (default), subscription-only, or subscription-first. Subscription routing requires an enabled deployment and an assigned profile. |
--paid-fallback-max-usd | Set a positive per-request paid limit. Required for subscription-first; it cannot be used with the other funding modes. |
--yes | Skip the confirmation prompt. |
Use forgebench gateway verify --forgebench-url https://api.forgebench.ai to check the deployed native routing contract without a model call. The API URL is required. Use your deployment's URL for a self-hosted instance. To verify traffic, run a small task and inspect Activity → Routed requests. The contract check alone does not establish that a request reached the gateway.
For a supported native subscription, use Setup guide → Advanced: use an existing native subscription to check availability and generate the command. For Codex, start the configured client with forgebench gateway launch --tool codex.
Codex needs no export. Install saves the key in the CLI's own settings, and
Codex gets it by running forgebench gateway token. Install also sets a
default model and lists the key's chat models in Codex's /model. Re-run
forgebench gateway install after the key's models change. Hermes,
Factory Droid and Crush still read the key from FORGEBENCH_GATEWAY_KEY in
your shell.
OpenCode plugin entry
On OpenCode 2.x, gateway install --tool opencode adds one entry to the
plugins list of opencode.json (or opencode.jsonc, comments kept):
{"package": "@forgebench/opencode@<exact version>", "options": {...}}. The
options hold three independent switches, gateway, sync and mcp, plus the
ForgeBench url, the CLI executable, and, for gateway, the models and
routing headers install resolved from your key. gateway install and hooks install each change only their own switch; mcp install keeps writing its
direct MCP entry (see Install with the CLI). The entry stays
while any switch is on and is removed with the last one.
Install never writes the key into opencode.json. It saves the key in the CLI's
own key file (mode 0600), and the plugin runs forgebench gateway token for each
request. An existing generated provider.forgebench block and
opencode-gateway.key file are retired only after the key is saved and the
entry is written; a block you edited is kept and reported.
| Situation | What the CLI does |
|---|---|
| OpenCode below 2.x | Install does nothing and says 2.x is required. gateway status reports an existing install as legacy. gateway remove still removes what the CLI wrote. |
| Pinned version not published, or the registry cannot be checked | Install checks registry.npmjs.org for the exact version first. If it is missing or unverifiable, the existing generated files stay, the command says why, and the retry command is printed. |
| Older pin in the entry | Install replaces the version after the check and keeps your options, models, headers, comments and other plugins. A newer pin than the CLI expects is left alone. |
Your own provider.forgebench, or a -@forgebench/opencode entry | Left alone; install refuses and exits with 1. |
gateway status and forgebench doctor read only the config file. They show the
installed and pinned versions and, once configured, report that OpenCode loads
the package on its next start; restart OpenCode to activate a change.
Try for this session
gateway launch runs Claude Code, Codex or OpenCode through ForgeBench for
that one process, with no install first. The routing is temporary: nothing is
written to the tool's configuration, your normal login, plugins and history
are untouched, and the temporary files are deleted when the tool exits. The
tool still writes its own session history as usual.
# Claude Code, one prompt
forgebench gateway launch --tool claude -- -p "summarize this repo"
# Codex, non-interactive
forgebench gateway launch --tool codex -- exec "summarize this repo"Verified so far: -p for Claude Code and exec for Codex. The interactive
default for all three tools, and OpenCode (--tool opencode -- run ...), are
not yet verified; do not rely on them.
The key is the one gateway install saved for that ForgeBench URL (or
FORGEBENCH_GATEWAY_KEY for the default URL). Launch never saves a key and
never sends one deployment's key to another. The key reaches the tool through
its environment or the CLI's key store, never its arguments or a settings file.
| Behaviour | Description |
|---|---|
| Exit code | The tool's exit code. A tool ended by a signal returns 128 plus the signal number. |
| Ctrl-C and termination | The signal is passed to the tool. If it does not exit, launch stops it, waits for it, then deletes the temporary files. |
| Claude Code settings | With a key-funded profile, a ANTHROPIC_CUSTOM_HEADERS, ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN in your user or project settings, or your shell, is overridden for this session only. A note names what was overridden and where; your files are not changed. |
| Allowed forms | The interactive default, -p for Claude Code, exec for Codex and run for OpenCode (only -p and exec are verified so far). Arguments that change the routing, resume or fork a session, or attach to a server, are refused, as is a model outside your key's models. |
| Subscription profiles | When the key's profile is funded by a subscription, Claude Code and Codex use the native subscription route and must be a client version the server has verified. OpenCode has no subscription route and is refused. A subscription-first profile launches subscription-only and stops at quota; paid fallback is enabled only by --paid-fallback-max-usd USD, which must be positive and within the profile's and server's limits. Claude Code settings with an apiKeyHelper are refused in this mode. |
| OpenCode version | OpenCode 2.x only; 1.x is refused. |
| Refused before the tool starts | Setup refuses missing keys, tools or model lists, conflicting configuration, unreadable files, managed routing restrictions and OpenCode plugin or provider restrictions. Subscription-funded Claude Code also refuses conflicting credentials or ANTHROPIC_CUSTOM_HEADERS. The message names the file to change, and nothing is launched. |
Status
Shows the installed version, sign-in status, whether the hook is installed, and whether a schedule is running.
forgebench status
# Machine-readable output
forgebench status --jsonIf reporting is not working, forgebench doctor diagnoses why and says how to
fix it. It also accepts --json.
Capabilities
forgebench capabilities shows the CLI build and the features it supports.
Add --json for machine-readable output.
Native subscription sign-in remains separate from gateway authorization. Subscription gateway modes require the deployment to advertise support for the client and version. Direct subscription calls with session reporting do not receive gateway routing or budget enforcement.
Update
Checks for a newer version. --install downloads the official release binary, checks it against the
release checksum, and replaces the installed CLI.
# Check the stable channel (the default)
forgebench update
# Install the latest stable release
forgebench update --install
# Check or install from the preview channel instead
forgebench update --channel preview
forgebench update --install --channel preview| Flag | Description |
|---|---|
--check | Only check for a newer version. This is the default. |
--install | Verify and install the latest release of the selected channel. |
--channel preview | Use the preview channel (newer, less tested) instead of stable. |
--auto on | Install a newer official release automatically after you run status or doctor in a terminal. Turning it on also turns on --auto-check. Off by default. |
--auto-check off | Stop the background release check that runs when you use the CLI in a terminal. On by default. |
--install only replaces the official release binary. If you installed the
CLI with a package manager or from source, update it the same way you
installed it. An update is refused while a local harness run (see
Harness) is active; retry after it finishes.
Harness
Starts and controls a coding agent (Claude Code, Codex or OpenCode) running on your own machine, under your own user account. Each command prints the run's state as JSON.
# Start a run with an explicit backend and model
forgebench harness start --backend claude --model sonnet --prompt "Fix the failing test"
# Check on it, or wait for it to finish while relaying its output
forgebench harness status <run-id>
forgebench harness wait <run-id> --follow
# Queue the next turn while it runs, or continue a stopped run
forgebench harness followup <run-id> --prompt "Now add a test for the edge case"
forgebench harness resume <run-id> --prompt "Also update the changelog"
# Stop it
forgebench harness cancel <run-id>| Command | Description |
|---|---|
start | Launch a run. Requires --backend (claude, codex or opencode), --model and --prompt. Optional: --cwd (defaults to the current directory), --binary (an explicit path to the agent's executable), --parent-run-id, and --native-arg (repeatable) or options after -- to pass through to the agent. Model, session and daemon options are reserved and cannot be passed through. The backend and model cannot change for the life of the run. |
status <run-id> | Show the run's state: starting, running, stopping, completed, failed, cancelled, or outcome_unknown if its worker stopped reporting. |
wait <run-id> | Block until the run finishes. --timeout stops waiting after that many seconds. --follow relays the agent's output while you wait and prints the final state to stderr. |
followup <run-id> --prompt | Queue the next turn. If the run is still working, the turn starts when the current one ends. |
resume <run-id> --prompt | Continue a run that has stopped, in the same agent session. Refused while the run is active; use followup for that. |
cancel <run-id> | Stop the run, and drop any queued next turn. |
A prompt can be up to 1 MB. The command exits with 1 when the run has
failed or its outcome is unknown, and 2 when the command itself was refused.
Uninstall
Removes the schedule, the hooks, and the stored login, then prints the
command to remove the program itself. For Claude Code it also turns off the
plugin's session sync and MCP connection, and removes the plugin and its
marketplace when forgebench installed them. A plugin you installed yourself
stays installed and its options are not changed. If the plugin cannot be removed, the
command prints the claude plugin commands that finish the job and exits
with 1.
forgebench uninstall