locopilot train

Submit a fine-tuning job.

Source: src/cli/commands/train.ts

Synopsis

locopilot train --config <file> [--cloud]

Flag	Required	Default	Description
--config <file>	✅	—	Path to a JSON config file (see training/configuration)
--cloud	❌	false	Route the job to LocoPilot Cloud instead of running locally. Requires locopilot login.

Free tier (local in-process)

locopilot train --config train.json

The job is POST-ed to http://localhost:8080/v1/locopilot/training/jobs. The local API immediately enqueues it on the in-process BasicWorker and returns a job ID. The CLI then opens an SSE stream from /v1/locopilot/training/jobs/<id>/logs and forwards every line to stdout.

  Submitting training job...

  ✔ Job created: job_7f3a2b
    Framework:  unsloth
    Base model: meta-llama/Meta-Llama-3-8B

  Tailing logs...

[unsloth] Loading meta-llama/Meta-Llama-3-8B ...
[unsloth] Step 50/300 — loss: 1.42
[unsloth] Step 100/300 — loss: 0.98
...
[unsloth] Training complete ✔

  Adapter saved to: /Users/you/locopilot/out/lora-llama3-8b/

What gets validated

Before submission the CLI:

1. Reads and JSON-parses the file at --config. Aborts on parse error.
2. Verifies the four required fields: framework, baseModel, datasetPath, outputDir.
3. Resolves relative datasetPath and outputDir paths against the config file's directory (not the CWD) so configs are portable.

The full config schema lives in training/configuration.

Pro tier (cloud)

locopilot train --config train.json --cloud

The job is POST-ed to LocoPilot Cloud's /api/train, which enqueues it on a BullMQ queue. Logs stream from /api/train/<id>/logs (Redis pub/sub-backed SSE).

If your subscription is missing or expired the cloud call rejects with a ProSubscriptionRequiredError and the CLI prints the upgrade URL.

Apple Silicon

On darwin/arm64 the local worker auto-selects the MLX adapter (framework: 'mlx' in config) regardless of what you wrote — Unsloth and Axolotl don't run on Metal. The same dataset and JSONL formats work; only the runner differs. See training/adapters.

Errors

Error	Cause
Config missing required field: framework / baseModel / datasetPath / outputDir	Required field absent in the JSON
Could not connect to API: …	The local API isn't running — locopilot start first
Not logged in. Run: locopilot login	--cloud was used but no Pro token is stored
✖ Pro subscription not active.	Cloud rejected the job — your Stripe subscription is past-due / cancelled
Job rejected: <validator error>	Dataset format invalid (see training/datasets)

Tail an existing job

If your terminal disconnects, the job keeps running. Reattach with locopilot logs:

locopilot logs --job job_7f3a2b