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

# learning-env

> Reference for relai learning-env commands.

Use `relai learning-env` to create or upload repeatable scenarios.

## `create`

Create a learning environment from a prompt or from a run log plus feedback.

```sh theme={"system"}
relai learning-env create [OPTIONS] --prompt {PROMPT}
relai learning-env create [OPTIONS] --log-file {PATH} --feedback {TEXT}
```

<Warning>
  Learning environment generation can take a while when the prompt, run log, or agent context is complex.
</Warning>

| Option                    | Description                                                                                                       |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `--prompt {TEXT}`         | Behavior to turn into a learning environment.                                                                     |
| `--log-file {PATH}`       | Agent run log, in any text format. Requires `--feedback`.                                                         |
| `--feedback {TEXT}`       | Feedback about the run. Requires `--log-file`.                                                                    |
| `--name {NAME}`           | Stable generated file name and environment id.                                                                    |
| `--agent-target {TARGET}` | Registered target for this learning environment. Required non-interactively when multiple targets are registered. |

```sh theme={"system"}
relai learning-env create --prompt "{describe the behavior to test}"
relai learning-env create --log-file {path/to/run-log} --feedback "{describe the behavior to preserve}"
relai learning-env create --prompt "{describe the behavior to test}" --name {name}
relai learning-env create --prompt "{describe the behavior to test}" --agent-target {target}
```

The run log does not need a specific structure: any text format under the
size limit works, including JSONL message logs, plain transcripts, or your
own trace format. RELAI parses it. Logs that include internal detail — tool
calls, retrievals, intermediate reasoning — give RELAI more to work with than
user-facing output alone.

Creates a learning-environment file under `.relai/learning-envs/` using the project's language. Interactive successful flows may offer to commit and upload it. Non-interactive flows print follow-up commands.

Learning environments are scoped to the selected agent target. When multiple
targets are registered, interactive runs present a single-target picker; pass
`--agent-target {target}` in non-interactive runs.

After upload, open the [Agents page](https://platform.relai.ai/agent), select your agent, and use the Learning Environments tab.

Common failures: prompt over 8 KB, feedback over 32 KB, log file over 160 KB, missing paired `--feedback`, backend generation failure, validation failure, duplicate explicit name, or dirty generated paths.

## `upload`

Upload an existing committed learning environment.

```sh theme={"system"}
relai learning-env upload --learning-envs {name}
```

```sh theme={"system"}
relai learning-env upload --learning-envs {name-a},{name-b}
relai learning-env upload --learning-envs {name} --agent-target {target}
```

Uploads the exact source and git metadata to the RELAI backend.
Use `--agent-target {target}` only to upload a legacy learning environment that
does not declare its target in source; a declared target always takes precedence.

Common failures: file missing, invalid learning environment, file not tracked or not committed at current `HEAD`, uncommitted changes, detached `HEAD`, or backend branch conflict.