CLI reference

Complete reference for the isonforge command. Run isonforge --help for an inline summary.

Synopsis

isonforge [options] [command] [prompt...]

Top-level commands

Command Description
isonforge Open interactive REPL
isonforge "<prompt>" One-shot prompt (interactive UI)
isonforge -p "<prompt>" Print mode, non-interactive
isonforge --bg "<prompt>" Start as background agent, exit immediately
isonforge --resume Interactive session picker at startup
isonforge --continue [id] Resume last (or specific) session
isonforge auth login Authenticate
isonforge auth status Show login state
isonforge auth logout Remove saved key
isonforge init Generate FORGE.md from project analysis
isonforge agents List background agents
isonforge logs <id> Tail an agent's stdout log
isonforge attach <id> Follow an agent's output live
isonforge stop <id> Terminate an agent
isonforge rm <id> Remove a stopped agent from the list
isonforge respawn <id> Restart a stopped agent with its original prompt
isonforge --version Print version

All flags

Authentication and session

Flag Description
--continue [id] Resume previous session. Latest if no id; specific session by id.
--resume Show an interactive session picker at startup. Choose from the last 20 sessions.

System prompt customization

Flag Description
--system-prompt <text> Replace the entire default system prompt. Drops project context, FORGE.md, and tool guidance - you take responsibility.
--system-prompt-file <path> Same as above but reads from a file. Mutually exclusive with --system-prompt.
--append-system-prompt <text> Append text after the default prompt. Default identity and tool guidance are preserved.
--append-system-prompt-file <path> Same as above but reads from a file. Combinable with the replace flags.

See System prompt customization for details.

Permissions

Flag Description
--yolo Auto-approve every tool execution. Same as --permission-mode bypassPermissions.
--dangerously-skip-permissions Alias for --yolo. Provided for Claude-Code muscle-memory.
--permission-mode <mode> Start in a specific mode: default, acceptEdits, plan, auto, bypassPermissions. Session-scoped.
--allowedTools <list> Comma-separated tool names that skip permission prompts.

See Permission modes.

Effort and reasoning

Flag Description
--effort <level> One of low, medium, high, xhigh, max. Maps to sampling parameters and reasoning budget.

See Effort levels.

Flag Description
-p, --print One-shot mode. Forces --yolo. Streams to stdout, exits when done.
--max-turns <n> Cap the agentic loop at N turns. Exits with error if hit.
--max-budget-usd <usd> Stop when cumulative token cost (input + output) exceeds this USD value. Requires ISONFORGE_RATE_IN / ISONFORGE_RATE_OUT env.
--output-format <fmt> text (default), json (single envelope at end), or stream-json (event chunks).
--json-schema <schema> JSON-Schema enforced on final output. Passes through to the backend's guided decoding. Inline JSON or @path/to/schema.json.

See Print mode.

Filesystem and context

Flag Description
--add-dir <path> Add an extra working directory. Repeatable: --add-dir ../shared --add-dir ../utils. Validated at startup. Surfaced to the model in project metadata.

Settings

Flag Description
--settings <path-or-json> Path to a JSON settings file, or inline JSON. Overrides all file-based sources.
--setting-sources <list> Comma-separated subset of user,project,local. Default loads all three.

See Settings.

Worktrees

Flag Description
-w, --worktree [name] Start in an isolated git worktree at <repo>/.isonforge/worktrees/<name>. Auto-generates a name if omitted.
--from-pr <pr> Resolve a PR's head branch (via gh CLI), fetch it, and create a worktree from it.

See Worktrees.

Background mode

Flag Description
--bg Run the prompt as a detached background agent. Parent exits immediately, agent runs to completion in the background.

See Background agents.

Image input

Flag Description
--image <path> Attach a PNG or JPG. Repeatable for multiple images. Max 8 MB per image.

See Image input.

Output / debug

Flag Description
--verbose Print full API requests and responses to stderr. Also ISONFORGE_VERBOSE=1.
--version, -V Print version and exit.
--help, -h Print help and exit.

Examples

Plan first, then execute:

isonforge --permission-mode plan "refactor auth/session.py to use redis"
# Review the plan. Then:
isonforge --continue "gas"

One-shot review with JSON output:

git diff main | isonforge -p \
  --output-format json \
  --max-turns 3 \
  --append-system-prompt "Flag only security issues, ignore style." \
  "review this diff"

Schema-validated extraction:

echo "John Doe, 30, Software Engineer" | isonforge -p \
  --json-schema '{"type":"object","properties":{"name":{"type":"string"},"age":{"type":"integer"}}}' \
  --output-format json \
  "extract structured info"

Background audit:

ID=$(isonforge --bg "audit every fetch() call for missing await + timeout" | grep -oE '[a-f0-9]{8}' | head -1)
# do other work
isonforge logs $ID

Worktree from PR:

isonforge -w pr-123 --from-pr 123 "finish what was left in this PR"

Multi-directory workspace:

isonforge --add-dir ../shared-lib --add-dir ../docs "update the cookbook to match the new API"

Exit codes

Code Meaning
0 Success
1 General error (API key missing, network, parse error)
2 Budget cap hit (--max-budget-usd) or UserPromptSubmit hook blocked
99 Self-restart signal (handled by the launcher wrapper for /upgrade)
130 Interrupted (Ctrl+C)