CLI/CLI command reference
Complete reference for every forge command: synopsis, flags, defaults, and behavior.
This page is the complete reference for the ForgeAI CLI (forge, version 0.1.0). The package installs two equivalent binaries, forge and forgeai — both run the same CLI. If you have not installed it yet, start with Installing the CLI, then Authenticating the CLI.
forge --version prints the CLI version; --help works on any subcommand.http://localhost:3000. Most networked commands accept --server <url> to override it — the per-command synopses below show which ones. Commands without the flag (forge reconnect, the open commands, forge session respond, forge mcp) always use the persisted server URL. Running forge auth login --server https://forgeai-production-382c.up.railway.app persists the URL to config, so you only need --server once.~/.forgeai/: config.json (settings), auth/ (encrypted tokens), daemon.pid / daemon.sock / daemon.log (daemon state), events/ (local event journal), and open/ (clones created by the open commands).forge auth login [--server <url>]
forge auth status [--server <url>]
forge auth logout
forge auth setup-claude
forge auth setup-codex
forge auth setup-opencode
forge auth setup-kiloAuthenticates with the cockpit using the OAuth Device Flow: it prints a verification URL and user code, opens your browser automatically, then polls every 5 seconds (30-minute timeout). On success the CLI links the organizations you approved on the device page, registers itself as a device in each, and stores the token AES-256-GCM-encrypted at ~/.forgeai/auth/credentials.json. The --server <url> flag (default http://localhost:3000) is persisted to config on successful login. Details: Authenticating the CLI.
Prints whether you are authenticated, your name and email, the server URL and default organization, then probes cloud connectivity with a heartbeat (5-second timeout) and reports Cloud: Connected or Cloud: Unreachable.
Stops a running daemon, deletes the encrypted credentials file, and clears session-specific config (linked orgs, CLI identity, sync state). Machine-level settings (server URL, agent type, agent slots, VM sizing) are preserved.
Obtains a long-lived (about one year) Claude Code OAuth token by running claude setup-token, and stores it in the macOS Keychain or, on other platforms, AES-256-GCM-encrypted at ~/.forgeai/auth/claude-oauth.json. Agents run in containers with this token — you must already be logged into Claude Code on your machine. See Security.
Stores Codex credentials for agents running with agent-type CODEX. If a Codex login exists on this machine (~/.codex/auth.json, created by codex login), the command offers to import it; otherwise it asks for an OpenAI API key. The credential is stored like the Claude token (Keychain on macOS, AES-256-GCM-encrypted file elsewhere) and configured inside each agent container at spawn time — an imported auth.json is written into the container home, an API key is registered through codex login --with-api-key. See Security.
Stores OpenCode credentials for agents running with agent-type OPENCODE. If an OpenCode login exists on this machine (~/.local/share/opencode/auth.json, created by opencode auth login), the command offers to import it; otherwise it asks for a provider API key (Anthropic, OpenAI, or OpenRouter), injected into agent containers as that provider's standard environment variable. The command also lets you set the OpenCode model in provider/model form — leave it empty to use OpenCode's default for your provider. See Security.
Stores Kilo credentials for agents running with agent-type KILO. If a Kilo login exists on this machine (~/.local/share/kilo/auth.json, created by kilo auth login), the command offers to import it; otherwise it asks for a Kilo gateway API key (from your profile at app.kilo.ai), injected into agent containers as KILO_API_KEY. The command also lets you set the model in kilo/vendor/model form (e.g. kilo/anthropic/claude-sonnet-4.5) — leave it empty to use Kilo's default. See Security.
forge connect [--server <url>] [--org <slug>] [--attach] [--stop]Connects this machine to the cockpit. By default it spawns a background daemon that holds a WebSocket connection to every linked organization, sends a heartbeat every 30 seconds, and receives agent dispatches. If a daemon is already running, the command prints its PID and per-organization status and reconnects any missing orgs. See Connecting projects.
| Flag | Default | Description |
|---|---|---|
--server <url> | persisted config | Cloud server URL (only honored with --attach) |
--org <slug> | all linked orgs | Connect a single organization only (only honored with --attach) |
--attach | off | Run in the foreground (blocks the terminal; Ctrl-C shuts down cleanly) |
--stop | off | Shut down the background daemon |
Beta note: --server and --org currently take effect only in --attach (foreground) mode. In the default mode they have no effect: they are only validated when a new daemon is spawned (and ignored entirely if one is already running), and the background daemon always connects to all linked organizations using the persisted server URL.
forge disconnect [--server <url>] [--org <slug>]
forge reconnect [--org <slug>]disconnect closes WebSocket connections while keeping the CLI registered: through daemon IPC when a daemon runs (the daemon stays alive), otherwise over REST. reconnect re-establishes dropped connections through the running daemon and fails with No daemon running. Run 'forge connect' first. without one. Both take --org <slug> to target a single organization.
forge org list [--server <url>]
forge org unlink <slug> [--server <url>]
forge cli list [--server <url>]
forge cli unlink <cliId> [--server <url>]| Command | Description |
|---|---|
org list | Lists linked organizations with per-org status (connected, disconnected, not registered, unreachable) and marks the default org |
org unlink <slug> | After a y/N confirmation, disconnects and deletes this CLI's device registration in that org; warns when unlinking the last org |
cli list | Lists registered CLI devices in your default org: name, device ID, owner, agent slots, last seen; the current device is flagged (current) |
cli unlink <cliId> | Unregisters a device by ID after a y/N confirmation; warns if it is the current device |
The device list is also available in the cockpit under Settings → CLI Devices. Unlinking helps when you hit your plan's CLI-device limit — see Plans & billing and Organizations & members.
The default organization is the first organization you approve during forge auth login; forge org list marks it. There is no command to change it afterwards — org unlink removes the link but does not reassign the default — so to pick a different default, re-run forge auth login. Commands scoped to the default organization: cli list, cli unlink, session respond, the open commands (task open, workflow open, release open), the connectivity probe in auth status, and journal status.
forge config set agent-type <value>
forge config set models <engine> <models>
forge config set agent-slots <value>
forge config set opener <value>
forge config get| Key | Accepted values | Default | Notes |
|---|---|---|---|
agent-type | CLAUDE_CODE, CODEX, OPENCODE, KILO | CLAUDE_CODE | The agent engine this device runs. Make sure the matching credentials are stored (forge auth setup-claude / setup-codex / setup-opencode / setup-kilo). The cockpit can also change it live from Settings → CLI Devices |
models | [engine] <m1,m2,...> | none | Declares the models usable on this device (first = the device's default); none clears the list. The engine is optional and defaults to the configured agent-type. The list is advertised to the cockpit — tasks demanding a model this device does not declare are not dispatched to it. Refused when an org locked the list from the cockpit |
agent-slots | integer 1-20 | 5 | Maximum concurrent agents on this device; the cockpit can also push a new value live |
opener | terminal, vscode, finder | terminal | How the open commands open cloned directories |
agent-type and agent-slots apply immediately when a daemon is running; otherwise on the next forge connect. After the first registration, the cockpit is the source of truth for agent-type: a change made in Settings → CLI Devices while the CLI is offline is adopted by the CLI on its next connect. forge config get prints the current configuration with defaults shown when unset (including the OpenCode or Kilo model when relevant), plus the server URL, CLI ID, and CLI name.
forge models [engine]Shows the models declared on this device (with the default and any org lock) and the models available for the engine: OpenCode and Kilo list their real catalogs live (the CLI runs their own models command inside the agent image with your stored credentials — can take up to a minute); Claude Code and Codex show a curated list of known ids with availability notes (their plans gate models at run time). The engine defaults to the configured agent-type. The cockpit offers the same discovery on each device's Models dialog, including a "Fetch from device" button for connected devices.
The CLI journals events locally as NDJSON under ~/.forgeai/events/ while the WebSocket is down, then resyncs them to the cloud over REST on reconnect.
forge journal list [projectId]
forge journal status
forge journal clear [projectId]| Command | Description |
|---|---|
journal list | Shows total events, pending-sync count, and the last event's time and type |
journal status | Shows last sync time, pending events, and the sync cursor for the default organization's journal |
journal clear | Deletes all journal entries after warning that unsynced events will be lost |
Beta note: journal list and journal clear without an argument read a default journal file, while journal status uses the default organization's journal — so journal list may not show the journal that forge connect actually writes.
Docker is required for agent execution — see Prerequisites.
forge vm init
forge vm status
forge vm cleanup
forge vm stop-all| Command | Description |
|---|---|
vm init | Checks the Docker daemon (docker info, 5-second timeout) and ensures the agent image getforgeai/agent:latest exists — docker pull first, falling back to a local docker build from the repo's rootfs/Dockerfile. Exits 1 with a pointer to Docker Desktop if Docker is unavailable. (The built-in help still says "Download rootfs"; the implementation is Docker-based.) |
vm status | Lists active agent sessions (session ID, task, status, container ID); when no sessions are active, it reports whether Docker is ready instead |
vm cleanup | Removes containers for sessions whose status is STOPPED |
vm stop-all | Force-stops and removes all ForgeAI-managed containers |
forge task open <taskId>
forge workflow open <workflowId>
forge release open <releaseId>Each command fetches the entity from the cloud (always in your default organization — see above), clones or fetches its git branch into ~/.forgeai/open/<projectSlug>/<branchSlug>/, and opens the directory with your configured opener (default: terminal). They exit with code 1 if you are not authenticated, no default organization is set, the entity has no branch yet, or the project has no repository URL. git must be installed on your machine.
The cockpit gives you ready-to-paste commands: for example, the workflow wizard toolbar has a button that copies forge workflow open <workflowId>. See BMAD workflows, Tasks & the live board, and Releases & merge-back.
forge session respond <taskId> <response>Answers a blocked agent question for a task from the terminal (the same thing you can do from the task panel in the cockpit). The task is looked up in your default organization. Prints Response sent — agent will resume shortly.
forge mcp --task-id <id> --project-id <id> --org-id <id> [--workflow-id <id>] [--step-id <id>]Starts the MCP server bridge (stdio transport) for one agent session. This command is spawned automatically per task by the agent tooling — you do not normally run it yourself. --task-id, --project-id, and --org-id are required; --workflow-id and --step-id add workflow-step context. It requires a prior forge auth login.
If a command fails unexpectedly, check Troubleshooting & FAQ.