Skip to main content
Training guide chapters All documentation

Training CLI: commands and options

The project command line, from setup to recovery, evaluation, export and exit codes.

Training guide chapters

Commands and code stay in English in every language. Replace uppercase placeholders with values from your own account and paid job; do not paste real keys into shared notebooks or logs.

The command-line workflow

Each command has a specific side effect and a meaningful result.
  1. init / doctor Create and check the project
  2. plan Review without training
  3. run Train within budgets
  4. evaluate Check held-out criteria
  5. export Validate and package

Follow one explicit command sequence

The fpai-training executable uses the same project contract as the Python interface: initialize, inspect compatibility, review the dry-run plan, execute, evaluate and export. Reading status or a plan is not proof that training succeeded.

  • Authentication is read from FUSIONPOINTAI_API_KEY. There is no API-key command-line flag.
  • Use --help on the executable or a command. --version reports the installed package version.
  • The reviewed plan fixes resolved settings. No undocumented CLI hyperparameter overrides are supported.
Complete CLI command reference
Field or interfaceType or resultDefault or exit codeBehavior and validation
init --directory PATH command Required / no default Create a new project skeleton and example configuration; refuse an existing nonempty directory. No training or paid calls.
doctor --config PATH command Required / no default Check schema, local model files, dependencies, storage, devices and adapter compatibility. No weight updates or teacher generation.
plan --config PATH --dry-run command Required / no default Resolve defaults, pin fingerprints and show topics, sharing, budgets and outputs. No optimization or paid teacher work.
run --config PATH command Required / no default Require a reviewed valid plan and active entitlement; lock one run and execute real training within budgets.
status --run PATH command Required / no default Read the redacted local run snapshot. Does not restart workers or generate teacher requests.
pause --run PATH command Required / no default Request a safe pause and wait for a complete atomic checkpoint. Valid only for an active owned run.
resume --run PATH command Required / no default Resume a paused/interrupted recoverable run only after strict checkpoint and plan validation.
cancel --run PATH command Required / no default Stop owned workers, release owned resources and record cancellation; preserve valid output and diagnostics.
evaluate --run PATH --split test command Required / no default Evaluate the pinned model against validation or test data. No optimization and no hidden-data sharing.
export --run PATH --format safetensors command Required / no default Validate and package an accepted supported output; no external upload or live deployment.
Example · bash 
fpai-training --version
fpai-training --help
fpai-training init --directory ./german-project
# Replace training.json and rubric/data files with your reviewed configuration.
fpai-training doctor --config ./german-project/training.json
fpai-training plan --config ./german-project/training.json --dry-run
# Inspect resolved values, data sharing and budgets BEFORE the next command.
fpai-training run --config ./german-project/training.json
fpai-training status --run ./german-project/runs/german-001
fpai-training evaluate --run ./german-project/runs/german-001 --split test
fpai-training export --run ./german-project/runs/german-001 --format safetensors
# Supply the key through FUSIONPOINTAI_API_KEY, never a command-line argument.

Pause, resume or cancel safely

Control commands address one owned run directory. Pause waits for an atomic checkpoint and worker acknowledgement. Resume validates the same model, data, configuration, evaluator and distributed topology. Cancel stops only the run’s workers and records a terminal cancellation. Repeating a control request must not create another training process.

  • A paused run is recoverable, not completed. A cancelled run is not an accepted deliverable.
  • Use a second terminal for controls while a foreground run is active.
  • After a timeout, read status before retrying. Do not delete lock files or kill unrelated GPU jobs.
Command options
Field or interfaceType or resultDefault or exit codeBehavior and validation
--directory path Required / no default Required for init. A writable new project directory.
--config path Required / no default Required for doctor, plan and run. Path to a complete schema 1.0 file.
--run path Required / no default Required for status, pause, resume, cancel, evaluate and export. Owned run directory, not an account/session ID.
--dry-run flag true Explicit plan flag; plan is always read-only with respect to weights and paid work. No false/off execution mode.
--split enum "test" evaluate only: validation or test. Test data is never used for improvement.
--format enum "safetensors" export only: safetensors or adapters, subject to adapter capability.
--help flag false Show executable or command help without accessing the provider.
--version flag false Show actual installed release metadata, not the configuration schema version.
Example · bash 
# Run controls from a separate terminal if training is active.
fpai-training pause --run ./german-project/runs/german-001
# Wait for status=paused and a completed atomic checkpoint before stopping a host.
fpai-training status --run ./german-project/runs/german-001
fpai-training resume --run ./german-project/runs/german-001
# Cancellation is terminal; preserve existing artifacts, do not pretend it passed.
fpai-training cancel --run ./german-project/runs/german-001
# Repeat status, not run(), after a timeout. Never kill an unrelated process.

Interpret state and exit codes together

Exit zero means the requested operation succeeded; a successful status read, pause or dry run is not accepted training. The training result also needs a completed state, accepted stop reason and all required evaluation criteria. Failed targets remain visible in reports instead of being relabelled successful.

  • Commands write machine-readable JSON to stdout and redacted diagnostics to stderr. Secrets never appear in either stream.
  • Run and resume wait for a terminal or paused state; status returns the current snapshot.
  • SIGINT exits 130 after best-effort owned-worker cleanup. An interrupted process cannot fabricate a completed checkpoint.
Example · text 
SDK 0.2.0 EXIT AND STATE CONTRACT
0   accepted, successful read/control, or successful dry-run; inspect operation.
2   invalid configuration; no training started.
3   incompatible model/runtime/method/export combination.
4   authentication, entitlement or authorized-sharing failure.
5   resource budget exhausted; preserve latest valid checkpoint and report.
6   evaluation requirements not met; not an accepted model.
7   execution, checkpoint, cancellation-control or export failure.
130 interrupted by the caller.

Lifecycle:
planned -> preparing -> training -> evaluating -> completed
training -> pausing -> paused -> training (validated resume)
active -> cancelling -> cancelled
active -> failed

stop_reason: accepted | budget_exhausted | no_progress | regression |
             cancelled | failed
paused is a recoverable state, not an accepted training result.
completed requires stop_reason=accepted and all required criteria passing.
Repeated control requests must read/reuse the owned transition, not spawn workers.
One run lock prevents duplicate execution of the same run directory.