Quickstart

From install to a useful first conversation in a few minutes.

1. Install

npm install -g @forgeax/cli
forgeax --version

If global npm installs are restricted:

npx @forgeax/cli -p "hi"
# Or from a packed tarball:
# npm install -g ./forgeax-cli-*.tgz

2. Configure an API key

Default is the Anthropic Messages family (OpenAI-compatible endpoints are also supported — see Configuration):

export ANTHROPIC_API_KEY=YOUR_ANTHROPIC_API_KEY
# Optional gateway / self-hosted endpoint
# export ANTHROPIC_BASE_URL=https://your-gateway.example/v1

OpenAI-compatible family:

export FORGEAX_PROVIDER_API=openai-compat
export OPENAI_API_KEY=YOUR_OPENAI_API_KEY
export OPENAI_BASE_URL=https://api.openai.com/v1   # or your compatible gateway

No key yet? Smoke-test with the built-in echo provider:

forgeax --demo -p "hi"

3. Enter a project and start

cd /path/to/your/project
forgeax

On a TTY you get the Ink TUI; non-TTY or --no-tui uses a readline REPL.

One-shot:

forgeax -p "Summarize this repo layout and point out the entry files"

4. Day-one actions

You want…	Do this
Resume last session	forgeax -c or forgeax --resume <id>
Machine-readable output	forgeax -p "..." --output-format json
Pipe input	git diff | forgeax -p "Code review"
Tighten auto-edits	--permission-mode acceptEdits or settings (see Permissions)
Check the environment	/doctor in-session (if loaded) or Troubleshooting

5. Conventional project dirs (optional)

Auto-discovered:

Path	Purpose
.forgeax/settings.json	Shared project settings (committable)
.forgeax/settings.local.json	Machine-local settings
.forgeax/skills/ · ~/.forgeax/skills/	Skills
.forgeax/commands/	Markdown slash commands
.forgeax/mcp.json · ~/.forgeax/mcp.json	MCP servers
.forgeax/sessions/	Session WAL (--resume / -c)
.forgeax/memory/	Auto-memory (disable with --no-memory)

User-global config defaults to ~/.forgeax/ (override with FORGEAX_CONFIG_DIR).

Next

• Install — Node version, credentials, checklist
• Workflows — pipes, resume, thinking, sandbox
• MCP · Permissions