CLI reference

Forven has two command-line interfaces:

• The operator CLI, python -m forven, works directly on the same local store the web UI uses: authentication, the strategy registry, the trading daemon, market data, the brain, and diagnostics.
• The agent CLI, python -m forven.agent, drives a running backend over HTTP and prints JSON. It is built for AI harnesses that work by running shell commands. See agent CLI.

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

Every operator command is defined in one entry point (forven/cli.py); python -m forven calls it via forven/__main__.py. Installed as a package, the same commands are available as forven and forven-agent. 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 from the terminal. auth login and auth refresh take openai or minimax; ai ask also takes lmstudio. Forven uses bring-your-own-key model access — most people connect providers in the app under Agents → Setup → Providers; see models & providers.

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 lifecycle stages are quick_screen → gauntlet → paper → live_graduated; the graveyard is archived, rejected, and backtest_failed. The public site simplifies these to screen / gauntlet / candidate / live, where the public "candidate" is the 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 archives them as untestable (untestable:broken_code) 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                  # queue a strategy-creation task (within today's budget)
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

evolution ideate fills free slots with strategy-creation tasks for the Strategy Developer, which writes an idea and builds strategies from it. It queues nothing, and says why, when the system is in Manual or Semi mode, today's budget is spent, or enough creation tasks are already in flight. To hand Forven an idea of your own, use The Forge → + Submit idea instead; submitted ideas run in every mode.

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 the mode, or set it to paper (live is refused)
python -m forven execution status             # mode, 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; forven execution mode paper sets paper. The default is paper. The mode is a global label: it does not decide whether orders are real. Strategies at the Live stage and live-armed bots do, as execution modes explains. (The command's own help text still describes the older model.)

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. Without a bot, a Discord webhook URL (DISCORD_WEBHOOK_URL or Settings → Notifications → Discord transport) still delivers notifications to one channel.

Bot sandbox (Windows)

python -m forven bot-sandbox      # prepare and check the low-integrity sandbox bots run in

On Windows, Bot Factory bots run in a low-integrity sandbox by default. The command prepares it and reports one of:

• On — bots start at low integrity.
• Unusable — bots start without the sandbox; the problems are listed and the command exits with code 1.
• Off — not on Windows, or FORVEN_BOT_SANDBOX=0 is set.

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 the brain's full-text recall 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.

Agent CLI (python -m forven.agent)

The agent CLI is a thin HTTP client for AI harnesses (Claude Code, Codex and similar) that work by running shell commands. Every subcommand prints one JSON document to stdout and exits 0 on success, or non-zero with the message on stderr. It needs the backend running; it covers the same research loop as the MCP server.

python -m forven.agent health
python -m forven.agent readiness --symbol BTC/USDT --timeframe 1h --streams funding,oi
python -m forven.agent register --file C:\path\to\strategy.py
python -m forven.agent backtest --strategy S02545 --dataset BTC/USDT-1h --compact
python -m forven.agent gate-report S02545
python -m forven.agent data-census --stream ohlcv --limit-worst 20
python -m forven.agent breadth S02545
python -m forven.agent paper-pool
python -m forven.agent readmit-candidates --days 30
python -m forven.agent requeue S02545,S02604
python -m forven.agent live-recheck

Global options: --base-url (default FORVEN_API_URL, else http://127.0.0.1:8003), --api-key, --operator-key, and --timeout (seconds, default 300).

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:

• Paper is the supported mode. The CLI cannot switch to live; mainnet is default-deny and unsupported.
• The kill-switch requires a manual reset. Live trading stays halted until you run forven risk reset (or use Reset Halt in the app). Paper is never halted.
• 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.