Install

Requirements

Item	Requirement
Node.js	≥ 18 (published artifacts run on Node; the monorepo may use Bun for development)
OS	macOS / Linux / Windows (WSL recommended)
Network	Reach your model API endpoint
Optional	sandbox-exec (macOS) or bwrap (Linux) for --sandbox

Install methods

Global install (recommended)

npm install -g @forgeax/cli

Verify:

which forgeax
forgeax --version
forgeax --help

Package name ≠ command name: install @forgeax/cli; the command is forgeax. Do not use npm i -g forgeax as the product entry.

Temporary via npx

npx @forgeax/cli --demo -p "hi"
npx @forgeax/cli -p "List TypeScript entrypoints in this directory"

From source / public mirror

git clone --recurse-submodules https://github.com/ForgeaX-Games/forgeax-cli.git
cd forgeax-cli
# Follow the repo README to install deps and build dist, then:
# npm link   # or npm pack && npm i -g ./forgeax-cli-*.tgz

Public org: ForgeaX-Games.

Credentials

Configure at least one credential set matching your protocol family:

# Anthropic Messages family (default)
export ANTHROPIC_API_KEY=...
export ANTHROPIC_BASE_URL=...          # optional

# Or OpenAI-compatible family
export FORGEAX_PROVIDER_API=openai-compat
export OPENAI_API_KEY=...
export OPENAI_BASE_URL=...

Model override:

export FORGEAX_MODEL=claude-opus-4-8   # or your deployment name
# Equivalent: forgeax --model <id>

Or write user settings (see Configuration):

{
  "model": "claude-opus-4-8"
}

Path: ~/.forgeax/settings.json.

Acceptance checklist

On a clean machine:

# 1) Binary & help
forgeax -v
forgeax -h

# 2) Offline smoke (no API key)
forgeax --demo -p "hi"

# 3) Real turn (needs a key)
forgeax -p "In one sentence, what is in the current working directory?"

If step 2 fails, see Troubleshooting.

Upgrade & uninstall

npm update -g @forgeax/cli
npm uninstall -g @forgeax/cli

Relation to ForgeaX Studio

	CLI	Studio
Entry	forgeax in a terminal	Browser / desktop app
Kernel	This package is the runtime	Can attach the same kernel via --serve sidecar
Docs	This site /docs/cli/	Studio docs

In Studio’s registry the internal kernel id may still show as forgeax-core — that is a KernelId, independent of the npm name @forgeax/cli, and does not change how you install or run the CLI.