Skip to main content
The finetune CLI shares the studio workspace without requiring a terminal or MCP server. Schema discovery does not import training libraries or allocate compute.
Use the reviewed checkout and Python environment described in the quickstart. Credentials belong in the environment, not configuration JSON. Workspaces use OS permissions and should remain private.

​
Parse reports and outcomes separately

Successful commands write one JSON object to stdout:
Command failures use ok: false, controlled error.code/error.message, and exit 1. CLI usage errors use help output and exit 2; diagnostics go to stderr. Check the exit code and ok, then inspect the operation’s business result:
  • validate: result.valid can be false while the report succeeded.
  • readiness: inspect failed checks and warnings; success is not provider authentication.
  • launch: submission is not training completion.
  • quality: recorded_study_passed can be false after a successful inspection.
  • status: inspect terminal state and execution uncertainty as well as stored metrics.

​
Prepare and review one run

Use a schema-derived configuration such as the SFT fixture:
validate reads configuration only. inspect-data reads bounded regular files, rejects malformed/ambiguous data, and reports positions without reflecting source values in errors. Samples require --include-samples. Preparation copies input privately and returns result.run.run_id, result.run.plan_sha256, result.review, and result.launch_argv. Retain that response. Repeating preparation creates another run. Inspect the actual model, revision, data identity, method, resource requests, timeout, seed, and billing policy before launching. Changing the dataset after preparation does not change its retained snapshot.

​
Launch the exact plan

Use the returned ID/checksum. If executing launch_argv programmatically, pass it as an argument array to subprocess.run; do not join it into shell code. Remote launches require --allow-paid, intentionally omitted from the returned array, and the backend’s reviewed cost policy. Add it only for authorized paid execution. The worker rechecks plan bytes, dataset identity, package code, and submission ownership. An identical launch retry returns already_submitted: true and starts no new worker, even after failure. This is submission idempotence, not restart or checkpoint recovery. Known terminal states include succeeded, failed, and cancelled. Interrupted supervision or unknown execution can yield terminal: null and state.execution_unconfirmed: true: the detached worker may still be active. A completion file alone cannot establish success; an owned worker must publish the checked outcome. Inspect the original run before preparing a replacement or repeating paid work.

​
Inspect and stop

Logs explicitly expose private output. Reads cover at most the final 128 KiB; offsets address that bounded window. auto chooses nonempty training output with supervisor fallback; explicit sources do not fall back. Missing output is not training success. Provider status reads plan-bound retained allocation/cleanup receipts without provider calls, reconnection, cancellation, or retries. Reconcile uncertain resources through the actual provider before starting another remote run. Local stops are cooperative and idempotent for the same plan. A receipt does not establish worker exit. Queued jobs wait for admission, active training stops at a safe boundary, and supervisor loss does not remove the reviewed local stop path. Changed package code and remote backends reject unsupported local stops. Use exact recovery instead of changing a failed plan to resume. Use paired evaluation to assess quality; latest training-metric deltas are not a quality winner.

​
HTTP operator API

The newer /finetune routes require strict authentication and the admin role even when general gateway development routes permit anonymous access. Configure an existing absolute workspace in server-side STATESET_FINETUNE_WORKSPACE. This is a single-operator workspace, not a tenant ownership grant; clients cannot choose arbitrary server data/report paths. Streamed body limits are 64 KiB for configuration, 8 MiB for quality, and 4 KiB for stop. Overlapping setup/artifact inspections return 429 with inspection_busy; metadata and local stop remain available. HTTP failures use the gateway status/error envelope and specific detail codes. A successful response can still report invalid settings or a failed study gate. These routes do not launch training, run a judge, prepare recovery, or guarantee remote cleanup. Use the CLI/TUI for separately reviewed preparation and execution. The generated Agents API reference is a separately exported snapshot; inspect the running server’s capabilities for this newer source-derived surface. Source basis: docs/FINETUNING_AGENTS.md, stateset_agents/cli_finetune.py, and the current finetune schema, reviewed October 20, 2026. Continue with checkpoint and quality evidence.
Last modified on October 20, 2026