Docs · CLI reference

ResearchForge CLI reference: every command and flag

All 133 commands in ResearchForge 0.4.0, generated from the CLI itself. Every command also has --help, and most take --json.

researchforge

researchforge autorun

Run 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 dashboard

Open 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 doctor

Check that required and optional dependencies are available.

--json
Emit machine-readable JSON output.
researchforge hub

Run 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 init

Initialize 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 paths

Show every location ResearchForge uses in this project.

--json
Emit machine-readable JSON output.
researchforge run

Run 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 serve

Run 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 status

Show the status of the current ResearchForge project.

--json
Emit machine-readable JSON output.
researchforge validate

Repeatedly 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-hypothesis

Inject 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 archive

Archive 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-scan

Scan 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 ask

Ask 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-run

Run 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-key

Store 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-setup

Configure 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-setup

Set 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 compute

Switch compute for the next rounds.

<competition>
Kaggle competition slug or URL
<target>
One of: local, kaggle, colab, ssh, cloud, competition
researchforge kaggle dashboard

Open 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-round

Delete 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 draft

A 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 driver

Show 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-login

Sign 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-round

Execute the proposal at .overnight_<slug>/proposal.json. Prints result JSON.

<competition>
Kaggle competition slug or URL
researchforge kaggle finish

Generate the morning report and send push notification. Call when all rounds are done.

<competition>
Kaggle competition slug or URL
researchforge kaggle gather-facts

Gather 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 ideation

Research-only mode: read competition, kernels, papers → prioritised plan.

<competition>
Kaggle competition slug or URL
researchforge kaggle keys open

Open 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 remove

Remove 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 set

Set 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 status

Which 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 test

Make 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 wait

Wait 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-history

Fold the repo project beside this competition into its one history.

<competition>
Kaggle competition slug or URL
researchforge kaggle monitor

Unified 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-submission

Ask 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 overnight

Improve 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 pause

Stop 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-round

Print 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-kernel

Write 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-hypothesis

Add 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-kernel

Download 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 respond

Answer 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 resume

Start new rounds again after a pause.

<competition>
Kaggle competition slug or URL
researchforge kaggle resynthesize

Re-synthesize the research landscape from experiment results.

<competition>
Kaggle competition slug or URL
researchforge kaggle run

Run 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-parallel

Run 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-install

Install 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-setup

Configure 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-uninstall

Remove the launchd watcher service for a competition.

<competition>
Kaggle competition slug or URL
researchforge kaggle sensors

List 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 settings

Show 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 setup

Setup phase only (for debugging).

<competition>
Kaggle competition slug or URL
researchforge kaggle skip-idea

Take 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-setup

Configure 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 status

Where the loop is: paused?, running round, best result, pool, open questions.

<competition>
Kaggle competition slug or URL
--json
Machine-readable output
researchforge kaggle steer

Steer 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 watch

Watch 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 install

Install 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 status

Show 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 uninstall

Uninstall 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 disable

Disable local analytics (the existing log is kept; delete it if you wish).

--json
Emit machine-readable JSON output.
researchforge analytics enable

Enable local analytics (prints exactly what is and is not collected).

--json
Emit machine-readable JSON output.
researchforge analytics show

Compute the beta metrics locally from the recorded events.

--json
Emit machine-readable JSON output.
researchforge analytics status

Show whether analytics are enabled and how many events are recorded.

--json
Emit machine-readable JSON output.

researchforge audit

researchforge audit export

Write the full history to a JSON file.

<output>
Destination, e.g. audit.json
--json
Emit machine-readable JSON output.
researchforge audit log

Show 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 approval

Ask 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 monitor

Run 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 pause

Pause: a running launch finishes, no new one starts.

--path
Project folder (default: the project around the current dir).
--reason
researchforge auto-run resume

Resume after a pause.

--path
Project folder (default: the project around the current dir).
researchforge auto-run service

Install (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 settings

Change 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 start

Start one launch now, through the same gates as the monitor.

--path
Project folder (default: the project around the current dir).
researchforge auto-run status

Settings, 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 stop

Stop the running launch. Experiments it finished are kept.

--path
Project folder (default: the project around the current dir).

researchforge baseline

researchforge baseline reset

Drop 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 run

Run 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 show

Show the latest baseline run.

--json
Emit machine-readable JSON output.
researchforge baseline status

Show the latest baseline run (alias for `baseline show`).

--json
Emit machine-readable JSON output.

researchforge claude

researchforge claude install

Install 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 status

Show 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 uninstall

Remove 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 approve

Approve the contract, freezing it as the next immutable version.

--yes
Skip the interactive confirmation.
--file
--json
Emit machine-readable JSON output.
researchforge contract generate

Generate 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 show

Show the active approved contract.

--json
Emit machine-readable JSON output.
researchforge contract validate

Validate 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 install

Install 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 status

Show 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 uninstall

Remove 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 abandon

Discard 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 approve

Approve 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 cancel

Cancel a planned/approved plan (its experiments become cancelled).

<plan_id>
e.g. plan-001
--yes
--json
Emit machine-readable JSON output.
researchforge experiment import

Validate and import an experiment plan and its patches.

<file>
Experiment plan artifact (plan.yaml).
--json
Emit machine-readable JSON output.
researchforge experiment judge

Decide whether an experiment is worth Kaggle GPU validation (autorun --judgment).

<experiment_id>
Experiment ID, e.g. exp-003
<decision>
yes | no | skip
researchforge experiment list

List plans and their experiments.

--json
Emit machine-readable JSON output.
researchforge experiment plan

Export 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 resume

Resume 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 run

Run 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 show

Show one experiment in full.

<experiment_id>
e.g. exp-001
--json
Emit machine-readable JSON output.
researchforge experiment start

Import, 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-candidates

Show ranked experiment candidates for Kaggle submission.

--json
Emit machine-readable JSON output.
researchforge experiment submit

Submit 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 dockerfile

Generate 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-script

Generate 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 policy

Generate .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 approve

Approve 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 generate

Generate 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 import

Validate and import a hypotheses artifact.

<file>
Hypotheses artifact (YAML or JSON).
--json
Emit machine-readable JSON output.
researchforge hypotheses list

List stored hypotheses.

--json
Emit machine-readable JSON output.
researchforge hypotheses reject

Reject 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 review

Walk the unreviewed hypotheses one at a time, approving or rejecting each.

--json
Emit machine-readable JSON output.
researchforge hypotheses show

Show one hypothesis in full.

<hypothesis_id>
e.g. hyp-001
--json
Emit machine-readable JSON output.

researchforge notify

researchforge notify setup

Persist 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 status

Show current notification configuration.

researchforge notify test

Send a test notification using the currently configured topic.

researchforge paper

researchforge paper package

Generate 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 export

Write every stored paper to a JSON file.

<output>
Destination, e.g. papers.json
--json
Emit machine-readable JSON output.
researchforge papers import

Import papers from an exported JSON file.

<file>
A file written by `papers export`.
--json
Emit machine-readable JSON output.
researchforge papers list

List stored papers ordered by relevance.

--limit
--json
Emit machine-readable JSON output.
researchforge papers show

Show one stored paper in full.

<paper_id>
e.g. arxiv:2401.12345
--json
Emit machine-readable JSON output.

researchforge project

researchforge project create

Create (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 show

Show the current project definition.

--json
Emit machine-readable JSON output.

researchforge repo

researchforge repo scan

Scan 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 build

Build 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 context

Export 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 landscape

Show 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 synthesize

Generate 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 show

Show 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 branch

Reconstruct 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 pr

Push 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.