Workflows

One-shot (print)

forgeax -p "Explain the startup order in src/main.ts"
forgeax --print "Draft an Install section for the README"

Good for scripts, CI, and ask-and-exit use.

Output formats

forgeax -p "..." --output-format text          # default, human-readable
forgeax -p "..." --output-format json          # single result object
forgeax -p "..." --output-format stream-json   # NDJSON per event

Interactive REPL / TUI

forgeax                 # TTY → Ink TUI
forgeax --no-tui        # force readline

Start at the project root so .forgeax/* is auto-discovered.

Resume & sessions

Sessions default under ./.forgeax/sessions/ (override with --sessions-dir):

forgeax -c                         # resume most recent session in this dir; create if none
forgeax --resume <session-id>      # resume by id (or create with that id)
forgeax --session-id <id> -p "..." # explicit id (aligned with resume semantics)

Cross-process multi-turn needs the on-disk WAL; ephemeral runs (no session) are not persisted by default.

Pipes & redirects

When stdin is not a TTY, the CLI reads pipe content and combines it with the -p prompt:

git log --oneline -n 30 | forgeax -p "Rank these commits by risk"
git diff main...HEAD | forgeax -p "Write a PR description"
cat build.log | forgeax -p "Find the failure root cause and fix steps"

Extended thinking

forgeax -p "Design a cache invalidation strategy" --thinking
forgeax -p "..." --thinking 8000    # optional token budget

Skills / Commands / Plugins

forgeax --skills ./my-skills,~/.forgeax/skills
forgeax --commands ./.forgeax/commands
forgeax --plugins ./plugins

When omitted, project and user directories are scanned automatically (see Quickstart).

MCP

forgeax --mcp ./.forgeax/mcp.json
forgeax --mcp-token github=GITHUB_TOKEN

Details in MCP. Expose this kernel’s tools to other MCP clients:

forgeax mcp-serve
forgeax mcp-serve --allow-writes   # allow mutating tools (default is read-leaning)

Permission posture

forgeax --permission-mode default
forgeax --permission-mode acceptEdits
forgeax --permission-mode plan
# Dangerous: auto-approve all permission prompts (refused as root)
forgeax --yes

Declarative rules live in settings — see Permissions.

OS sandbox (Bash)

forgeax --sandbox      # or FORGEAX_SANDBOX=1 / settings.sandbox.enabled
forgeax --no-sandbox

macOS uses Seatbelt; Linux uses bwrap. If unavailable, the CLI degrades loudly (never silently pretends to be sandboxed).

Memory

forgeax --memory ./.forgeax/memory
forgeax --no-memory

Hooks

forgeax --hooks ./hooks.json

Config may be a top-level hooks map or wrapped as { "hooks": { ... } }.

Web search

forgeax --search-url https://search.example/api
# or env FORGEAX_SEARCH_URL / BRAVE_API_KEY

Without a backend, the web_search tool is hidden.

Studio sidecar (advanced)

forgeax --serve --sock /tmp/forgeax.sock

Exposes the kernel as a JSON-RPC sidecar to a host (Studio / orchestrator). Everyday CLI users usually do not need this.