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

# Quick start

> Start your first job, watch it run, and download a trial.

This page takes you from an empty terminal to a downloaded trial: one API key, any harness, any model, any sandbox provider, and every trial's trace streamed live. A trial is one agent's attempt at one task. A job is a set of trials: the tasks of one or more datasets, run by one or more agents.

<Steps>
  <Step title="Install the CLI and set your key">
    ```bash theme={"dark"}
    npm install -g @evolvingmachines/evolve
    export EVOLVE_API_KEY="<your key>"
    evolve auth status
    ```

    Create a key on the dashboard's [API keys page](https://dashboard.evolvingmachines.ai/api-keys), then export it. See [installation](/getting-started/installation) for the SDKs.
  </Step>

  <Step title="Give your coding agent the manual">
    ```bash theme={"dark"}
    evolve skills install
    ```

    Your agent then reads these docs with `evolve skills get evals`, and the `create-task`, `rewardkit`, `create-adapter` and `publish` skills by name. [The five skills](/cli-reference/skills).
  </Step>

  <Step title="Pick a dataset">
    The catalog lists every dataset you can run, with its versions.

    ```bash theme={"dark"}
    evolve dataset list
    evolve dataset show terminal-bench-4@4.0
    ```

    `dataset show` prints the version's tasks and, for each task, which sandbox providers can run it.
  </Step>

  <Step title="Start a job and watch it">
    Name a dataset, an agent, and a model. `--watch` streams the job's events until it finishes; `-l 5` caps the run at five tasks and `--max-trial-spend 1` caps what each trial may spend on the model, so the first job is small.

    ```bash theme={"dark"}
    evolve run \
      -d terminal-bench-4@4.0 \
      -a codex \
      -m gpt-6-astra \
      -l 5 \
      --max-trial-spend 1 \
      --watch
    ```

    The final block prints the job id, how many trials landed in each status, and what the trials spent. Without `--watch` the command returns the id at once and the job keeps running.
  </Step>

  <Step title="Read the result">
    ```bash theme={"dark"}
    evolve job show <job-id>
    evolve job trials <job-id>
    evolve trial show <trial-id>
    ```

    `job show` is the whole job: how many trials landed in each status, the rewards, the spend. `job trials` lists the trials one per line with their ids. `trial show` is one trial in full, with its reward and, when it failed, why.
  </Step>

  <Step title="Download the trial">
    A trial downloads as a trial tree: the trajectory, the agent's stdout and stderr, the verifier log, and the reward.

    ```bash theme={"dark"}
    evolve trial download <trial-id> -o trials/
    ```

    To read one artifact without saving anything, stream it instead.

    ```bash theme={"dark"}
    evolve trial download <trial-id> --stream verifier
    ```
  </Step>
</Steps>

## Next, by what you want to do

<Columns cols={2}>
  <Card title="Port a benchmark" icon="arrow-right-left" href="/core-concepts/tasks">
    `evolve skills get create-adapter` turns it into Harbor-format tasks.
  </Card>

  <Card title="Write a task" icon="file-plus" href="/core-concepts/tasks">
    `evolve skills get create-task`, and `rewardkit` for its verifier.
  </Card>

  <Card title="Publish a dataset" icon="upload" href="/core-concepts/datasets">
    `evolve skills get publish`, then `evolve dataset publish`.
  </Card>

  <Card title="Upload a job you ran elsewhere" icon="folder-up" href="/core-concepts/upload">
    `evolve upload <job dir>` brings a Harbor job into the dashboard.
  </Card>
</Columns>