@finetuner/cli

The finetuner.dev command-line tool (ft): turn one product idea into a fine-tuning dataset and a training runbook. The CLI interviews you, gates a source-of-truth document pack you sign off on, generates and judges every row, audits the corpus, and exports splits + a dataset card + a runbook.

idea ─▶ intake ─▶ interview ─▶ research ─▶ SOT docs ─▶ generation ─▶ audit ─▶ export ─▶ runbook
                                      doc-pack sign-off gate

Install

curl -fsSL https://finetuner.dev/install.sh | bash   # provides the `ft` command

Requires Node ≥ 20. The installer downloads one self-contained file to ~/.finetuner and drops ft (and a finetuner alias) in ~/.local/bin — no npm, no node_modules. When it finishes it prints the command to start: ft.

Prefer npm? npm i -g @finetuner/cli still works.

The bundle is signed and served by the API at /api/launcher (streamed from private storage — the same artifact npm ships). ft keeps itself current: a below-minimum launcher self-updates and re-runs your command automatically; a newer-but-compatible one prints a one-line nudge. Force it anytime with ft update. npm installs update via npm i -g.

Quick start

ft login                          # sign in (stores a session)
ft                                # opens the idea screen — type what you're building, ↵ to start

Running ft with nothing else opens the idea screen: type a sentence describing the assistant, press Enter, and the pipeline takes over (the project folder is named from the idea). Prefer to name it yourself? Pass it inline:

ft new "support bot" --idea "A support assistant for Acme Outfitters: refunds, shipping, billing…"

ft new runs the whole pipeline behind the terminal UI: interviews you, proposes a volume, drafts gold examples and a plan you confirm, writes the document pack for sign-off, then generates → audits → exports. A local viewer (dashboard + dataset browser) serves the project for the session.

Commands

Run ft <command> --help for the full flag list. ft with no command resumes the project in the current folder, or — outside a project — opens the idea screen to start a new one.

Pipeline

| Command | What it does | |---|---| | ft new [name] | Create ./<slug>/, capture the idea, and run the full pipeline. | | ft resume | Continue from wherever the project last stopped. | | ft generate | Run up through batched generation, then stop. | | ft audit | Run the full-corpus audit (multi-lens findings → verifier → freeze). | | ft export | Export train/val/test splits, the dataset card and the manifest. | | ft runbook | Write the fine-tuning runbook for the confirmed target model. | | ft fix <ref> | Repair one bad row, ban the failure, sweep look-alikes. |

<ref> is a row id or a memorable phrase from the row's text.

Inspect

| Command | What it does | |---|---| | ft status | Phase, rows accepted/target, spend vs cap, target model, next step. | | ft view | Open the project viewer (dashboard + dataset browser) in a browser. | | ft models | Pipeline seat registry + the open-weights target-model knowledge pack. | | ft config | Print the resolved project configuration. | | ft demo | Offline scripted replay of the whole UI — no API, no keys. |

Account

| Command | What it does | |---|---| | ft login | Sign in; stores the session. | | ft signup | Create an account and sign in. | | ft whoami | Show the signed-in account, or that you're logged out. | | ft logout | Clear the stored session. |

Key flags

| Flag | Commands | Meaning | |---|---|---| | -i, --idea <text> | new | One paragraph describing the assistant. | | -f, --file <path> | new | Grounding document to ingest at intake (repeatable). | | -d, --dir <path> | most | Project directory (default: ./<slug> for new, . otherwise). | | --rows <n> | new | Dataset row target (default 400). | | --budget <usd> | new | Hard spend cap in USD (default 25). | | --orchestrator/--executor/--judge <model> | new | Pick a pipeline seat: a registry id or <model>@<baseUrl>. | | --mock | new | Offline dry run on mock generation seats ($0, no provider keys). | | -y, --yes | pipeline | Unattended: questions take defaults, every gate auto-approves. | | --headless | pipeline | Line output instead of the TUI (automatic when not a TTY). | | --batches <n> | new/resume/generate | Stop generation after N batches. | | -r, --reason <text> | fix | What's wrong with the row. | | --port <n> / --no-open | view | Viewer port / don't open a browser. |

Gates

Interactive runs pause at gates so you confirm before any spend escalates:

1. Grounding risk — knowledge-heavy task with no source docs: accept the invented-fact risk or stop and upload sources.
2. Gold examples — approve, edit, or decline the drafted example rows.
3. Plan — confirm plan.md (the contract every SOT doc serves) or request edits.
4. Sample rows — "your data will look like this — correct?"
5. Doc-pack sign-off — the last gate before any executor spend: accept, stop, revise one doc, or rescan after manual edits.

During generation, gate A (schema/shape) and gate B (the judge) police every row. --yes takes the default at every gate (accept) — what non-interactive and agent-driven runs use.

Driving from an AI agent

The full unattended (--yes --headless) playbook ships with the CLI as AGENTS.md — the cross-agent standard read by Codex, Cursor, opencode, Antigravity, Gemini CLI, Aider, Zed and others. Claude Code also gets it via CLAUDE.md and an on-demand skill.

Project files

A project directory is the single source of truth — everything is event-sourced and resumable:

| Path | What it holds | |---|---| | finetuner.json | Project config: seats, row target, budget, target model. | | idea.md | The original idea (resume anchor for the pre-SOT phases). | | events.jsonl | The full event spine of the run. | | ledger.jsonl | Every model call's token counts (cost derived at read time). | | plan.md, sot/*.md | The confirmed plan and the source-of-truth doc pack. | | corpus/corpus.jsonl | Generated rows (ids + text — what ft fix <ref> matches). | | deliverables/ | Splits, manifest.json, dataset card, RUNBOOK.md. | | audits/ | Corpus-audit findings and probe coverage. |

Configuration

export FT_API_URL=https://api.finetuner.dev   # override the API base URL

The session is stored at ~/.config/finetuner/session.json (override the dir with FT_CONFIG_DIR / XDG_CONFIG_HOME). Provider API keys for the generation seats (executor/judge) resolve at runtime from your environment/keychain and never touch project files or config.