CLI Reference

All commands are available via the forge CLI after installing aether-forge.

Agent Lifecycle

`forge generate-fast`

Generate an agent instantly from an idea.


forge generate-fast \
  --name "My Agent" \
  --idea "ETH swing trader" \
  --output ./my-agent \
  --strategy-file ./strategy.md \
  --wallet \
  --autonomous \
  --skills elsa:trading \
  --planner-mode openrouter \
  --planner-model deepseek/deepseek-r1 \
  --no-registry

Flag	Description
`--name`	Agent name
`--idea`	Plain-language description
`--output`	Output directory
`--strategy-file`	Path to strategy markdown file
`--wallet`	Provision a real OWS wallet
`--autonomous`	Enable autonomous mode
`--skills`	Skills from registries (e.g., `elsa:trading`)
`--planner-mode`	LLM provider (`ollama`, `anthropic`, `openai`, `gemini`, `openrouter`)
`--planner-model`	Specific model name
`--no-registry`	Skip local registry

`forge generate-slow`

Autoresearch refinement loop.


forge generate-slow --name "My Agent" --idea "basis capture" \
  --output ./my-agent --max-iterations 5

`forge validate`

Validate all JSON artifacts in an agent directory.


forge validate ./my-agent

`forge eval-pack`

Run scenario-based evaluation.


forge eval-pack ./my-agent

`forge run`

Run an agent continuously.


forge run ./my-agent \
  --environment sandbox \
  --mode paper \
  --interval 30 \
  --auto-approve \
  --autoresearch \
  --knowledge \
  --a2a-port 9001 \
  --health-port 8080 \
  --json-log ./logs/agent.jsonl \
  --pid-file ./agent.pid

Flag	Description
`--environment`	Policy/runtime environment, such as `sandbox`, `paper`, `canary-live`, or `production`
`--mode`	Crypto scaffold backend: `simulated`, `paper`, or `live`
`--interval`	Seconds between ticks
`--auto-approve`	Skip human approval prompts
`--autoresearch`	Enable self-improvement loop
`--knowledge`	Enable Layer 4 MemPalace
`--a2a-port`	Start A2A server on this port
`--health-port`	Health check HTTP server
`--json-log`	Path for structured JSON logs
`--planner-mode`	Override LLM provider
`--planner-model`	Override model

`forge promote-draft`

Promote agent to next stage.


forge promote-draft ./my-agent --target paper --approver "ops-team"

Strategy


forge strategy view ./my-agent        # Show parameters + performance
forge strategy accept ./my-agent <proposal-id>   # Apply improvement proposal
forge strategy reject ./my-agent <proposal-id>   # Discard proposal

Wallet


forge wallet-create --name agent-wallet
forge wallet-list
forge wallet-account --name wallet --chain evm
forge wallet-sign-message --name wallet --chain evm --message "hello"
forge wallet-sign-tx --name wallet --chain evm --tx-hex 0x...
forge wallet-send-tx --name wallet --chain evm --tx-hex 0x...
forge wallet-import --name imported --mnemonic "word1 word2 ..."
forge wallet-export --name wallet
forge wallet-delete --name old-wallet
forge wallet-backup .
forge wallet-restore backup.json

Agent Registry


forge agent-list                      # List all agents
forge agent-info <id>                 # Show details
forge agent-remove <id>              # Archive agent
forge agent-register <id>           # Register on Base mainnet
forge agent-discover --agent-id 1    # Inspect one on-chain agent
forge agent-discover --address 0x... # Count agents owned by an address
forge agent-send <url> --capability X --payload '{}'

Security


forge security-check . --harden     # Run 8-point audit
forge halt .                         # Activate kill switch
forge resume .                       # Clear kill switch

Skills


forge skills-search "trading"
forge skills-add elsa:trading --project ./my-agent
forge elsa-list
forge elsa-list --category perpetuals

Replay Debugging


forge replays ./my-agent             # List all replay files
forge replays ./my-agent --limit 50  # Last 50
 
forge replay-show ./my-agent/replays/tick_0001.json
forge replay-show ./my-agent/replays/tick_0001.json --full     # Show payloads
forge replay-show ./my-agent/replays/tick_0001.json --steps-only

