Skip to content

cli-reference.md

Latest commit

 

History

History
292 lines (212 loc) · 8.96 KB

cli-reference.md

File metadata and controls

292 lines (212 loc) · 8.96 KB

CLI Reference

Full reference for all index.js command-line flags.

Synopsis

node index.js --goal="<description>" [--type=<type>] [options]

Required

Flag Type Description
--goal string What the AI should build or fix. This is the natural-language project goal passed directly to the planner.

Project Configuration

Flag Type Default Description
--type string node Project type. Affects system prompts and planning strategy. See full type list below.
Allowed types: embedded | cli | node | web | htmlcss | python | react | api | rust | docker | arduino | nextjs | go | fastapi | bash | svelte | tauri | vscode-ext | terraform | platformio | dotnet | cpp | c

| --build | string | (none) | Shell command to run after each applied patch. E.g. "npm test", "pytest", "cargo test", "dotnet test", "make" | | --target | string | cwd | Absolute or relative path to the project directory. All source file reads, patch writes, and build commands run relative to this directory. | | --max-budget | number | 5.00 | Maximum USD spend before APE halts. Checked before every API call. | | --max-tokens | number | 500000 | Maximum cumulative prompt + completion tokens before APE halts. | | --resume | boolean | false | Continue from an existing ape-state.json. Restores task queue, budget counters, and iteration index. | | --no-git | boolean | false | Skip all git operations (branch creation, staging, commits). Useful for non-git projects or CI pipelines. |

Review Mode

These flags override the automatic risk-based mode selection.

Flag Type Default Description
--lite-only boolean false Force LITE mode (single OpenAI pass) for every task. Fastest and cheapest. No adversarial review.
--debate-only boolean false Force DEBATE mode (4-phase GPT↔Claude) for every task. Slowest but highest confidence.

Default behaviour (no flag): riskClassifier.js scores each change set on a 0–100 scale. Low/medium risk → LITE. High/critical risk → DEBATE. See risk-gated-debate.md.

--lite-only and --debate-only are mutually exclusive. If both are set, --debate-only wins.

Patch Application

Flag Type Default Description
--apply boolean false Actually write patches to disk via git apply. Without this flag, APE runs in dry-run mode — plans, reviews, and shows the diff, but never modifies files.
--dry-run boolean (implied) No-op flag provided for explicitness. APE is always in dry-run mode unless --apply is set.

Safe default: omitting --apply is intentional. Run APE without it first to review what it would do.

Safety Flags

Flag Type Default Description
--allow-protected boolean false Allow APE to propose changes inside src/protocol, src/radio, and src/routing. Without this flag, patches touching these paths are logged as warnings and the risk score is elevated.
--allow-isr boolean false Allow patches containing ISR, IRAM_ATTR, or interrupt handler code. Without this, such patches trigger automatic escalation to DEBATE mode.
--confidence-threshold number 70 Minimum consensus confidence score (0–100) required to pass. Tasks scoring below this are blocked and reported as failed. Raise for critical firmware; lower for experimental work.

Commit Control

Flag Type Default Description
--auto-commit boolean false After each successful apply + build, automatically propose a commit (human still sees a Y/N prompt). Without this, APE asks explicitly before staging files.

Debug

Flag Type Default Description
--verbose boolean false Print full raw model JSON responses after each debate phase. Useful for diagnosing unexpected AI outputs or tuning prompts. Only affects DEBATE mode (LITE mode has no per-phase viewer).

Examples

1 — Safe preview, no changes written

node index.js \
  --goal="Add input validation to the user registration endpoint" \
  --type=node \
  --build="npm test"

APE plans, reviews, and shows the diff. Nothing written to disk.

2 — Full run, apply patches

node index.js \
  --goal="Add input validation to the user registration endpoint" \
  --type=node \
  --build="npm test" \
  --apply \
  --max-budget=3.00

3 — Force full adversarial debate, allow protected paths

node index.js \
  --goal="Refactor the payment transaction rollback handler" \
  --type=node \
  --debate-only \
  --allow-protected \
  --apply \
  --max-budget=10.00

All tasks go through the 4-phase GPT↔Claude debate, regardless of risk score.

4 — Force debate with verbose model JSON

node index.js \
  --goal="Refactor routing layer" \
  --type=embedded \
  --debate-only --apply --verbose

