CLI reference

The Forven CLI drives the same local lab the web UI uses, from a terminal. It is aimed at operators and developers who want scriptable access to authentication, the strategy registry, the trading daemon, market data, the brain, and diagnostics.

The CLI is the forven entry point, run as a Python module:

python -m forven <group> <command> [options]
python -m forven --version

Every command is defined in a single entry point (forven/cli.py); python -m forven calls it via forven/__main__.py. The groups below mirror the subsystems documented elsewhere in this wiki.

Conventions

• <required> arguments are positional; [--optional] flags are shown in brackets with their defaults.
• The CLI reads and writes the same local store as the app: SQLite plus workspace files under your Forven data directory. See the configuration reference for precedence and locations.
• Several commands run in the foreground and block until you interrupt them (forven daemon start, forven bot start, forven lab worker). Run them in a dedicated terminal.
• "Migrate" commands import from a prior workspace; you can skip them on a fresh install.

Quick start

A first-time setup runs four commands, then a verify:

python -m forven configure          # pick AI providers, run OAuth
python -m forven workspace init     # operator profile, rules, risk-per-trade
python -m forven db init            # create the SQLite schema
python -m forven status             # confirm subsystems are up

By default execution stays in paper mode. You set it explicitly with forven execution mode paper.

Command groups at a glance

Authentication & configuration

Manage credentials for AI providers. The supported providers are openai, minimax, and lmstudio. Forven uses bring-your-own-key model access — see models & providers for how keys are stored locally.

python -m forven auth status                  # all provider profiles + token expiry
python -m forven auth login <provider>        # start OAuth for openai | minimax
python -m forven auth refresh <provider>      # force-refresh tokens (openai | minimax)
python -m forven auth migrate                 # import tokens from a prior workspace
python -m forven configure                    # interactive wizard: select providers, run OAuth
python -m forven ai ask <provider> <prompt> [--model <ID>]

forven ai ask is a one-shot test call to confirm a provider works; the model defaults to that provider's default.

Database & workspace

python -m forven db init                          # create SQLite schema
python -m forven db migrate                       # import prior JSON state into SQLite
python -m forven db restore-snapshot <id>         # restore a strategy's stage from a migration snapshot
python -m forven db status                         # row counts for every table
python -m forven workspace init [--force]          # write operator profile + rules (--force overwrites)
python -m forven workspace list                    # list identity files
python -m forven workspace read <filename>         # print one workspace file

The workspace holds your operator profile — name, capital, risk-per-trade, and trading rules — which the brain reads as context.

Strategies & lifecycle

Browse and maintain the strategy registry. The real lifecycle stages are researching → backtesting → quick_screen → gauntlet → paper → live (deployed) → retired. The public site simplifies these to screen / gauntlet / candidate / live, where the public "candidate" is the real paper stage. See the pipeline for the full lifecycle.

python -m forven strategies list [--status <filter>]
python -m forven strategies triage-stale [--days <N>] [--apply]
python -m forven strategies triage-orphans [--apply]
python -m forven strategies optimize <strategy_id>

• triage-stale dry-runs by default. It finds quick_screen strategies with no activity older than --days (default 7) that never advanced, and archives them only when you pass --apply.
• triage-orphans finds strategies whose runtime type is not registered — typically a fabricated class name. Orphans silently fail optimization, gates, and execution. --apply demotes them to a research_only stage so they stop wasting cycles.
• optimize grid-searches parameters and runs walk-forward analysis on the top candidates, printing best params, fitness, the WFA verdict, and degradation.

Backtesting & walk-forward (scanner)

The scanner evaluates a fixed set of predefined strategies — backtest, fitness scoring, and out-of-sample walk-forward.

python -m forven scanner run                                       # one multi-strategy live scan
python -m forven scanner status                                    # last scan: timestamp, trades, total PnL%
python -m forven scanner strategies                                # list the predefined strategies
python -m forven scanner backtest [--bars <N>] [--strategy <ID>]
python -m forven scanner walkforward [--bars <N>] [--splits <N>] [--strategy <ID>]

Notes from the source:

• --bars counts hourly bars: 1440 is 60 days, 168 is one week. Omit it to read the value from settings.
• walkforward defaults to 1440 bars and 3 splits. It prints in-sample vs out-of-sample Sharpe, degradation, OOS trades/return, and a PASS/FAIL verdict.
• Walk-forward across the whole set is compute-intensive (roughly fifteen minutes for the full set with three splits). Pass --strategy <ID> to validate a single strategy quickly.

Fitness and degradation are evaluated against fixed thresholds in the lab; treat any printed score as an illustrative measure of out-of-sample survival, not an expectation of profit. Read the gauntlet and metrics docs for what each number means.

Evolution pipeline

Drive the lifecycle steps the research daemon otherwise runs autonomously.

python -m forven evolution status                  # counts + sample IDs per stage
python -m forven evolution ideate                  # delegate research to the strategy-developer agents
python -m forven evolution test                    # assign walk-forward to the simulation agent
python -m forven evolution review                  # weekly review: retire underperformers, queue post-mortems
python -m forven evolution optimize [strategy_id]  # optimize one, or all deployed strategies if omitted

Trading & execution

python -m forven daemon start                  # start the trading daemon (foreground, INFO logs)
python -m forven daemon status                 # running state, scan count, last scan, current prices
python -m forven execution mode [mode]         # get, or set to paper | live (set to live prompts to confirm)
python -m forven execution status             # mode, execution-trader tasks, account, open positions
python -m forven execution reconcile          # reconcile SQLite positions against the exchange
python -m forven trades list [--limit <N>]    # recent trades (default 20): asset, direction, entry, PnL%, strategy
python -m forven trades open                   # all non-closed positions with opened_at timestamps

