> ## 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.

# evolve dataset

> Browse and publish the dataset catalog.

```bash theme={null}
evolve dataset <command> [options]
```

## dataset list

```bash theme={null}
evolve dataset list [options]
```

List the dataset catalog.

<ParamField path="-l, --limit" type="n">
  Page size.
</ParamField>

<ParamField path="--cursor" type="c">
  Resume from a page cursor.
</ParamField>

<ParamField path="--columns" type="keys | all | help">
  Choose and order columns, comma-separated. `help` lists the keys.
</ParamField>

<ParamField path="-q, --quiet">
  Print only ids, one per line, for piping.
</ParamField>

<ParamField path="--no-trunc">
  Full cell content instead of one-line truncation.
</ParamField>

<ParamField path="--no-headers">
  Omit the header row in piped (TSV) output.
</ParamField>

<ParamField path="--search" type="text">
  Free-text filter over name and description.
</ParamField>

## dataset show

```bash theme={null}
evolve dataset show <name[@version]> [options]
```

Show one dataset: its versions, its manifest identity, its tasks with a NOTES column, the providers each task can run on, and the failed tasks of the shown version with their reasons. One line reports a git dataset whose upstream ref has moved; it never appears in `--json`, where the same fact is the `upstream` field.

<ParamField path="-l, --limit" type="n">
  Task-list page size.
</ParamField>

<ParamField path="--cursor" type="c">
  Resume the task list from a cursor.
</ParamField>

```bash theme={null}
evolve dataset show terminal-bench-4@4.0
```

## dataset check

```bash theme={null}
evolve dataset check <dir>
```

Pre-flight a local corpus. A dry run: nothing is uploaded, nothing is written. Prints a verdict per task and exits 1 on any refusal.

## dataset publish

```bash theme={null}
evolve dataset publish [options]
```

Publish a dataset version from a git source, a local directory, or a fetchable source: a public tarball URL, or a public hub package. A name owned by someone else is refused before the bytes move, and an archive over the published ceiling is refused with `import_too_large`.

A directory upload prints `upload <sent>/<total> (P%)` once per 10% of the archive; with `--json --watch` the same steps are `upload.progress` events (`sent_bytes`, `total_bytes`, `elapsed_sec`). A large upload prints `Registered import <id>` early and reads `QUEUED (receiving)` until the corpus has arrived. Once the build settles, `--watch` prints every task's outcome and ends with `built N of M tasks`.

<ParamField path="--git" type="url">
  Git repository URL. With `--ref`.
</ParamField>

<ParamField path="--ref" type="ref">
  Pinned git ref: a full 40-hex commit sha, or a tag, resolved to its commit at publish and verified at import. Branch names are refused as `unpinned_git_ref`. With `--git`.
</ParamField>

<ParamField path="--path" type="subfolder">
  Repository subfolder holding the corpus. With `--git`; only that folder is imported.
</ParamField>

<ParamField path="--dir" type="path">
  Local corpus directory, tarred and uploaded. Pre-flighted first; see `--skip-preflight`.
</ParamField>

<ParamField path="--from" type="url | hub:org/name[@ref]">
  Fetchable source the server pulls itself, with no local bytes: a public https tarball URL, or `hub:org/name[@ref]`, a public Harbor hub package. The ref is the latest tag by default, a revision number, or `sha256:<digest>`; it is resolved and digest-pinned when the publish is accepted.
</ParamField>

<ParamField path="--name" type="dataset">
  Catalog dataset name to create or extend. Optional with `--dir` when the corpus carries a `dataset.toml` manifest, and with `--from hub:…`, which defaults to the package's short name. Required with `--git` and `--from <url>`.
</ParamField>

<ParamField path="--version" type="v">
  Version label for the published version. Optional with `--dir` when `dataset.toml` declares one, and with `--from hub:…`, which defaults to the resolved revision. Required with `--git` and `--from <url>`.
</ParamField>

<ParamField path="--watch">
  Poll until the publish settles: the version `READY` (built and active) or `FAILED`.
</ParamField>

<ParamField path="--skip-preflight">
  Upload without the pre-flight check. A refused task then lands `FAILED` at import instead of being caught here.
</ParamField>

```bash theme={null}
evolve dataset publish --from hub:cookbook/hello-world --watch
```

## dataset watch

```bash theme={null}
evolve dataset watch <name | import-id>
```

Re-attach to a publish and follow it to `READY` or `FAILED`, the same follow `dataset publish --watch` renders. Works after the CLI exited, or from another machine. A name with no live publish is refused, naming the newest settled import. With `--json` the same events stream, opened with `import.attached`; the transfer's own `upload.progress` lines belong to the publishing process and never appear here.

## dataset download

```bash theme={null}
evolve dataset download <name[@version]> [options]
```

Download the original corpus package. Owner only.

<ParamField path="-o, --output-dir" type="dir">
  Directory to save into. Defaults to the current directory.
</ParamField>

## dataset activate

```bash theme={null}
evolve dataset activate <name> <version>
```

Make a `READY` version the dataset's active version.

## Global options

<ParamField path="--json">
  Machine-readable JSON output.
</ParamField>

<ParamField path="--api-key" type="key">
  API key. Defaults to `$EVOLVE_API_KEY`.
</ParamField>

<ParamField path="--base-url" type="url">
  API base URL. Defaults to the Evolve dashboard API.
</ParamField>