CLI reference

Commands, global options, REPL commands, and exit codes.

Two shapes: an interactive session, and one task run to completion. Everything else is a flag. The interactive form is for exploring; the one-shot form is what you put in scripts, because it exits with a code that means something.

Commands

commanddoes

forge: Start the interactive session (the default).
forge "<task>": Run a single task to completion and exit.
forge run "<task>": The explicit form of the above.
forge repl: Start the interactive session explicitly.
forge config: Show the resolved configuration (secrets redacted).
forge tools: List the tools the model can call, with their risk level.
forge version: Print the Forge version.

Bare forge with no argument starts a session; with an argument it runs that one task and exits. A task can also arrive on stdin, which is what makes it composable with the rest of your shell.

$ forge$ forge "add a /healthz endpoint and a test for it"$ echo "run ruff and fix what it reports" | forge run --json

Global options

flagdoes

--model <id>: Model id (defaults to $ANTHROPIC_MODEL).
--provider <name>: Provider: anthropic (default) or fake.
-C, --workspace <path>: Workspace root the agent operates in (default: cwd).
--mode <mode>: Approval mode: cautious | auto | yolo. Default auto.
-y, --yes, --yolo: Shorthand for --mode yolo. Approves everything.
--cautious: Shorthand for --mode cautious. Approve every write.
--sandbox <mode>: Shell isolation: none (default) or docker.
--max-iterations <n>: Hard ceiling on loop iterations per task.
--max-tokens <n>: Max output tokens per model call.
--json: Emit a single JSON result on stdout and nothing else.
-v, --verbose: Show structured step logs on stderr.
-q, --quiet: Suppress the activity log.
--version: Show version and exit.

Flags sit at the top of the precedence chain, so they override the environment and both config files. See Configuration for the full order.

The ones that matter most

-C, --workspace - every path the agent touches is resolved inside this directory. Run Forge against another repository without leaving the one you are in.
--mode - how much the agent may do unattended. --cautious and --yolo are shorthands for the ends of that scale.
--max-iterations - the ceiling on the loop, and therefore the ceiling on what one task can cost.
--json - one JSON object on stdout and nothing else. The activity log goes to stderr, so you can pipe stdout straight into jq.

Session commands

Inside a session, anything that is not a slash command is sent to the agent as a task.

commanddoes

/help: Show the command list.
/tools: List available tools.
/config: Show resolved configuration.
/clear: Forget the conversation so far.
/exit: Quit. Also: exit, quit, Ctrl-D.

/clear drops the conversation, not your files. Use it when you switch to an unrelated task - a fresh context is cheaper and the agent stops being influenced by earlier work.

Exit codes

One-shot mode distinguishes “the task is done” from “the task did not finish” from “you configured this wrong”, which is what makes it usable in CI.

codemeans

0: Task completed.
1: Did not complete - max iterations, refusal, or error.
2: Misconfigured - no model, bad flag, unavailable sandbox.
130: Interrupted (Ctrl-C).

run-forge.sh

#!/bin/sh# Fail the job if Forge could not finish the task.set -eforge --json --max-iterations 25 "$1" > result.json

Note the difference between 1 and 2. A 1 means Forge ran and could not finish - worth reading the log. A 2 means it never started, and retrying will fail the same way until you fix the configuration.

JSON output

--json emits a single object describing the run. Treat the fields as additive: new keys may appear, so read the ones you need rather than asserting the whole shape.

{  "ok": true,  "task": "fix the failing test in tests/test_auth.py",  "iterations": 4,  "summary": "Corrected the token expiry comparison; 41 tests pass.",  "files_changed": ["src/auth/token.py", "tests/test_auth.py"]}

Introspection

$ forge tools$ forge tools --json$ forge config$ forge version

These four commands describe the installed build rather than the documentation. When something here looks wrong, they are the answer - Tools covers the registry they print.