> ## Documentation Index
> Fetch the complete documentation index at: https://docs.freesolo.co/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI reference

> Every flash command and flag.

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)                       |

## Auth & identity

<ResponseField name="flash login" type="[--api-key KEY] [--freesolo-url URL] [--api-url URL]">
  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`.
</ResponseField>

<ResponseField name="flash whoami">
  Show the identity your stored key resolves to.
</ResponseField>

<ResponseField name="flash version">Print the Flash version.</ResponseField>

## Discovery

<ResponseField name="flash models">
  List the supported base model ids. See [Supported models](/reference/models)
  for algorithms, reasoning, and pricing.
</ResponseField>

<ResponseField name="flash gpus">
  List active validated GPU classes with VRAM, provider availability, and
  estimated \$/hr. Selection is automatic by default; `[gpu] exact_type` pins an
  exact class.
</ResponseField>

## Environments

<ResponseField name="flash env setup [flags]">
  Scaffold a [starter project](/directory-structure) into the current directory:
  `environment.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.

  On an interactive terminal it first runs a short survey about the interaction
  shape (single- vs multi-turn) and whether to train with reasoning, then
  scaffolds to match. The flags below skip the questions; a non-interactive run (no TTY, `CI`,
  or `-y`) takes the defaults (single-turn, no reasoning). A flag that disagrees
  with an already-scaffolded project is ignored with a warning.

  | Flag             | Default | Effect                                                                                                                                                       |
  | ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
  | `--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                                                                                                                        |
</ResponseField>

<ResponseField name="flash env push --name NAME [PATH]">
  Publish a local Freesolo environment to Freesolo's [managed Environments
  Hub](/guides/environments/package#publish-it) (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](/guides/datasets#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.
</ResponseField>

<ResponseField name="flash env pull ENV_ID [PATH] [-o OUTPUT] [-f]">
  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`; the package is
  downloaded through the Flash control plane. 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.
</ResponseField>

<ResponseField name="flash env list">
  List local environment sources you can publish.
</ResponseField>

<ResponseField name="flash env delete ENV_ID [-y]">
  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. Pass `-y`/`--yes` to skip the confirmation prompt.
</ResponseField>

## Training

<ResponseField name="flash train CONFIG [flags]">
  Submit a managed training run from a [TOML config](/reference/configuration) and follow its logs.
  Before submit, Flash checks your prepaid balance against the pre-flight
  estimate. Successful runs are billed at the quoted Flash cost (see
  [Cost & billing](/guides/training#cost-and-billing)). [Cost and billing](/reference/cost-model) explains the pre-flight `--cost`
  estimate.

  | Flag              | Effect                                                                               |
  | ----------------- | ------------------------------------------------------------------------------------ |
  | `--dry-run`       | Run authenticated server submit preflights; create `state=dry_run`; no GPU or charge |
  | `--cost`          | Print the local pre-flight USD cost and exit (no submit)                             |
  | `--background`    | Submit and return immediately instead of following logs                              |
  | `--set KEY=VALUE` | Override a config value (dotted key, repeatable)                                     |
  | `--config FILE`   | Deep-merge additional TOML for config composition (repeatable)                       |
</ResponseField>

## Run management

<ResponseField name="flash runs">
  List your runs with state, algorithm, cost, and model.
</ResponseField>

<ResponseField name="flash status RUN_ID [-f]">
  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 worker logs.
</ResponseField>

<ResponseField name="flash log RUN_ID [-f]">
  Print a run's full logs, including worker console/error artifacts.
  `-f`/`--follow` streams new logs until the run reaches a terminal state.
</ResponseField>

<ResponseField name="flash cancel RUN_ID">
  Cancel a run. The CLI waits for the managed worker to stop before returning,
  which can take several minutes.
</ResponseField>

## Serving

<ResponseField name="flash deploy RUN_ID[/step-N] [--dry-run]">
  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](/guides/deploy-and-chat#billing).

  If no final adapter exists, use the `RUN_ID/step-N` selector listed by
  `flash checkpoints RUN_ID`.
</ResponseField>

<ResponseField name="flash checkpoints RUN_ID">
  List a run's saved SFT, GRPO, or OPD checkpoints available to deploy. Serve
  one with `flash 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"`).
</ResponseField>

<ResponseField name="flash chat TARGET -m MESSAGE [flags]">
  Send a message to a deployment. `TARGET` is the stable `RUN_ID` alias or a full
  immutable revision. `RUN_ID/step-N` is not a chat target.

  | 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                                                                                                  |
</ResponseField>

<ResponseField name="flash deployments [--json]">
  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`.
</ResponseField>

<ResponseField name="flash undeploy RUN_ID">
  Disable the stable alias and all immutable revisions for the run.
</ResponseField>

## Export

<ResponseField name="flash export --adapter-id ID --repository OWNER/NAME [flags]">
  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                                                                         |
</ResponseField>

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    The commands in a full end-to-end run.
  </Card>

  <Card title="Troubleshooting" icon="life-ring" href="/reference/troubleshooting">
    Fix common CLI and auth errors.
  </Card>
</CardGroup>