Shows what the LLM proposed, policy decisions, and results per step.

Artifacts & Migration

`forge eval`

Run a single scenario against the native runtime (not the full pack).


forge eval ./my-agent --scenario btc-up-trend

`forge artifact-compat`

Check compatibility between two artifact directories — reports whether a target version is backward-compatible with the current spec, and whether a migration contract is required.


forge artifact-compat ./my-agent-v1 ./my-agent-v2

`forge artifact-migration-plan`

Generate a migration contract skeleton for a single artifact type. Use this when a major-version bump requires data hydration.


forge artifact-migration-plan ./my-agent-v1 ./my-agent-v2 \
    --artifact-type capability-manifest

`forge migrate`

Dry-run or apply a migration contract. --apply is required for any mutation.


# Memory database migration; default is dry-run
forge migrate memory ./my-agent \
    --contract ./my-agent/migration-contract.json
 
# Apply after reviewing the dry-run report
forge migrate memory ./my-agent \
    --contract ./my-agent/migration-contract.json \
    --apply
 
# Single artifact migration
forge migrate artifact ./my-agent/agent-spec.json \
    --target agent-spec \
    --contract ./migration-contract.json

Scaffold

The scaffold-* commands operate on the generated agent project (the src/strategy/, src/runtime/, src/policies/ layout that generate-fast produces).

`forge scaffold-run`

Drive the scaffold’s eval flow without going through the framework’s top-level eval command — useful when iterating on src/strategy/router.py.


forge scaffold-run ./my-agent

`forge scaffold-policy-sync`

Diff the policy logic embedded in the scaffold’s Python (e.g. src/policies/policy_bundle.py) against policy-bundle.json and bring the JSON back into sync.


forge scaffold-policy-sync ./my-agent

`forge scaffold-live-status`

Inspect the scaffold’s live exchange adapter — connectivity, last quote latency, configured chain — without firing real orders.


forge scaffold-live-status ./my-agent

Replay & Resume

`forge resume-replay`

Resume a runtime session from a tick replay file. The session re-hydrates from step_ledger, working_set, and pending_approvals, then continues from the hold point. Pair with --approve to auto-approve a held step.


forge resume-replay ./my-agent \
    --replay ./my-agent/replays/tick_0008.json \
    --approve approver-cli-2026-05-02

Payments

`forge x402-call`

Fire a single x402 payment call manually (real money on Base mainnet). Respects the agent’s persistent budget (x402_state.json), the halt file, and the audit log.


forge x402-call ./my-agent \
    --url https://api.example.com/paid/swap-quote \
    --method POST \
    --body '{"in":"USDC","out":"WETH","amount":"100"}' \
    --max-per-call-usd 0.05 \
    --confirm-live

Models & Config

`forge models-list`

List available LLM models from a provider — useful when picking a model for the planner block in aether-forge.json.


forge models-list --provider openrouter --query claude
forge models-list --provider ollama
forge models-list --provider openai

`forge config-validate`

Validate an aether-forge.json against the configuration schema (planner block, runtime block, mcp_servers block).


forge config-validate ./my-agent/aether-forge.json

`forge init`

Initialize a new aether-forge.json in the current (or named) directory — shortcut for adding the framework to an existing project without running the full generator.


forge init                                # in cwd
forge init --output ./my-existing-project/aether-forge.json

Wallet (extra)

`forge wallet-info`

Read full wallet metadata (provider, vault path, policy ID, scoped API key handle) for a single named wallet.


forge wallet-info --name agent-wallet

Shell completions

`forge completions`

Generate shell completion scripts.


forge completions bash > ~/.local/share/bash-completion/completions/forge
forge completions zsh  > ~/.zfunc/_forge
forge completions fish > ~/.config/fish/completions/forge.fish

Diagnostics


forge doctor                         # Full system check (8 round-trip checks)

Probes Python, jsonschema, OWS SDK, cryptography, Ollama, OpenRouter, the SQLite memory layer, and MemPalace; prints a one-line verdict.