> For the complete documentation index, see [llms.txt](https://docs.unitlab.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.unitlab.ai/api-sdk-cli/clis/cli-datasets-and-versions.md).

# CLI: datasets and versions

### Product state behind the commands

![Dataset history for published CLI-visible versions](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2FVlkSuopZNbC9JUP9uVx1%2Fdataset-history.png?alt=media\&token=27ae53b7-17d1-45dc-a93b-200509328987)

*CLI dataset commands create and inspect the same version history shown in the product. Use explicit version numbers in automation.*

{% hint style="info" %}
**Outcome:** Create datasets, add sources, publish versions, and inspect draft or versioned membership.
{% endhint %}

```bash
unitlab dataset list --json
unitlab dataset create "Training set" --folder-id FOLDER_ID --json
unitlab dataset add-sources DATASET_ID --asset-id ASSET_ID --json
unitlab dataset unpublished-changes DATASET_ID --json
unitlab dataset publish DATASET_ID "Added edge cases" --json
unitlab dataset versions DATASET_ID --json
unitlab dataset items DATASET_ID --version 3 --json
```

Publish only after reviewing draft membership. Use explicit version numbers when attaching data or recording a reproducible pipeline.

### Operating contract

| Concern           | Required behavior                                                           |
| ----------------- | --------------------------------------------------------------------------- |
| Execution surface | Pinned `unitlab==3.0.0` command in the intended Python 3.10+ environment.   |
| Machine contract  | Use `--json`; human-readable output is not an automation interface.         |
| Target resolution | Resolve stable IDs with a read command before a state-changing command.     |
| Success evidence  | Exit status, JSON result, returned IDs, and a read-after-write state check. |

### Failure and recovery boundary

| Condition                                       | Response                                                                                                     |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Authentication or authorization fails           | Stop, correct the service identity or access model, rotate exposed credentials, and rerun a read-only check. |
| Validation or entitlement rejects the operation | Correct the input or entitlement; do not retry an unchanged request.                                         |
| A request times out                             | Inspect remote state before repeating a mutation because the server may have accepted it.                    |
| Asynchronous processing exceeds its deadline    | Preserve the Batch Queue or release ID, continue bounded monitoring, and inspect item-level failures.        |
| Only part of a batch succeeds                   | Keep successful identifiers, isolate failed rows, and retry only the corrected subset.                       |

{% hint style="warning" %}
Pin and test the production SDK version. Use stable IDs, keep secrets out of logs and command history, and record the correlation ID, target IDs, counts, final state, and redacted error details for material state changes.
{% endhint %}