Execution mode

forven execution mode with no argument reports the current mode; with paper or live it sets it. The default is paper.

forven execution reconcile audits open trades in SQLite against positions on the exchange and reports synced status plus any discrepancies. It is safe to run anytime.

Risk

python -m forven risk status      # kill-switch / daily-halt state, high-water-mark, limits, exposure
python -m forven risk reset       # manually reset the kill-switch after review (prompts to confirm)

forven risk status groups open positions and shows net, gross-long, and gross-short exposure against your drawdown, daily-loss, and per-trade limits.

Brain & agents

The brain is the sole orchestrator: it reads pending tasks, strategy state, and market data, makes decisions, and assigns follow-up work to agents. Agents never task each other and never place trades directly.

python -m forven brain invoke [--provider <p>] [--model <m>]   # run one orchestration cycle
python -m forven brain ask <question> [--provider <p>]         # ask the brain, using full context
python -m forven brain tasks                                   # pending brain_invoke tasks (last 20)

Manage the agent team:

python -m forven team list
python -m forven team create <agent_id> <name> --role <description> `
    [--model <provider>] [--model-id <ID>] `
    [--schedule <expr>] [--schedule-type <cron|interval|on_demand>]
python -m forven team inspect <agent_id>
python -m forven team assign <agent_id> <task_description> [--type <type>] [--title <title>]
python -m forven team enable <agent_id>
python -m forven team disable <agent_id>

--role is required on create. The default model provider is openai and the default --schedule-type is on_demand. team assign queues work for the brain to dispatch; the default task type is research.

Market data & regimes

python -m forven market-data backfill [--asset <asset>] [--days <N>]   # historical funding rates
python -m forven market-data collect                                   # snapshot funding/OI/mark prices
python -m forven market-data coverage [--asset <asset>]                # per-asset, per-metric coverage
python -m forven regime status                                         # current regimes for tracked assets

• backfill defaults to 365 days and accepts a specific asset (e.g. BTC, ETH, SOL) or all. It never deletes existing rows — re-running fills gaps.
• regime status classifies each asset as TREND_UP, TREND_DOWN, RANGE_BOUND, or HIGH_VOL, with confidence and the underlying ADX, EMA alignment, ATR ratio, and RSI. See market regimes for how regimes gate strategy families.

Regime Lab worker

The Regime Lab is an isolated background service with its own database and job queue (lab_jobs).

python -m forven lab worker [--once] [--poll-seconds <N>] [--lease-seconds <N>]
python -m forven lab status

--once processes a single job and exits. Defaults are a 1.0-second poll and a 90-second lease, with rotating file logs.

Scheduler

python -m forven scheduler list                 # jobs: type, schedule, enabled, last status, next run
python -m forven scheduler migrate              # import jobs from a prior workspace
python -m forven scheduler enable <job_id>
python -m forven scheduler disable <job_id>
python -m forven scheduler run <job_id>         # force-run now (async)

Job leases (default 90 seconds) prevent concurrent runs of the same job. If a job appears stuck, wait for the lease to expire before retrying. See troubleshooting for stale-lock recovery.

Discord bot

python -m forven bot start                      # start the bot daemon (foreground; blocks until interrupt)
python -m forven bot status                     # singleton-lock status: lock held, active PID, stale detection
python -m forven bot send <channel> <message>   # send to a channel by name or ID

bot start blocks; use a process supervisor to keep it alive across reboots.

Diagnostics & export

python -m forven doctor [--json]     # health checks: DB, auth, scheduler, costs, interrupts
python -m forven status              # overview: mode, auth providers, DB counts, workspace files
python -m forven dump [--out <path>] # export operator profile + recent decisions/approvals as JSON
python -m forven fts5-rebuild        # rebuild brain full-text search indices

• forven doctor exits with code 2 on a FAIL, so it scripts cleanly into CI or a monitor. --json emits machine-readable output.
• forven dump writes a JSON bundle of your operator profile, the last 50 decisions, and the last 50 approvals. It excludes brain memory and API keys. Without --out it prints to stdout.
• forven fts5-rebuild repairs brain full-text search index drift. It is idempotent and prints row counts per index.

Steps: verify a clean install

1. Run python -m forven configure and complete OAuth for at least one provider.
2. Run python -m forven workspace init to write your operator profile.
3. Run python -m forven db init to create the schema.
4. Run python -m forven status and confirm execution mode, auth, and database all report ready.
5. Run python -m forven doctor for a full health pass; resolve any FAIL lines before continuing.

What you'll see: status prints a compact overview (execution mode, authenticated providers, database row counts, workspace file count). doctor prints a per-check table with an overall PASS / WARN / FAIL and exits non-zero on failure.

Caveats

These are real, current rough edges from the code, surfaced honestly:

• Testnet is the supported exchange path. Both modes route to the HyperLiquid testnet by default; mainnet is default-deny and unsupported.
• The kill-switch requires a manual reset. Trading stays halted until you run forven risk reset.
• Orphan strategies fail silently. Run forven strategies triage-orphans (dry-run) periodically to catch them.
• Walk-forward is slow at scale. Scope it to one strategy with --strategy when you need a fast answer.
• Foreground daemons block. daemon start, bot start, and lab worker hold the terminal; run each in its own window or under a supervisor.
• Migration is optional. The migrate subcommands and the OpenClaw workspace path only matter if you are importing from a prior install.

Related

• Configuration reference — config precedence, locations, and key groups the CLI reads.
• MCP server — drive Forven from an AI client instead of the terminal.
• Troubleshooting & recovery — stuck jobs, stale locks, and reconnection.