Installing the CLI

The ForgeAI CLI (forge) is the execution engine that runs on your machine: it connects to the cockpit, receives dispatched work, and runs AI coding agents in local Docker containers using your own AI tokens. This page covers getting the CLI onto your machine and verifying it works.

Beta note: this is a prerelease (0.1.0-beta.1), published under the beta npm tag. Asking for @beta explicitly is recommended — it keeps working once a stable release exists and starts moving the latest tag. The package is Apache-2.0.

Requirements

Requirement	Details
Node.js	20.11 or newer (declared in the package's engines) — forge connect and the forge vm init local image build rely on import.meta.dirname, which is undefined on older Node.
git	The CLI shells out to the git binary for clone, fetch, and checkout operations.
Docker	Required for agent execution (forge connect and the forge vm commands). Not needed just to install the CLI.

See Prerequisites for the full environment setup, including Docker and your Claude Code authentication.

Operating system support

The CLI codebase handles macOS, Windows, and Linux (cross-platform directory openers, token storage, and Docker host networking). In practice, macOS on Apple Silicon is the only fully-exercised platform today: the local agent-image build targets linux/arm64, so Intel/AMD64 hosts would receive an ARM64 image that requires emulation.

Install

Install the beta globally:

npm install -g @getforgeai/cli@beta

This puts two identical binaries on your PATH, forge and forgeai — use whichever you prefer. The shared @getforgeai/protocol package is pulled in automatically as a dependency.

If you prefer not to install globally, you can run it on demand instead:

npx @getforgeai/cli@beta --help

Verify the installation

Check the version:

forge --version

This prints the installed version, for example 0.1.0-beta.1. Then confirm the command tree loads:

forge --help

You should see the program described as "ForgeAI CLI - AI-assisted development cockpit" with command groups including auth, connect, org, cli, journal, config, session, task, workflow, release, and vm. The full list is in the CLI command reference.

Building from source instead

You only need this if you want to modify the CLI. Clone the repository, install with pnpm (the monorepo pins pnpm@10.14.0), and build — this compiles @getforgeai/protocol first, then the CLI:

pnpm install
pnpm build:cli

The output lands in packages/cli/dist/ (gitignored, so the build step is mandatory). Link it onto your PATH with pnpm link --global from packages/cli.

Point the CLI at your cockpit

The CLI defaults to http://localhost:3000 as its cloud server URL. To target a deployed cockpit, pass --server when you first log in — the URL is persisted to ~/.forgeai/config.json on successful login:

forge auth login --server https://forgeai-production-382c.up.railway.app

Authentication uses an OAuth device flow; see Authenticating the CLI for the full walkthrough, including forge auth setup-claude (or setup-codex / setup-opencode / setup-kilo) for the AI credentials that agents run with.

Prepare the agent runtime

Agents run inside the getforgeai/agent:latest Docker image. Initialize it once:

forge vm init

This checks that the Docker daemon is running (it exits with an error pointing to Docker Desktop if not), then tries to pull the image, falling back to building it locally from packages/cli/rootfs/Dockerfile — an Ubuntu 24.04 image with Node.js 20, git, and the agent CLIs preinstalled (Claude Code, Codex, OpenCode, and Kilo). Expect the first build to take several minutes. If you built the image before Codex/OpenCode support and switch to one of those engines, refresh it (docker pull getforgeai/agent:latest, or remove the local image and re-run forge vm init) — the CLI detects a stale image and tells you.

Updating

There is no self-update command. Reinstall the latest beta:

npm install -g @getforgeai/cli@beta

Betas move fast — if you need a fixed version, pin it explicitly (for example @getforgeai/cli@0.1.0-beta.1).

Where the CLI stores its files

All CLI state lives under ~/.forgeai/: config.json (settings), auth/ (encrypted credentials), daemon.pid, daemon.sock, and daemon.log (background connection daemon), events/ (local NDJSON event journal), docker/sessions/ (per-task agent session directories), repos/ (host-side project clones used for branch and worktree operations during agent runs), cache/skills/ (cached skill bundles), and open/ (local clones created by forge task open and friends).

Uninstalling

To cleanly remove the CLI from a machine, release its registration first, then delete the local state.

Unlink the device from each organization it is registered with (this disconnects the WebSocket and removes the device registration on the server):

forge org unlink <org-slug>

To remove a device you no longer have access to, run forge cli list from any authenticated machine in the same organization and unlink it by ID:

forge cli unlink <cliId>

Then sign out — this stops the background daemon and deletes the locally stored credentials:

forge auth logout

Finally, uninstall the package and delete the CLI's state directory:

npm uninstall -g @getforgeai/cli
rm -rf ~/.forgeai

Next steps

• Authenticating the CLI — log in with the device flow and set up your agent credentials
• Connecting projects — link organizations and keep the daemon connected
• CLI command reference — every command and flag
• Quickstart — the end-to-end first-run path