> ## Documentation Index
> Fetch the complete documentation index at: https://freesolo.co/docs/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. The key is verified against Freesolo and
  saved locally, and the resolved identity is printed 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 the managed GPU classes with VRAM and estimated \$/hr. GPU selection is
  automatic — you don't pick one.
</ResponseField>

## Environments

<ResponseField name="flash env setup">
  Scaffold a [starter project](/directory-structure) into the current directory: `environment.py`, a tiny
  `dataset/train.jsonl`, `configs/sft.toml` (SFT) plus `configs/rl.toml` (GRPO),
  and a `TRAINING.md` playbook for coding agents with current CLI usage, reward
  guidance, and common run mitigations. Existing files are preserved.
</ResponseField>

<ResponseField name="flash env push --name NAME [PATH]">
  Publish a local Freesolo environment to Freesolo's [managed Environments Hub](/guides/environments#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`; the namespace is validated by Freesolo and must match your
  Freesolo org namespace (a mismatch is rejected); `PATH` defaults to the current
  directory. Pass `.` or any folder with `environment.py` at its root so helper
  modules, `dataset/`, `README.md`, and common sibling sidecars are uploaded
  ([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` chooses the output path and `-f` allows overwriting 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.
  Flash checks prepaid balance against the pre-flight estimate before submit, and
  successful runs are billed at the quoted Flash cost (see
  [Cost & billing](/guides/training#cost-and-billing)). The pre-flight `--cost`
  estimate is explained in
  [Cost and billing](/reference/cost-model).

  | Flag              | Effect                                                                    |
  | ----------------- | ------------------------------------------------------------------------- |
  | `--dry-run`       | Validate the config locally and print the resolved job spec; don't submit |
  | `--cost`          | Print the pre-flight USD cost for the config 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 [flags]">
  Register a trained adapter with the managed serving service.
  Serving is [billed per token](/guides/deploy-and-chat#billing).

  | Flag          | Default | Effect                                                                                                                                                  |
  | ------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `--dry-run`   | -       | Preview the deploy without creating it                                                                                                                  |
  | `--no-verify` | -       | Skip the server-side post-deploy smoke check. Registration alone does not guarantee the adapter serves, so use this only when you'll verify separately. |

  If the run has no final adapter (for example it was cancelled or preempted
  before finalizing) but saved per-step checkpoints, a run-level deploy fails
  with a clear error listing the available steps and the exact
  `flash deploy RUN_ID/step-N` command to use instead.
</ResponseField>

<ResponseField name="flash checkpoints RUN_ID">
  List a run's per-step checkpoints that are available to deploy — including
  intermediate checkpoints from a live or stopped RL run. 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 RUN_ID -m MESSAGE [flags]">
  Send a message to a deployed adapter and stream the reply as it is generated.

  | Flag              | Default    | Effect                                                                                                                                     |
  | ----------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
  | `-m`, `--message` | (required) | The user message                                                                                                                           |
  | `--system`        | -          | Optional system prompt sent ahead of the user message (transient — used for this request only). Useful for training-prompt parity in evals |
  | `--max-tokens`    | `512`      | Max tokens to generate                                                                                                                     |
  | `--temperature`   | `0.0`      | Sampling temperature                                                                                                                       |
</ResponseField>

<ResponseField name="flash deployments">
  List active serving deployments and endpoints.
</ResponseField>

<ResponseField name="flash undeploy RUN_ID">
  Deregister a run's adapter from serving so it no longer accepts requests.
</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>