Docs · CLI reference
ResearchForge CLI reference: every command and flag
--help, and most take --json.researchforge
researchforge autorunRun the autonomous research loop until it stalls, hits the target, or times out.
- --stall
- Stop a plan after N consecutive non-improving experiments.
- --global-stall
- Stop the loop after N rounds with no improvement anywhere.
- --max-rounds
- Hard cap on synthesis rounds.
- --max-hours
- Wall-clock limit — for overnight runs.
- --target
- Stop when the primary metric reaches this value (defaults to the contract's objective.primary_metric.target_value).
- --compound
- Each round's experiments build on a node of the experiment graph instead of the baseline (default: on).
- --explore
- UCB1 exploration constant. 0 always expands the current best; higher values revisit under-explored branches instead.
- --merge
- Each round, try combining two independent winners into one multi-parent experiment. When their diffs overlap the AI is asked to author the combination as a single patch.
- --observe
- After each experiment, have the AI read its benchmark output and record one paragraph on what the run showed. Costs one AI call per experiment.
- --resynthesize
- Generate new hypotheses from results each round (default: on).
- --provider, -p
- AI provider: anthropic|google|openai.
- --model, -m
- Override the AI model name.
- --resume
- Continue the interrupted loop in .researchforge/autorun.json.
- --yes, -y
- Unattended — skip the first-batch approval prompt.
- --dry-run
- Print the move the loop would make next and exit. No AI, nothing runs.
- --no-metric-gate
- Record every result instead of rejecting on the local metric — for when the local benchmark is only a signal (e.g. Kaggle). Hard constraints still reject.
- --kaggle
- Kaggle-aware mode: record every result (implies --no-metric-gate), tag how far each local metric can be trusted, mark what is worth Kaggle GPU time, and list submission candidates at the end.
- --judgment
- After each experiment, decide whether it is worth Kaggle GPU validation (y/n/skip prompt; queued as a question when nobody is at the terminal).
- --json
- Emit machine-readable JSON output.
researchforge dashboardOpen the live ResearchForge dashboard at localhost:7842.
- --run
- Run to visualize (default: the latest run).
- --output
- Write the dashboard here instead of the default path.
- --open
- Open the dashboard in the default browser.
- --json
- Emit machine-readable JSON output.
- --legacy
- Force the old static HTML report (repo projects).
- --port
- Port for the live dashboard [default: 7842]
researchforge doctorCheck that required and optional dependencies are available.
- --json
- Emit machine-readable JSON output.
researchforge hubRun the hub: every project on this machine, in one read-only dashboard.
- --port
- Preferred port (default 9000); falls back to a free one if busy.
- --background
- Run detached; manage with --status / --stop.
- --stop
- Stop the background hub and exit.
- --status
- Show whether the hub is running.
- --open
- Open the hub in the default browser.
- --prune
- Remove missing projects from the registry and exit.
researchforge initInitialize a ResearchForge project in the current directory.
- --claude
- Also install the Claude Code skills into .claude/skills/.
- --cursor
- Also install the Cursor rules into .cursor/rules/, with an always-on gateway.
- --json
- Emit machine-readable JSON output.
researchforge pathsShow every location ResearchForge uses in this project.
- --json
- Emit machine-readable JSON output.
researchforge runRun an experiment plan (alias for `experiment start`).
- <file>
- Experiment plan artifact (plan.yaml).
- --yes
- Skip the interactive confirmation.
- --stall
- Stop after N consecutive non-improvements.
- --monitor
- Start (or skip) the background live monitor for this run (default: auto on a TTY).
- --json
- Emit machine-readable JSON output.
researchforge serveRun the live monitoring server (read-only view of this project).
- --host
- Bind address (loopback by default; change with care).
- --port
- Preferred port (default 9000); falls back to a free one if busy.
- --background
- Run detached; manage with --status / --stop.
- --stop
- Stop the background monitor and exit.
- --status
- Show whether a background monitor is running.
- --open
- Open the monitor in the default browser.
researchforge statusShow the status of the current ResearchForge project.
- --json
- Emit machine-readable JSON output.
researchforge validateRepeatedly re-run promising finalists to confirm or reject them (Stage 3).
- <run_id>
- e.g. run-001
- --experiment, -e
- Validate only these experiment ids.
- --n
- Repeats per finalist for this validation, overriding the contract's validation.repeat_finalists.
- --stdev-max
- Refuse to validate a finalist whose repeats have a standard deviation above this, however good its average looks.
- --yes
- Skip the cost confirmation.
- --json
- Emit machine-readable JSON output.
researchforge kaggle
researchforge kaggle add-hypothesisInject your own idea into the pool now; the next prepare-round sees it first.
- <competition>
- Kaggle competition slug or URL
- <idea>
- The idea, in one sentence
- --rationale
- --priority
- 1 = try first
researchforge kaggle archiveArchive a round: it leaves the views, is never a parent and never "best". Reversible.
- <competition>
- Kaggle competition slug or URL
- <round_id>
- Round number, e.g. 7 or R7
- --restore
- Bring an archived round back
- --reason
- Why, for the record
researchforge kaggle arxiv-scanScan arXiv for new papers and inject technique ideas into the hypothesis pool.
- <competition>
- Kaggle competition slug or URL
- --query, -q
- arXiv search query (auto-generated from competition if omitted)
- --max-results
- Max papers to scan
- --background
- Run as background daemon (checks daily)
- --once
- Run one scan cycle and exit
researchforge kaggle askAsk the person a question without stopping the loop; it reaches their phone.
- <competition>
- Kaggle competition slug or URL
- <question>
- The question, in one sentence
- --options
- Allowed answers, comma-separated (e.g. yes,no). Commas inside brackets or quotes stay in the answer; separate with | to keep every comma.
- --default
- Suggested answer
- --blocks
- An exact pool idea that waits for the answer (repeatable)
- --hold
- Start no new round until it is answered
- --action
- Settings an answer changes when the person picks it: "<answer> => compute:kaggle, max_experiments:40" (repeatable, one per answer)
researchforge kaggle auto-runRun experiments automatically when the pool has untested ideas.
- <competition>
- Kaggle competition slug or URL
- --on
- Turn the auto_run_sensor on or off for this project
- --driver
- claude (Claude Code), cursor (Cursor agent), byok (API key), or auto: match how this project runs (the default the first time)
- --rounds
- Rounds per launch (1-20)
- --daily-max
- Most rounds per day, all launches (1-100)
- --max-minutes
- Stop a launch after this long
- --model
- Model for the claude / cursor driver
- --cli-path
- Path to the claude / cursor-agent binary
- --stop
- Stop the launch that is running now
- --now
- Check the gates and start a launch now
- --dry-run
- Show the gates and the exact command; start nothing
researchforge kaggle auto-run-keyStore a token or API key for unattended auto-run, typed at a hidden prompt.
- <name>
- CLAUDE_CODE_OAUTH_TOKEN, CURSOR_API_KEY or an AI API key
researchforge kaggle cloud-gpu-setupConfigure a pay-per-hour cloud GPU as a compute target.
- <competition>
- Kaggle competition slug or URL
- --provider
- Cloud GPU provider: runpod, lambda, vast or aws
- --api-key-env
- Env var name that holds the API key (e.g. RUNPOD_API_KEY)
- --gpu-type
- GPU type/size to provision (leave blank to use cheapest available)
- --region
- Cloud region (Lambda Labs only, e.g. us-west-2)
- --python
- Python executable on the provisioned instance
- --rsync-data
- Copy competition data to the instance before each experiment
- --list-gpus
- List available GPU types for the provider and exit
- --image
- Docker image (RunPod/vast) or AMI id (AWS, required)
- --max-price
- Max $/hr (vast.ai offer filter; 0 = no limit)
- --ssh-key-name
- AWS: EC2 key pair name (required)
- --security-group-id
- AWS: security group allowing SSH (required)
researchforge kaggle colab-setupSet up Colab for unattended rounds: the plan, the GPU, and Google's Colab CLI.
- <competition>
- Kaggle competition slug or URL
- --plan
- free, pro, pro_plus, payg or enterprise
- --gpu
- T4, L4, G4, A100 or H100
- --high-mem
- High-RAM machine (Pro/Pro+)
- --install
- Install Google's Colab CLI if it is missing
researchforge kaggle computeSwitch compute for the next rounds.
- <competition>
- Kaggle competition slug or URL
- <target>
- One of: local, kaggle, colab, ssh, cloud, competition
researchforge kaggle dashboardOpen the Dagster-style dashboard showing all competitions, experiments, schedulers.
- --port
- Port to serve on
- --open
- Open in browser
- --json
- Print raw JSON and exit
- --daemon
- Start in background (survives terminal close)
- --stop
- Stop a running background dashboard
- --status
- Show whether dashboard is running
researchforge kaggle delete-roundDelete a round from the log for good. Prefer `kaggle archive`, which can be undone.
- <competition>
- Kaggle competition slug or URL
- <round_id>
- Round number, e.g. 7 or R7
- --yes
- Skip the confirmation
researchforge kaggle draftA setup in progress, shared with the dashboard's New competition page.
- <competition>
- Kaggle competition slug or URL
- --start
- Make a draft from gather-facts' output
- --form-json
- Answers to merge into the draft (JSON)
- --run
- Run the draft's setup now
- --json
- Print the draft as JSON
researchforge kaggle driverShow or switch the project's driver: who runs rounds and sensors unattended.
- <competition>
- Kaggle competition slug or URL
- <driver>
- claude, cursor or byok — omit to see the current one
- --model
- Model for this driver
- --sensors
- Route the sensors' AI calls (notebook ideas, arXiv, re-synthesis) through this driver
researchforge kaggle driver-loginSign a driver in for unattended runs — one command, run in your own terminal.
- <driver>
- claude, cursor, byok or colab
- --provider
- byok only: anthropic, gemini or openai
researchforge kaggle execute-roundExecute the proposal at .overnight_<slug>/proposal.json. Prints result JSON.
- <competition>
- Kaggle competition slug or URL
researchforge kaggle finishGenerate the morning report and send push notification. Call when all rounds are done.
- <competition>
- Kaggle competition slug or URL
researchforge kaggle gather-factsGather all competition facts and print as JSON. Runs in ~30s, zero user input.
- <competition>
- Kaggle competition slug or URL
- --refresh
- Force re-gather even if cached
researchforge kaggle ideationResearch-only mode: read competition, kernels, papers → prioritised plan.
- <competition>
- Kaggle competition slug or URL
researchforge kaggle keys openOpen the dashboard's Keys page in your browser (starting the dashboard if needed).
- <name>
- The key to scroll to (default: the page)
researchforge kaggle keys removeRemove a key ResearchForge stored (Kaggle's own files are left alone).
- <name>
- One of: kaggle, anthropic, gemini, openai, claude, cursor, colab, runpod, lambda, vast, aws
researchforge kaggle keys setSet a key at a hidden prompt — run it in your own terminal, never through an agent.
- <name>
- One of: kaggle, anthropic, gemini, openai, claude, cursor, colab, runpod, lambda, vast, aws
- --username
- kaggle only: username for a legacy key
researchforge kaggle keys statusWhich keys are set, where, and what the last test said. Never prints a value.
- <name>
- One key (default: all)
- --json
- Print JSON
researchforge kaggle keys testMake one harmless call with the stored key (a tiny prompt for the Claude token).
- <name>
- One of: kaggle, anthropic, gemini, openai, claude, cursor, colab, runpod, lambda, vast, aws
researchforge kaggle keys waitWait until a key is set (and, once tested, passed). Exit 1 on timeout.
- <name>
- One of: kaggle, anthropic, gemini, openai, claude, cursor, colab, runpod, lambda, vast, aws
- --timeout
- Give up after N seconds
researchforge kaggle merge-historyFold the repo project beside this competition into its one history.
- <competition>
- Kaggle competition slug or URL
researchforge kaggle monitorUnified background monitor — replaces 'watch'. Runs all checks in one cycle.
- <competition>
- Kaggle competition slug or URL
- --poll-hours
- How often to run all checks (hours) [default: 6]
- --arxiv-hours
- How often to run arXiv scan (hours, 0=off) [default: 24]
- --briefing-at
- Send morning briefing at HH:MM local time ('' = off)
- --heartbeat-stale
- Alert if execute_round.lock older than N hours [default: 2]
- --once
- Run one cycle and exit (for testing)
- --submission-minutes
- Check Kaggle submissions this often between cycles (minutes, 0 = only with each cycle) [default: 15]
- --kernel-minutes
- Check public notebooks this often between cycles (minutes, 0 = only with each cycle) [default: 60]
researchforge kaggle offer-submissionAsk the person whether to submit one round; their "yes" submits it.
- <competition>
- Kaggle competition slug or URL
- <round_num>
- The round to offer, e.g. 21
- --note
- What the person should know, e.g. its LB claim
researchforge kaggle overnightImprove your Kaggle score overnight. Just provide the competition URL.
- <competition>
- Kaggle competition URL or slug
- --gpu
- Where experiments run: local (this machine, using its GPU if it has one), kaggle (free GPU quota), colab, ssh (after ssh-setup), cloud (after cloud-gpu-setup) or competition. Without it, setup asks.
- --time-hours
- Time budget in hours
- --max-experiments
- Max experiments to run
- --watch-interval-hours
- Run the background monitor (all enabled sensors: new public notebooks, submissions, hypothesis pool, ...) every N hours until this machine restarts. For a persistent service use `researchforge kaggle scheduler-install`. Default: off.
- --refresh
- Start setup over: re-gather competition facts and re-run the baseline. Without it, an already set-up project resumes where it left off.
- --answers-json
- Pre-supply domain knowledge and other HIL answers as JSON. Accepts inline JSON or a file path. Example: '{"known_approaches": "LGB + target encoding", "external_data": "no"}'
researchforge kaggle pauseStop starting new rounds. A round already running finishes; sensors keep running.
- <competition>
- Kaggle competition slug or URL
- --reason
- Why (shown on the dashboard)
researchforge kaggle prepare-roundPrint proposal context for the next round as JSON (Claude Code path — no API key needed).
- <competition>
- Kaggle competition slug or URL
researchforge kaggle propose-from-kernelWrite proposal.json from a public notebook, so it runs as a round on the chosen compute.
- <competition>
- Kaggle competition slug or URL
- <ref>
- Public notebook, owner/notebook-slug
- --title
- The round's title
- --description
- --rationale
- --expected-impact
- --hypothesis
- The exact pool idea this round tests
- --parent
- Parent round, e.g. 3 or R3
- --branch
- Branch tag
- --append
- A .py file appended after the notebook (scoring code)
- --dataset
- Another dataset to attach, owner/slug (repeatable)
researchforge kaggle propose-hypothesisAdd one or more AI-proposed hypotheses directly to the experiment pool.
- <competition>
- Kaggle competition slug or URL
- --idea
- Hypothesis idea text. Can be a single string or inline JSON array of ideas.
- --rationale
- Why this idea might improve the score.
- --source
- Credit for the idea: 'claude_observation', 'arxiv:<id>', 'kernel:<ref>', etc.
- --priority
- Priority 1-10 (1=highest). Default 5.
- --bulk
- JSON array of hypothesis objects: [{"idea": "...", "rationale": "...", "source": "...", "priority": 5}, ...] or a file path to a JSON file.
researchforge kaggle pull-kernelDownload a public notebook into reference_kernels/<name>/ to read or port from.
- <competition>
- Kaggle competition slug or URL
- <ref>
- Public notebook, owner/notebook-slug
- --outputs
- Also download the notebook's output files
- --datasets
- Also download the datasets it attaches (if the data policy allows)
researchforge kaggle respondAnswer a question the loop asked. With no id, lists the open questions.
- <competition>
- Kaggle competition slug or URL
- <interaction_id>
- Question id from `kaggle status`
- <answer>
- Your answer
- --dismiss
- Close it without answering; its ideas run again
- --comment
- Your own words with it; the next proposal reads them
researchforge kaggle resumeStart new rounds again after a pause.
- <competition>
- Kaggle competition slug or URL
researchforge kaggle resynthesizeRe-synthesize the research landscape from experiment results.
- <competition>
- Kaggle competition slug or URL
researchforge kaggle runRun experiments with an AI API key (after setup).
- <competition>
- Kaggle competition slug or URL
- --rounds
- Stop after this many rounds (default: setup's maximum)
researchforge kaggle run-parallelRun multiple proposals in parallel across available compute targets.
- <competition>
- Kaggle competition slug or URL
- --proposals
- Comma-separated proposal file paths, or 'auto' to find all proposal_*.json in the artifacts dir
- --max-workers
- Max parallel experiment threads [default: number of proposals]
researchforge kaggle scheduler-installInstall a background service so the monitor runs on a schedule without Claude Code.
- <competition>
- Kaggle competition slug or URL
- --interval-hours
- How often to poll (hours). Default: uses saved scheduler config or 6h.
- --uninstall
- Remove the service instead of installing it.
researchforge kaggle scheduler-setupConfigure the overnight scheduler: watcher interval, start time, morning briefing.
- <competition>
- Kaggle competition slug or URL
- --watcher-hours
- How often to check for new public notebooks (0=off)
- --start-at
- Start experiments at this time today (HH:MM local), e.g. 23:00
- --briefing-at
- Send morning briefing at this time (HH:MM local), e.g. 07:00
- --briefing-on-completion
- Send ntfy notification immediately when experiments finish
- --only-if-improved
- Skip briefing if nothing improved
researchforge kaggle scheduler-uninstallRemove the launchd watcher service for a competition.
- <competition>
- Kaggle competition slug or URL
researchforge kaggle sensorsList or configure the monitor's sensors (persisted in scheduler_config.json).
- <competition>
- Kaggle competition slug or URL
- --enable
- Sensor name to enable (repeatable)
- --disable
- Sensor name to disable (repeatable)
- --add
- Name of a custom sensor to add
- --command
- Shell command for --add; exit 0 = healthy
- --timeout
- Timeout (s) for a custom sensor command
- --remove
- Name of a custom sensor to remove
- --json
- Print sensor config + state as JSON
researchforge kaggle settingsShow or change notification level, submission policy, the Kaggle GPU cap, the phone-alert topic and which way the metric improves.
- <competition>
- Kaggle competition slug or URL
- --notify-level
- verbose = every result · balanced · minimal = candidates only
- --submission-policy
- aggressive = any improved round · balanced = an improved round that left a notebook or file to submit · conservative = only when asked
- --kaggle-gpu-daily-cap
- Max Kaggle GPU experiments per day (0 = no cap)
- --metric-direction
- maximize (higher is better) or minimize (lower is better), if setup got it wrong
- --ntfy-topic
- This competition's ntfy topic for phone alerts ('' = use the machine-wide one)
researchforge kaggle setupSetup phase only (for debugging).
- <competition>
- Kaggle competition slug or URL
researchforge kaggle skip-ideaTake an idea out of the pool's ranking (it stays listed as skipped, with the reason).
- <competition>
- Kaggle competition slug or URL
- <idea>
- The pool idea, as prepare-round shows it
- --reason
- Why it cannot run
researchforge kaggle ssh-setupConfigure a remote SSH server as a compute target for overnight experiments.
- <competition>
- Kaggle competition slug or URL
- --host
- SSH target: user@hostname or hostname
- --key
- Path to SSH private key (default: ~/.ssh/id_rsa)
- --remote-dir
- Base directory on remote server for experiments
- --python
- Python executable on remote server
- --rsync-data
- Copy competition data to remote server before each experiment
- --test
- Test SSH connectivity after saving config
researchforge kaggle statusWhere the loop is: paused?, running round, best result, pool, open questions.
- <competition>
- Kaggle competition slug or URL
- --json
- Machine-readable output
researchforge kaggle steerSteer the research: add a direction, answer one, remove one — or list them.
- <competition>
- Kaggle competition slug or URL
- <text>
- The direction, or the reply with --reply
- --standing
- Keep it for every round until removed
- --reply
- Answer this direction id (the proposer does this)
- --remove
- Remove this direction id
- --json
- Print JSON
researchforge kaggle watchWatch for new public kernels and inject their ideas into the experiment pool.
- <competition>
- Kaggle competition slug or URL
- --interval-hours
- How often to check for new kernels
- --once
- Run one cycle and exit
- --dry-run
- Report what would be injected but don't persist
researchforge all
researchforge all installInstall both Claude Code skills and Cursor rules.
- --force
- Overwrite files modified after install.
- --user
- Install into ~/.claude/skills/ and ~/.cursor/rules/ (machine-wide).
- --json
- Emit machine-readable JSON output.
researchforge all statusShow install status for both Claude Code skills and Cursor rules.
- --user
- Check ~/.claude/skills/ and ~/.cursor/rules/ (machine-wide).
- --json
- Emit machine-readable JSON output.
researchforge all uninstallUninstall both Claude Code skills and Cursor rules.
- --force
- Remove files modified after install.
- --user
- Uninstall from ~/.claude/skills/ and ~/.cursor/rules/ (machine-wide).
- --json
- Emit machine-readable JSON output.
researchforge analytics
researchforge analytics disableDisable local analytics (the existing log is kept; delete it if you wish).
- --json
- Emit machine-readable JSON output.
researchforge analytics enableEnable local analytics (prints exactly what is and is not collected).
- --json
- Emit machine-readable JSON output.
researchforge analytics showCompute the beta metrics locally from the recorded events.
- --json
- Emit machine-readable JSON output.
researchforge analytics statusShow whether analytics are enabled and how many events are recorded.
- --json
- Emit machine-readable JSON output.
researchforge audit
researchforge audit exportWrite the full history to a JSON file.
- <output>
- Destination, e.g. audit.json
- --json
- Emit machine-readable JSON output.
researchforge audit logShow the project's history, oldest first.
- --last
- Show only the most recent N entries.
- --kind
- Show only one kind of entry.
- --json
- Emit machine-readable JSON output.
researchforge auto-run
researchforge auto-run approvalAsk before every plan, or give the loop your standing approval (typed).
- <mode>
- ask (each plan waits for you) or standing
- --path
- Project folder (default: the project around the current dir).
researchforge auto-run monitorRun the monitor: a cycle every poll_minutes (the service runs one per interval).
- --path
- Project folder (default: the project around the current dir).
- --once
- One cycle, then exit.
researchforge auto-run pausePause: a running launch finishes, no new one starts.
- --path
- Project folder (default: the project around the current dir).
- --reason
researchforge auto-run resumeResume after a pause.
- --path
- Project folder (default: the project around the current dir).
researchforge auto-run serviceInstall (or remove) the background service: launchd, systemd timer or Task Scheduler.
- --path
- Project folder (default: the project around the current dir).
- --uninstall
- Remove the service.
researchforge auto-run settingsChange auto-run settings. Approval has its own command.
- --path
- Project folder (default: the project around the current dir).
- --on
- Turn auto-run on or off.
- --driver
- claude, cursor or byok
- --model
- --rounds-per-launch
- --daily-max
- --max-minutes
- --merge
- --metric-gate
- Off: record every result.
- --ntfy-topic
- --poll-minutes
- --papers-hours
- --briefing-at
researchforge auto-run startStart one launch now, through the same gates as the monitor.
- --path
- Project folder (default: the project around the current dir).
researchforge auto-run statusSettings, gates, the running or last launch, plans waiting and the service.
- --path
- Project folder (default: the project around the current dir).
- --json
- Emit machine-readable JSON output.
researchforge auto-run stopStop the running launch. Experiments it finished are kept.
- --path
- Project folder (default: the project around the current dir).
researchforge baseline
researchforge baseline resetDrop the frozen baseline so the next `baseline run` measures a new one.
- --confirm
- Required: confirms the frozen baseline should be dropped.
- --force
- Also drop it when experiments have already been measured against it.
- --json
- Emit machine-readable JSON output.
researchforge baseline runRun the baseline in an isolated worktree and store the result.
- --check
- Resolve the environment and stop (no execution).
- --auto-recover
- Automatically attempt setup-command fixes when the baseline fails due to a setup error (default: on).
- --n-runs
- Measure the baseline this many times and freeze the mean. Use it when the benchmark is noisy, so improvements are compared against an average rather than one lucky run.
- --json
- Emit machine-readable JSON output.
researchforge baseline showShow the latest baseline run.
- --json
- Emit machine-readable JSON output.
researchforge baseline statusShow the latest baseline run (alias for `baseline show`).
- --json
- Emit machine-readable JSON output.
researchforge claude
researchforge claude installInstall the ResearchForge skills into this repository's .claude/skills/.
- --force
- Overwrite/remove skills even if they were modified after installation.
- --user
- Target ~/.claude/skills/ (every project on this machine) instead of this repository.
- --json
- Emit machine-readable JSON output.
researchforge claude statusShow whether each packaged skill is installed, modified, or missing.
- --user
- Target ~/.claude/skills/ (every project on this machine) instead of this repository.
- --json
- Emit machine-readable JSON output.
researchforge claude uninstallRemove the installed ResearchForge skills (user-modified files are kept).
- --force
- Overwrite/remove skills even if they were modified after installation.
- --user
- Target ~/.claude/skills/ (every project on this machine) instead of this repository.
- --json
- Emit machine-readable JSON output.
researchforge contract
researchforge contract approveApprove the contract, freezing it as the next immutable version.
- --yes
- Skip the interactive confirmation.
- --file
- --json
- Emit machine-readable JSON output.
researchforge contract generateGenerate a researchforge.yaml draft from the project and repository scan.
- --force
- Overwrite an existing file.
- --target
- Optional metric value that satisfies the objective — `autorun` stops there.
- --json
- Emit machine-readable JSON output.
researchforge contract showShow the active approved contract.
- --json
- Emit machine-readable JSON output.
researchforge contract validateValidate a researchforge.yaml (safe to run repeatedly; no side effects).
- --file
- Contract file to validate.
- --json
- Emit machine-readable JSON output.
researchforge cursor
researchforge cursor installInstall the ResearchForge rules into this repository's .cursor/rules/.
- --force
- Overwrite/remove rules even if they were modified after installation.
- --user
- Target ~/.cursor/rules/ (every project on this machine) instead of this repository.
- --json
- Emit machine-readable JSON output.
researchforge cursor statusShow whether each packaged rule is installed, modified, or missing.
- --user
- Target ~/.cursor/rules/ (every project on this machine) instead of this repository.
- --json
- Emit machine-readable JSON output.
researchforge cursor uninstallRemove the installed ResearchForge rules (user-modified files are kept).
- --force
- Overwrite/remove rules even if they were modified after installation.
- --user
- Target ~/.cursor/rules/ (every project on this machine) instead of this repository.
- --json
- Emit machine-readable JSON output.
researchforge experiment
researchforge experiment abandonDiscard an interrupted run so a new plan can start clean.
- <run_id>
- e.g. run-001
- --yes
- Skip the interactive confirmation.
- --json
- Emit machine-readable JSON output.
researchforge experiment approveApprove a plan's runnable experiments for execution (spec §4.6).
- <plan_id>
- e.g. plan-001
- --yes
- Skip the interactive confirmation.
- --json
- Emit machine-readable JSON output.
researchforge experiment cancelCancel a planned/approved plan (its experiments become cancelled).
- <plan_id>
- e.g. plan-001
- --yes
- --json
- Emit machine-readable JSON output.
researchforge experiment importValidate and import an experiment plan and its patches.
- <file>
- Experiment plan artifact (plan.yaml).
- --json
- Emit machine-readable JSON output.
researchforge experiment judgeDecide whether an experiment is worth Kaggle GPU validation (autorun --judgment).
- <experiment_id>
- Experiment ID, e.g. exp-003
- <decision>
- yes | no | skip
researchforge experiment listList plans and their experiments.
- --json
- Emit machine-readable JSON output.
researchforge experiment planExport the experiment-planning context for a hypothesis.
- <hypothesis_id>
- e.g. hyp-001. Omit with --all to plan every pending hypothesis.
- --all
- Plan ALL pending hypotheses (those without a plan yet).
- --synthesize
- Use a built-in AI provider to generate plan.yaml + patches automatically.
- --provider, -p
- AI provider: anthropic|google|openai. Auto-detected from env when omitted.
- --model, -m
- Override model name.
- --parent
- Build on a measured experiment (e.g. exp-008) instead of the baseline.
- --merge
- Combine two measured experiments, e.g. exp-001,exp-003. Composes their patches without AI; asks the AI only if they edit the same lines.
- --json
- Emit machine-readable JSON output.
researchforge experiment resumeResume an interrupted run: stale stages are marked failed and retried.
- <run_id>
- e.g. run-001
- --monitor
- Start (or skip) the background live monitor for this run (default: auto on a TTY).
- --json
- Emit machine-readable JSON output.
researchforge experiment runRun the approved experiments: screening then full benchmark, one at a time.
- <plan_id>
- e.g. plan-001
- --stall
- Stop after N consecutive non-improvements. Overrides the contract setting.
- --monitor
- Start (or skip) the background live monitor for this run (default: auto on a TTY).
- --json
- Emit machine-readable JSON output.
researchforge experiment showShow one experiment in full.
- <experiment_id>
- e.g. exp-001
- --json
- Emit machine-readable JSON output.
researchforge experiment startImport, approve, and run a plan in one command (one typed approval).
- <file>
- Experiment plan artifact (plan.yaml).
- --yes
- Skip the interactive confirmation.
- --stall
- Stop after N consecutive non-improvements.
- --monitor
- Start (or skip) the background live monitor for this run (default: auto on a TTY).
- --json
- Emit machine-readable JSON output.
researchforge experiment submission-candidatesShow ranked experiment candidates for Kaggle submission.
- --json
- Emit machine-readable JSON output.
researchforge experiment submitSubmit an approved experiment to Kaggle. NEVER runs automatically.
- <experiment_id>
- Experiment ID to submit, e.g. exp-003
- --message, -m
- Submission message for Kaggle
- --dry-run
- Show what would be submitted without actually submitting
- --json
- Emit machine-readable JSON output.
researchforge generate
researchforge generate dockerfileGenerate a Dockerfile for this project.
- --provider, -p
- AI provider: anthropic|google|openai. Omit to use a minimal heuristic template.
- --model, -m
- Override model name.
- --cuda
- Use an NVIDIA CUDA base image (GPU workloads).
- --force
- Overwrite an existing Dockerfile.
- --output-dir
- Write Dockerfile here (default: project root).
- --json
- Emit machine-readable JSON output.
researchforge generate eval-scriptGenerate benchmarks/evaluate.py and src/config.py using a built-in AI provider.
- --provider, -p
- AI provider: anthropic|google|openai. Auto-detected from env when omitted.
- --model, -m
- Override model name.
- --existing
- Point to an eval script you already have. ResearchForge will copy it to benchmarks/evaluate.py (or use it in place) instead of generating one. Example: --existing scripts/run_eval.py
- --output-dir
- Write files here instead of the cwd. Defaults to the project root.
- --force
- Overwrite existing files.
- --json
- Emit machine-readable JSON output.
researchforge generate policyGenerate .researchforge/policy.yaml from your compliance documents.
- --from-docs
- Path to a compliance document (PDF, Markdown, text) or a folder containing multiple compliance documents. ResearchForge reads them and uses AI to extract rules and write policy.yaml.
- --existing
- Point to an existing policy.yaml to import and validate. ResearchForge copies it to .researchforge/policy.yaml.
- --provider, -p
- AI provider: anthropic|google|openai. Auto-detected from env when omitted.
- --model, -m
- Override model name.
- --force
- Overwrite existing policy.yaml.
- --json
- Emit machine-readable JSON output.
researchforge hypotheses
researchforge hypotheses approveApprove hypotheses for planning, without the interactive review.
- <hypothesis_ids>
- One or more ids, e.g. hyp-001 hyp-003
- --reason
- Optional note recorded with the approval.
- --json
- Emit machine-readable JSON output.
researchforge hypotheses generateGenerate landscape + hypotheses from stored papers using a built-in AI provider.
- --provider, -p
- AI provider: anthropic|google|openai. Auto-detected from env when omitted.
- --model, -m
- Override model name.
- --no-import
- Write YAML files but do not import them.
- --json
- Emit machine-readable JSON output.
researchforge hypotheses importValidate and import a hypotheses artifact.
- <file>
- Hypotheses artifact (YAML or JSON).
- --json
- Emit machine-readable JSON output.
researchforge hypotheses listList stored hypotheses.
- --json
- Emit machine-readable JSON output.
researchforge hypotheses rejectReject a hypothesis, so planning and autorun skip it.
- <hypothesis_id>
- e.g. hyp-002
- --reason
- Why this hypothesis is not worth testing.
- --json
- Emit machine-readable JSON output.
researchforge hypotheses reviewWalk the unreviewed hypotheses one at a time, approving or rejecting each.
- --json
- Emit machine-readable JSON output.
researchforge hypotheses showShow one hypothesis in full.
- <hypothesis_id>
- e.g. hyp-001
- --json
- Emit machine-readable JSON output.
researchforge notify
researchforge notify setupPersist ntfy settings so notifications work in every process, including Claude Code.
- --topic, -t
- Your ntfy.sh topic: a name nobody can guess
- --server
- ntfy server URL (default: https://ntfy.sh)
- --test
- Send a test notification after saving
researchforge notify statusShow current notification configuration.
researchforge notify testSend a test notification using the currently configured topic.
researchforge paper
researchforge paper packageGenerate the research package: report, related work, BibTeX, outline, data.
- --output
- Package directory (default: .researchforge/research-output; pass a path to write elsewhere, e.g. ./research-output).
- --json
- Emit machine-readable JSON output.
researchforge papers
researchforge papers exportWrite every stored paper to a JSON file.
- <output>
- Destination, e.g. papers.json
- --json
- Emit machine-readable JSON output.
researchforge papers importImport papers from an exported JSON file.
- <file>
- A file written by `papers export`.
- --json
- Emit machine-readable JSON output.
researchforge papers listList stored papers ordered by relevance.
- --limit
- --json
- Emit machine-readable JSON output.
researchforge papers showShow one stored paper in full.
- <paper_id>
- e.g. arxiv:2401.12345
- --json
- Emit machine-readable JSON output.
researchforge project
researchforge project createCreate (or resume) the ResearchForge project in the current directory.
- --mode
- improve_repository or explore_research_idea
- --objective
- What should improve or be investigated.
- --name
- --repo-path
- --force-update
- Overwrite an existing definition.
- --json
- Emit machine-readable JSON output.
researchforge project showShow the current project definition.
- --json
- Emit machine-readable JSON output.
researchforge repo
researchforge repo scanScan a repository and record its compatibility.
- <path>
- Repository to scan (defaults to the project repo path or cwd).
- --json
- Emit machine-readable JSON output.
researchforge report
researchforge report buildBuild the report: engineering when experiment data exists, else research-only.
- --output
- Write the report to this path.
- --json
- Emit machine-readable JSON output.
researchforge research
researchforge research contextExport the synthesis context bundle for Claude to read.
- --output
- Write the bundle here instead of the default path.
- --json
- Emit machine-readable JSON output.
researchforge research landscapeShow the stored research landscape, or import one with --import.
- --import, -i
- Validate and import a landscape artifact.
- --json
- Emit machine-readable JSON output.
researchforge research searchDiscover, deduplicate, rank, and store relevant arXiv papers.
- --query, -q
- Search query (repeatable). Omit to auto-generate.
- --max-candidates
- --select, --n, -n
- --categories, -c
- arXiv category filter (repeatable). E.g. cs.CV cs.LG
- --min-score
- Minimum relevance score (0–1).
- --since
- Only papers submitted on or after this date, e.g. 2024-01-01.
- --force
- Replace papers already cited by hypotheses.
- --provider, -p
- AI provider for query generation: anthropic|google|openai. Auto-detected from env when omitted.
- --json
- Emit machine-readable JSON output.
researchforge research synthesizeGenerate landscape and hypotheses using a built-in AI provider.
- --provider, -p
- AI provider: anthropic|google|openai. Auto-detected from env when omitted.
- --model, -m
- Override model name (e.g. claude-opus-4-5, gemini-3.6-flash, gpt-4o).
- --no-import
- Write YAML files but skip importing them.
- --from-results
- Ground the synthesis in what this project has already measured. New hypotheses are ADDED to the stored set, and candidates that restate one already on record are skipped.
- --run
- With --from-results, use one run's outcomes instead of all of them.
- --json
- Emit machine-readable JSON output.
researchforge results
researchforge results showShow the ranked results of a run, trade-offs, and rejected history.
- <run_id>
- e.g. run-001
- --json
- Emit machine-readable JSON output.
researchforge ship
researchforge ship branchReconstruct the validated change as a clean local branch (never pushed).
- <experiment_id>
- Experiment to ship (defaults to the unique validated one).
- --branch
- Override the derived branch name.
- --yes
- Skip the confirmation prompt.
- --json
- Emit machine-readable JSON output.
researchforge ship prPush the shipped change and open a DRAFT pull request (opt-in twice).
- <experiment_id>
- Shipped experiment (defaults to the latest shipped branch).
- --base
- PR base branch.
- --remote
- Push to this git remote instead of asking.
- --repo-url
- Push to this GitHub URL instead of asking.
- --as-measured
- Push the shipped commit on the frozen baseline instead of replaying the change onto the base branch.
- --yes
- Skip the push confirmation.
- --json
- Emit machine-readable JSON output.
Regenerate after a release with python scripts/gen_cli_reference.py using the researchforge environment.