CLI reference

The CLI is flash. Run flash --help or flash <command> --help for inline help.

Global flags

Flag	Effect
`-V`, `--version`	Print the Flash version and exit
`--debug`	Show full tracebacks on error (otherwise errors print one clean line)
`-v`, `-vv`	Increase log verbosity (`-v` info, `-vv` debug)

Run-management and serving commands are grouped under flash runs and flash models.

Auth & identity

Log in with your Freesolo API key. Flash verifies the key against Freesolo, saves it locally, and prints the resolved identity on success. Defaults: --api-key from FREESOLO_API_KEY; --freesolo-url from FREESOLO_BASE_URL (else https://api.freesolo.co); --api-url from FLASH_API_URL.

Show the identity your stored key resolves to.

Print the Flash version.

Projects

Every training run and every published environment belongs to one Freesolo project, named by its UUID. Configs carry it as the top-level project field; env push and env delete take it as --project.

Create a project in your organization and print its UUID. Names are unique per org, so reusing one is rejected. On a styled terminal the UUID is printed with its name; otherwise the bare UUID is printed, so it captures cleanly in a script (PROJECT=$(flash projects create my-project)).

List your organization’s projects with their UUIDs. Piped or redirected output is one tab-separated UUID<TAB>NAME per line. Use this to find the UUID for a config’s project field or a --project flag.

Discovery

List the supported base model ids. See Supported models for algorithms, reasoning, and pricing.

List active validated GPU classes with VRAM, provider availability, and estimated $/hr. Selection is automatic by default; [gpu] type pins an exact class.

Environments

Scaffold a starter project into the current directory: environment.py, a starter evaluations.py, a tiny dataset/train.jsonl, configs/sft.toml (SFT), configs/rl.toml (GRPO), and configs/opd.toml (OPD), plus a TRAINING.md playbook for coding agents with current CLI usage, reward guidance, and common run mitigations. Existing files are preserved.Setup needs a project, so run flash login first. --project is required without a TTY or with -y; otherwise an interactive run prompts. The UUID is written into every generated config. If configs already exist, setup refuses to continue when one has no valid project or names a different one, rather than rewriting them.An interactive run surveys the interaction shape and whether to train with reasoning, then scaffolds to match; the flags below skip the questions. If the project has recorded traces and no dataset/train.jsonl exists, it also offers to seed the dataset from them and sizes max_examples to the export. An existing dataset is never overwritten.

Flag	Default	Effect
`--project PROJECT_UUID`	prompt	Project for the generated configs and environment publication. Required without a TTY or with `-y`
`--single-turn`	default	Scaffold an `EnvironmentSingleTurn` env (prompt → one response)
`--multi-turn`	-	Scaffold a bounded-episode `EnvironmentMultiTurn` starter (`start_episode` / `step_episode` / `max_episode_turns` / `score_episode`) with a matching dataset
`--reasoning`	-	Scaffold configs with reasoning on (`thinking = true`, and a raised GRPO completion budget)
`--no-reasoning`	default	Scaffold configs without reasoning
`-y`, `--yes`	-	Accept the defaults without prompting

Validate a local environment offline before publishing. Loads the same entrypoint flash env push would package (PATH defaults to .) and drives its first few dataset episodes with no GPU and no model: it checks that prompts, SFT completions, and any multi-turn replies are well-formed chat messages and that the reward is finite, printing a short prompt/response preview per episode. It replays the dataset’s gold sft_completion as the policy answer when one is present, otherwise a canned response. Prints overall: PASS and exits 0 when every driven episode passes the contract checks, or overall: FAIL and exits 1 on a load error, an empty dataset, malformed messages, a hook exception, or a non-finite reward.PASS means the environment contract is valid, not that the reward is high. A partially low replayed reward is a warning, not a failure. But if every replayed gold answer scores zero the gate fails: a reward function that cannot recognize its own reference answers would only ever see flat-zero reward on a GPU. Episodes with no gold answer to replay are exempt.--split selects the dataset split to drive, matching [environment.params] and defaulting to train. Use the split the run actually trains on, for example --split train_sft. --param KEY=VALUE is repeatable and passes any other load_environment() keyword argument; values parse as TOML scalars, so 1, true, and "x" keep their types. --split wins over --param split=....

Score held-out evaluation suites against a deployed model. TARGET is a bare RUN_ID, a RUN_ID/step-N checkpoint, or a full immutable adapter revision; PATH is the local environment directory or environment.py and defaults to ..Define the suites in an evaluations.py beside your environment.py:

from flash.envs.evaluations import BaseEvalSuite, EvalCase

class HeldOut(BaseEvalSuite):
    name = "held-out"

    def cases(self):
        return [EvalCase(id="sum", input="2+2", expected="4")]

def load_evaluations(environment=None):
    return [HeldOut()]

score() may return an EvalResult, a float, or a bool. A module-level EVALUATIONS list works instead of the factory, and the factory receives the loaded environment when it accepts one, so suites can reuse environment graders.--suite runs only the named suite, --max-cases caps the cases taken from each selected suite, and --concurrency (default 1, maximum 32) issues that many model requests in parallel while results stay in case order. Generation defaults to --temperature 0.0 and --max-tokens 512.A case that never reached the model is recorded as an error and excluded from pass_rate and mean_score rather than scored as a zero, so a broken deployment does not read as a low-quality model. Errors are printed, counted in the summary, and still fail the command. Requires Flash 1.0.34.

Publish a local Freesolo environment to Freesolo’s managed Environments Hub (private) and print its id (your-org/name). --name is required and is normalized to a lowercase hyphen slug. You can also pass an explicit namespace/name; Freesolo validates the namespace against your Freesolo org namespace and rejects a mismatch. PATH defaults to the current directory. Pass . or any folder with environment.py at its root to upload helper modules, dataset/, README.md, and common sibling sidecars (what gets uploaded lists the extensions). A single .py file, or a folder with one top-level .py file, also works for small smoke tests; single-file mode packages only that entrypoint, a sibling README.md/TRAINING.md, and any dataset/ tree. Secrets (.env files, *.key, *.pem, credentials*, SSH keys) and virtualenvs are never uploaded.--project is required and must be a project UUID from your organization (flash projects list). A malformed UUID is rejected before upload, and one that does not belong to your org fails the push. There is no fallback project. Environment names are unique per organization, so re-pushing an existing name under a different project is refused rather than moving it; move it from its environment page in the dashboard instead.

Download a published environment, or one file from it, to local disk. ENV_ID must be a managed Freesolo hub slug your-org/your-env. Without PATH, the whole environment is written to a directory. With PATH, only that file is fetched. -o sets the output path; -f overwrites an existing output.

List your organization’s published environments alongside the local sources you can publish. Each published id is ready to paste into [environment] id. If you are not logged in, the local sources still list and the published section says so rather than reporting an empty catalog.

Delete a managed Freesolo Hub environment. ENV_ID must be a lowercase namespace/name Hub id; GitHub refs and local paths cannot be deleted from the Hub. --project is required and must be the UUID of the project that owns the environment. Pass -y/--yes to skip the confirmation prompt.

Traces

Export a project’s recorded traces as freesolo environment records, ready to train on. By default each trace becomes an {"input", "output"} row, the same shape flash env setup scaffolds, so the output drops straight into an environment’s dataset/train.jsonl. A file exported here matches the dashboard’s trace export.--format picks the export shape (requires Flash 1.0.22; the dashboard export offers the same three):

records (default): {"input", "output"} environment records. Traces with no usable request/response pair are skipped.
prompts: {"input"} only. GRPO and OPD both train from prompts alone (GRPO samples its own completions and scores them with the environment; OPD distils from a managed teacher), so no gold reply is needed, and a call whose reply never arrived still exports.
raw: the stored trace rows with their spans, unconverted. Raw rows are not a dataset, so they default to traces.raw.jsonl instead of dataset/train.jsonl, where a later env push + train could pick them up.

There is no per-algorithm format: every algorithm reads the same environment records.Traces are stored per-project, so an export always reads exactly one project. Without --project, an interactive terminal prompts you to pick from the projects your key can reach; a non-interactive terminal errors with the available ids so you can pass --project. An export reads the newest 1000 traces; skipped traces are counted in the summary. Writing an existing file needs --force.

Flag	Default	Effect
`--project ID`	prompt	Project id to export from
`--format NAME`	`records`	`records`, `prompts`, or `raw`
`-o`, `--output`	`dataset/train.jsonl` (`traces.raw.jsonl` raw)	Output JSONL path
`-f`, `--force`	-	Overwrite an existing output file

Training

Submit a managed training run from a TOML config and follow its logs. The config must set a top-level project UUID; Flash validates it against your organization before any GPU is allocated, so a missing, malformed, or foreign project fails the submit rather than starting paid work. Before submit, Flash checks your prepaid balance against the pre-flight estimate. Successful runs are billed at the quoted Flash cost. See Cost and billing.

Flag	Effect
`--dry-run`	Run the same submit checks as a real run, without a training GPU
`--cost`	Print the pre-flight USD cost and exit (no submit); see the note below
`--background`	Submit and return immediately instead of following logs
`--gpus N`	Most cards to run the job on (`1`-`8`); sugar for `--set gpu.count=N`
`--set KEY=VALUE`	Override a config value (dotted key, repeatable)
`--config FILE`	Deep-merge additional TOML for config composition (repeatable)

On an SFT config with no cached workload profile, --cost and --dry-run start a short profile run that is billed on its own, and --cost exits without a quote until it finishes. No training GPU is allocated and no training is charged, but that first call is not free. GRPO and OPD quote offline and never do this. See Cost and billing.

On an OPD config, --dry-run also preflights the managed teacher, so an unavailable teacher fails before a run record is created rather than partway into a paid run. It checks image rows only where they are statically visible at submit time - packaged dataset rows and inline records. Images your environment builds in code are still caught on the worker, after allocation.--gpus pins a ceiling, not an exact count: allocation still picks a single card when one fits, and only rentable shapes (1, 2, 4, 8) are provisioned. It overrides a [gpu] count in the config, and omitting it leaves an authored count untouched. See Multi-GPU runs for the auto-sizing rule.

Run management

List your runs with state, algorithm, cost, and model.

Print a run’s status, including its current or final cost record. -f/--follow polls status until the run reaches a terminal state without replaying its logs.

Print a run’s full console and error logs. -f/--follow streams new logs until the run reaches a terminal state.

Cancel a run. The CLI waits for the run to stop before returning, which can take several minutes.

List a run’s saved SFT, GRPO, or OPD checkpoints available to deploy. Serve one with flash models deploy RUN_ID/step-N. When output is not a styled terminal, each line is single-space separated (step N RUN_ID/step-N), so it splits cleanly in scripts (awk, grep "step N").

Serving

Deploy a final adapter or checkpoint. Every real deploy resolves an immutable revision, runs a mandatory bounded smoke, and activates the stable run-id alias only after verification. --dry-run previews without creating a deployment. Serving is billed per token.If no final adapter exists, use the RUN_ID/step-N selector listed by flash runs checkpoint RUN_ID.A run whose config pinned model_revision, and any adapter warm-started from one, is refused: serving does not support revision-pinned base models.Without --wait, deploy returns while the revision is still queued. With it, the command blocks until the revision is servable and exits 0, or exits 1 if the deployment failed, the wait timed out, or the alias rolled back to the previously deployed revision. The timeout defaults to 1800 seconds; pass a value (--wait 600) to set your own, or --wait 0 for a single state read. Interrupting the wait with Ctrl-C stops waiting, not the deployment.

Send a message to a deployment. TARGET is the stable RUN_ID alias, a full immutable revision, or RUN_ID/step-N for a checkpoint you have already deployed, resolving to that checkpoint’s verified revision, so run flash models deploy RUN_ID/step-N first.

Flag	Default	Effect
`-m`, `--message`	(required)	The user message
`--system`	-	Optional system prompt sent ahead of the user message. It is transient and useful for training-prompt parity in evals
`--max-tokens`	`512`	Max tokens to generate
`--temperature`	`0.0`	Sampling temperature

List each active run alias and its currently active verified revision. Human output shows run id, step, revision, state, verification time, OpenAI model, and detail. --json includes complete records and openai_base_url.

Disable the stable alias and all immutable revisions for the run.

Export

Export a trained adapter to a HuggingFace repo you own (created if it doesn’t exist). --adapter-id is either RUN_ID for the final adapter or RUN_ID/step-N for a saved checkpoint. --repository is required.

Flag	Default	Effect
`--api-key`	`HF_TOKEN`	HuggingFace token with write access to `--repository` (read from your shell or a local `.env` / `.env.local`)
`--public`	private	Create the destination repo as public

Get started

Flash

Reference

Global flags

Auth & identity

Projects

Discovery

Environments

Traces

Training

Run management

Serving

Export

​Global flags

​Auth & identity

​Projects

​Discovery

​Environments

​Traces

​Training

​Run management

​Serving

​Export

Global flags

Auth & identity

Projects

Discovery

Environments

Traces

Training

Run management

Serving

Export