Prints raw model JSON after each debate phase. Useful for debugging model behaviour.

5 — Quick LITE pass, high confidence threshold

node index.js \
  --goal="Update the app version in package.json" \
  --type=node \
  --lite-only \
  --confidence-threshold=90 \
  --apply

6 — Resume an interrupted session

node index.js \
  --goal="Add JWT authentication to the FastAPI backend" \
  --type=python \
  --build="pytest" \
  --resume \
  --apply

6 — Rust CLI project, no git

node index.js \
  --goal="Add async file processing with a progress bar" \
  --type=node \
  --target=./my-api \
  --build="npm test" \
  --no-git \
  --apply \
  --max-budget=2.00

Environment Variables

Set in .env (copy from .env.example):

Provider assignment

Variable Default Description
PROPOSER_PROVIDER openai Provider for Phases 1 & 3 (proposal + rebuttal). Values: openai, claude, opencode
PROPOSER_MODEL gpt-4.1 Model name passed to the proposer provider
CRITIC_PROVIDER claude Provider for Phases 2 & 4 (challenge + final audit). Values: openai, claude, opencode
CRITIC_MODEL claude-opus-4-5 Model name passed to the critic provider

OpenAI

Variable Required Default Description
OPENAI_API_KEY ✅ — OpenAI API key
OPENAI_MODEL ❌ gpt-4.1 Default GPT model (used if PROPOSER_MODEL / CRITIC_MODEL not set)
OPENAI_TIMEOUT_MS ❌ 120000 Per-request timeout
OPENAI_MAX_RETRIES ❌ 3 Retry attempts on transient errors

Anthropic (Claude)

Variable Required Default Description
ANTHROPIC_API_KEY ✅ — Anthropic API key
ANTHROPIC_MODEL ❌ claude-opus-4-5 Default Claude model
ANTHROPIC_TIMEOUT_MS ❌ 120000 Per-request timeout
ANTHROPIC_MAX_RETRIES ❌ 3 Retry attempts on transient errors

OpenCode Zen API

OpenCode exposes an OpenAI-compatible endpoint (/zen/v1/chat/completions). Free models require no API key.

Variable Required Default Description
OPENCODE_ZEN_BASE_URL ✅ (if using opencode) — Base URL, e.g. https://opencode.ai
OPENCODE_ZEN_API_KEY ❌ — API key (leave blank for free-tier models)
OPENCODE_DEFAULT_MODEL ❌ glm-5-free Default model when PROPOSER_MODEL/CRITIC_MODEL is not set
OPENCODE_ALLOW_ANY_MODEL ❌ 0 Set to 1 to bypass the built-in model allowlist

Built-in allowlist (free models, accepted without OPENCODE_ALLOW_ANY_MODEL=1):

  • glm-5-free
  • minimax-m2.5-free
  • kimi-k2.5-free
  • big-pickle

Runtime / budget

Variable Default Description
MAX_BUDGET 5.00 USD cap before APE halts
APE_MAX_TOKENS 500000 Token cap before APE halts
RISK_THRESHOLD 55 Risk score (0-100) above which DEBATE mode is forced
DEBATE_ROUNDS 4 Max phases per debate session
DEBUG ❌ Set to 1 for full stack traces on fatal errors

7 — All-free debate with OpenCode

# .env additions
OPENCODE_ZEN_BASE_URL=https://opencode.ai
PROPOSER_PROVIDER=opencode
PROPOSER_MODEL=glm-5-free
CRITIC_PROVIDER=opencode
CRITIC_MODEL=kimi-k2.5-free
node index.js \
  --goal="Refactor the data pipeline error handling" \
  --type=python \
  --build="pytest" \
  --debate-only \
  --apply

Cost: $0.00 (both models are free-tier on OpenCode).

8 — Mixed pairing: GPT proposes, OpenCode critiques

# .env additions
OPENCODE_ZEN_BASE_URL=https://opencode.ai
PROPOSER_PROVIDER=openai
PROPOSER_MODEL=gpt-4.1
CRITIC_PROVIDER=opencode
CRITIC_MODEL=minimax-m2.5-free
node index.js \
  --goal="Add pagination to the REST API" \
  --type=api \
  --build="npm test" \
  --apply