Overview

ForgeaX CLI — a terminal-native single-agent runtime

@forgeax/cli is ForgeaX’s native agent kernel, delivered as the global command forgeax. Describe what you want in natural language and get end-to-end help in the terminal — reading code, editing files, running commands, committing, and debugging.

The same codebase also ships two advanced shapes: a --serve sidecar (Studio / orchestrator kernel) and an embeddable createAgent library API. This site is for CLI product users.

Why ForgeaX CLI?

Drive development and ops with natural language

Say what you want instead of memorizing flags first. Whether you are tweaking a function, reviewing commit risk, or triaging error logs, conversational interaction is enough.

Terminal-native, seamless fit

• Familiar environment: AI assistance stays in the CLI — no forced switch to a separate IDE-only UI
• Native feel: Works on major OSes and terminals; Ink TUI on a TTY, or --no-tui for readline
• Low learning cost: Keep your shell / Git / scripting habits; AI layers on top

Capable out of the box

• Built-in tools: Read/write files, run commands, Git, search, notebook, Todo, and more
• MCP: Connect third-party tools and services via the Model Context Protocol
• Skills / Commands / Plugins: Auto-discovered at project and user level
• Permissions & sandbox: Declarative permissions rules; optional OS-level Bash sandbox (macOS Seatbelt / Linux bwrap)

Unix-philosophy AI

• Pipe-friendly: Consume stdin like grep / awk
• Scriptable: Fits CI, Makefiles, and local hooks
• Stdio: Redirects and pipelines compose cleanly

# Pipe examples
git log --oneline | forgeax -p "Review these commits for likely problems"
cat error.log | forgeax -p "Summarize root cause and fix steps"

Try it quickly

Requirements

• Node.js 18.0+
• A working model API key (see Install); or use --demo with no key

Install

npm install -g @forgeax/cli

The global command is forgeax (the package is scoped @forgeax/cli — do not install via npm i -g forgeax).

Start

# Enter a project
cd my-project

# Interactive (TUI on a TTY)
forgeax

# Or one-shot
forgeax -p "Help me optimize this function"

# Smoke test without an API key
forgeax --demo -p "hi"

Next steps

Learn more

• Quickstart — first setup and a 30-second REPL
• Workflows — -p / resume / pipes / output formats
• Install — env vars, models, verification

Configure & extend

• Settings & env — ~/.forgeax, layered settings
• MCP — mcp.json and tokens
• Permissions — deny / ask / allow and permission modes

Get help

• Troubleshooting
• CLI reference
• GitHub Issues

Feedback

• Source & issues: ForgeaX-Games/forgeax-cli
• Studio site: forgeax.github.io
• npm: @forgeax/cli
• 中文文档：概述