> ## Documentation Index > Fetch the complete documentation index at: https://docs.oumi.ai/llms.txt > Use this file to discover all available pages before exploring further. # DATASETS > Upload, version, analyze, and synthesize datasets | Command | Description | | ----------------------------------------- | ----------------------------------------------------------------------------------- | | [`analysis download`](#analysis-download) | Download a completed analysis's artifacts to local disk. | | [`analysis list`](#analysis-list) | List completed quality analyses for a dataset. | | [`delete`](#delete) | Permanently delete a dataset from the project. | | [`distill`](#distill) | Distill a dataset by generating completions from a model, waiting for it to finish. | | [`download`](#download) | Download a dataset version to local disk. | | [`get`](#get) | Show metadata for a single dataset. | | [`import-logs`](#import-logs) | Import a LangFuse or LangSmith trace export as a new dataset. | | [`items bulk-delete`](#items-bulk-delete) | Bulk-delete rows by explicit ID or by analysis-test failures. | | [`items get`](#items-get) | Show a single row (data item) from a dataset. | | [`items list`](#items-list) | List the rows (data items) in a dataset, optionally filtered. | | [`list`](#list) | List datasets in a project, optionally filtered and sorted. | | [`synthesize`](#synthesize) | Synthesize a new dataset from a recipe, waiting for it to finish. | | [`update`](#update) | Rename a dataset. | | [`upload`](#upload) | Upload a local file as a new dataset or a new version of an existing one. | | [`versions delete`](#versions-delete) | Permanently delete a dataset version. | | [`versions get`](#versions-get) | Show metadata for a single dataset version. | | [`versions list`](#versions-list) | List versions of a dataset, newest first by default. | | [`versions restore`](#versions-restore) | Restore a dataset to a prior version by creating a new version with its content. | *** ## ANALYSIS DOWNLOAD Download a completed analysis's artifacts to local disk. ```bash theme={null} oumi-cli datasets analysis download [OPTIONS] {dataset_id} {analysis_id} ``` **Arguments** | Argument | Type | Required | Description | | ------------- | ---- | -------- | --------------------------------------------------------------- | | `DATASET_ID` | int | ✓ | ID of the dataset that owns the analysis (see `datasets list`). | | `ANALYSIS_ID` | int | ✓ | ID of the analysis to download (see `datasets analysis list`). | **Options** | Option | Type | Required | Description | | -------------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------------- | | `--project` | str | | Project that owns the dataset; falls back to OUMI\_PROJECT\_ID or the active profile. | | `--format` | choice | | Artifact format to download. Default: `jsonl`. | | `--out` | path | | Destination file or directory. Defaults to ./analysis-\-\.\ in the current directory. | | `--expiration` | int range | | Lifetime of the download's presigned URL, in seconds (default 3600, max 604800). | *** ## ANALYSIS LIST List completed quality analyses for a dataset. ```bash theme={null} oumi-cli datasets analysis list [OPTIONS] {dataset_id} ``` **Arguments** | Argument | Type | Required | Description | | ------------ | ---- | -------- | --------------------------------------------------------------- | | `DATASET_ID` | int | ✓ | ID of the dataset whose analyses to list (see `datasets list`). | **Options** | Option | Type | Required | Description | | ------------------- | --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--project` | str | | Project that owns the dataset; falls back to OUMI\_PROJECT\_ID or the active profile. | | `--dataset-version` | int | | Filter to analyses of this dataset version. Omit to see analyses across every version. (Named `--dataset-version` to avoid colliding with the global `--version` flag.) | | `--limit` | int range | | Return at most N analyses (default 100). The CLI fetches and loops over pages internally; you never pass a page token. | | `--all` | flag | | Return every completed analysis, looping until the cursor is exhausted (bounded by `--max-items`). Mutually exclusive with `--limit`. | | `--max-items` | int range | | Hard safety cap for `--all` (default 10000). | *** ## DELETE Permanently delete a dataset from the project. ```bash theme={null} oumi-cli datasets delete [OPTIONS] {dataset_id} ``` **Arguments** | Argument | Type | Required | Description | | ------------ | ---- | -------- | -------------------------------------------------- | | `DATASET_ID` | int | ✓ | ID of the dataset to delete (see `datasets list`). | **Options** | Option | Type | Required | Description | | ----------- | ---- | -------- | ------------------------------------------------------------------------------------- | | `--project` | str | | Project that owns the dataset; falls back to OUMI\_PROJECT\_ID or the active profile. | | `--force` | flag | | Skip the confirmation prompt (alias for `--yes`). | | `--yes` | flag | | Skip the confirmation prompt; useful in scripts. | *** ## DISTILL Distill a dataset by generating completions from a model, waiting for it to finish. ```bash theme={null} oumi-cli datasets distill [OPTIONS] ``` **Options** | Option | Type | Required | Description | | ---------------------- | ---- | -------- | ------------------------------------------------------------------------------------------------------------------------- | | `--project` | str | | Project to distill in; falls back to OUMI\_PROJECT\_ID or the active profile. | | `--input-json` | str | | Request body (DistillDatasetRequest) as an inline JSON string. Pass exactly one of `--input-json` or `--input-json-file`. | | `--input-json-file` | path | | Path to a file holding the request body as JSON. Pass exactly one of `--input-json` or `--input-json-file`. | | `--wait` / `--no-wait` | flag | | Wait for the distillation to finish (default); `--no-wait` returns the operation ID immediately. | *** ## DOWNLOAD Download a dataset version to local disk. ```bash theme={null} oumi-cli datasets download [OPTIONS] {dataset_id} ``` **Arguments** | Argument | Type | Required | Description | | ------------ | ---- | -------- | ---------------------------------------------------- | | `DATASET_ID` | int | ✓ | ID of the dataset to download (see `datasets list`). | **Options** | Option | Type | Required | Description | | ------------------- | ---- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `--project` | str | | Project that owns the dataset; falls back to OUMI\_PROJECT\_ID or the active profile. | | `--dataset-version` | int | | Version ID to download. Defaults to the latest version. (Named `--dataset-version` to avoid colliding with the global `--version` flag.) | | `--out` | path | | Destination file or directory. Defaults to ./dataset-\-\.\ in the current directory. | | `--expiration` | int | | Lifetime of the download's presigned URL, in seconds (default 3600). | *** ## GET Show metadata for a single dataset. ```bash theme={null} oumi-cli datasets get [OPTIONS] {dataset_id} ``` **Arguments** | Argument | Type | Required | Description | | ------------ | ---- | -------- | --------------------------------------------------- | | `DATASET_ID` | int | ✓ | ID of the dataset to inspect (see `datasets list`). | **Options** | Option | Type | Required | Description | | ----------- | ---- | -------- | ------------------------------------------------------------------------------------- | | `--project` | str | | Project that owns the dataset; falls back to OUMI\_PROJECT\_ID or the active profile. | *** ## IMPORT-LOGS Import a LangFuse or LangSmith trace export as a new dataset. ```bash theme={null} oumi-cli datasets import-logs [OPTIONS] {file} ``` **Arguments** | Argument | Type | Required | Description | | -------- | ---- | -------- | ------------------------------------------------------------------------------------------------ | | `FILE` | path | ✓ | Path to the local .jsonl trace export (a LangFuse Tracing-tab export or a LangSmith run export). | **Options** | Option | Type | Required | Description | | -------------------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------- | | `--platform` | choice | ✓ | Observability platform the export came from. One of: `langfuse`, `langsmith`. | | `--display-name` | str | ✓ | Display name for the new dataset. | | `--project` | str | | Project to import the dataset into; falls back to OUMI\_PROJECT\_ID or the active profile. | | `--dedupe` / `--no-dedupe` | flag | | Drop prefix-overlap rows where one trace's full conversation is the prior turns of a longer trace in the same export. | | `--wait` / `--no-wait` | flag | | Wait for the dataset ingest to finish (default); `--no-wait` returns the operation ID immediately. | | `--dry-run` | flag | | Validate the file as JSONL and preview its row count locally; makes no API calls and imports nothing. | *** ## ITEMS BULK-DELETE Bulk-delete rows by explicit ID or by analysis-test failures. ```bash theme={null} oumi-cli datasets items bulk-delete [OPTIONS] {dataset_id} ``` **Arguments** | Argument | Type | Required | Description | | ------------ | ---- | -------- | ------------------------------------------------------------ | | `DATASET_ID` | int | ✓ | ID of the dataset to delete rows from (see `datasets list`). | **Options** | Option | Type | Required | Description | | ----------------- | ---- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `--project` | str | | Project that owns the dataset; falls back to OUMI\_PROJECT\_ID or the active profile. | | `--id` | str | | Row ID to delete (repeatable). Mutually exclusive with `--analysis-test`. | | `--analysis-test` | int | | Delete every row flagged by this analysis's failing tests (its test\_affected\_rows artifact). Mutually exclusive with `--id`. | | `--test-id` | str | | Narrow `--analysis-test` to specific test IDs (repeatable); omit to delete rows flagged by every test in the analysis. Requires `--analysis-test`. | | `--force` | flag | | Skip the confirmation prompt (alias for `--yes`). | | `--yes` | flag | | Skip the confirmation prompt; useful in scripts. | *** ## ITEMS GET Show a single row (data item) from a dataset. ```bash theme={null} oumi-cli datasets items get [OPTIONS] {dataset_id} {dataitem_id} ``` **Arguments** | Argument | Type | Required | Description | | ------------- | ---- | -------- | ----------------------------------------------------------- | | `DATASET_ID` | int | ✓ | ID of the dataset the row belongs to (see `datasets list`). | | `DATAITEM_ID` | str | ✓ | ID of the row to inspect (see `items list`). | **Options** | Option | Type | Required | Description | | ------------------- | ---- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--project` | str | | Project that owns the dataset; falls back to OUMI\_PROJECT\_ID or the active profile. | | `--dataset-version` | int | | Specific dataset version to read the row from. Defaults to the latest version. (Named `--dataset-version` to avoid colliding with the global `--version` flag.) | *** ## ITEMS LIST List the rows (data items) in a dataset, optionally filtered. ```bash theme={null} oumi-cli datasets items list [OPTIONS] {dataset_id} ``` **Arguments** | Argument | Type | Required | Description | | ------------ | ---- | -------- | ---------------------------------------------------------- | | `DATASET_ID` | int | ✓ | ID of the dataset to list rows from (see `datasets list`). | **Options** | Option | Type | Required | Description | | ------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--project` | str | | Project that owns the dataset; falls back to OUMI\_PROJECT\_ID or the active profile. | | `--dataset-version` | int | | Specific dataset version to list rows from. Defaults to the latest version. (Named `--dataset-version` to avoid colliding with the global `--version` flag.) | | `--search` | str | | Case-insensitive substring filter applied to each row's content. | | `--random-offset` | flag | | Start from a random offset instead of the beginning, useful for sampling a few rows without `--all`. Ignored when `--search` is set. | | `--limit` | int range | | Return at most N rows (default 100). The CLI fetches and loops over pages internally; you never pass a page token. | | `--all` | flag | | Return every row, looping until the cursor is exhausted (bounded by `--max-items`). Mutually exclusive with `--limit`. | | `--max-items` | int range | | Hard safety cap for `--all` (default 10000). | *** ## LIST List datasets in a project, optionally filtered and sorted. ```bash theme={null} oumi-cli datasets list [OPTIONS] ``` **Options** | Option | Type | Required | Description | | ------------------ | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------- | | `--project` | str | | Project to list datasets in; falls back to OUMI\_PROJECT\_ID or the active profile. | | `--limit` | int range | | Return at most N datasets (default 100). The CLI fetches and loops over pages internally; you never pass a page token. | | `--all` | flag | | Return every dataset, looping until the cursor is exhausted (bounded by `--max-items`). Mutually exclusive with `--limit`. | | `--max-items` | int range | | Hard safety cap for `--all` (default 10000). | | `--search` | str | | Only show datasets whose name matches this search text. | | `--sort-by` | choice | | Field to sort by. One of: `created_at`, `updated_at`. | | `--sort-direction` | choice | | Sort order (asc is oldest-first). | *** ## SYNTHESIZE Synthesize a new dataset from a recipe, waiting for it to finish. ```bash theme={null} oumi-cli datasets synthesize [OPTIONS] ``` **Options** | Option | Type | Required | Description | | ---------------------- | ---- | -------- | ----------------------------------------------------------------------------------------------------- | | `--recipe`, `-r` | str | ✓ | Recipe ID (integer), or path to a JSON synthesis recipe file whose recipeConfig.type is `synthesize`. | | `--display-name` | str | | Display name for the synthesized dataset. Auto-generated if omitted. | | `--project` | str | | Project to synthesize in; falls back to OUMI\_PROJECT\_ID or the active profile. | | `--wait` / `--no-wait` | flag | | Wait for synthesis to finish (default); `--no-wait` returns the operation ID immediately. | *** ## UPDATE Rename a dataset. ```bash theme={null} oumi-cli datasets update [OPTIONS] {dataset_id} ``` **Arguments** | Argument | Type | Required | Description | | ------------ | ---- | -------- | -------------------------------------------------- | | `DATASET_ID` | int | ✓ | ID of the dataset to update (see `datasets list`). | **Options** | Option | Type | Required | Description | | ---------------- | ---- | -------- | ------------------------------------------------------------------------------------- | | `--project` | str | | Project that owns the dataset; falls back to OUMI\_PROJECT\_ID or the active profile. | | `--display-name` | str | | New display name for the dataset. | *** ## UPLOAD Upload a local file as a new dataset or a new version of an existing one. ```bash theme={null} oumi-cli datasets upload [OPTIONS] {file} ``` **Arguments** | Argument | Type | Required | Description | | -------- | ---- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `FILE` | path | ✓ | Path to the local dataset file to upload. Expected format: JSONL (one JSON object per line, max 5 GB). Each row is classified server-side as 'conversation' (a top-level messages list of objects each carrying a role key) or generic 'dict' (arbitrary JSON keys). Check the result with `oumi-cli datasets get`. Use `--dry-run` to preview the detected shape locally first. For 'dict' rows, which key is input vs. label is declared by the consuming evaluator/synthesis config, not the file itself. See `evaluators generate-template` for the field names a given evaluator type expects. | **Options** | Option | Type | Required | Description | | ---------------------- | ---- | -------- | ---------------------------------------------------------------------------------------------------------------------- | | `--project` | str | | Project to upload the dataset into; falls back to OUMI\_PROJECT\_ID or the active profile. | | `--dataset-id` | int | | Upload as a new version of this existing dataset. Omit to create a brand-new dataset. | | `--display-name` | str | | Display name for the dataset. Defaults to the local filename. | | `--expiration` | int | | Lifetime of the upload's presigned URL, in seconds (default 3600). | | `--wait` / `--no-wait` | flag | | Wait for the dataset ingest to finish (default); `--no-wait` returns the operation ID immediately. | | `--dry-run` | flag | | Validate the file as JSONL and preview its row count and detected schema type; makes no API calls and uploads nothing. | *** ## VERSIONS DELETE Permanently delete a dataset version. ```bash theme={null} oumi-cli datasets versions delete [OPTIONS] {dataset_id} {version_id} ``` **Arguments** | Argument | Type | Required | Description | | ------------ | ---- | -------- | ----------------------------------------------------------- | | `DATASET_ID` | int | ✓ | ID of the dataset (see `datasets list`). | | `VERSION_ID` | int | ✓ | ID of the version to delete (see `datasets versions list`). | **Options** | Option | Type | Required | Description | | ----------- | ---- | -------- | --------------------------------------------------------------------------------------------- | | `--project` | str | | Project that owns the dataset; falls back to OUMI\_PROJECT\_ID or the active profile. | | `--force` | flag | | Skip the confirmation prompt (alias for `--yes`). | | `--yes` | flag | | Skip the confirmation prompt; useful in scripts. Cannot delete the only version of a dataset. | *** ## VERSIONS GET Show metadata for a single dataset version. ```bash theme={null} oumi-cli datasets versions get [OPTIONS] {dataset_id} {version_id} ``` **Arguments** | Argument | Type | Required | Description | | ------------ | ---- | -------- | ------------------------------------------------------------ | | `DATASET_ID` | int | ✓ | ID of the dataset (see `datasets list`). | | `VERSION_ID` | int | ✓ | ID of the version to inspect (see `datasets versions list`). | **Options** | Option | Type | Required | Description | | ----------- | ---- | -------- | ------------------------------------------------------------------------------------- | | `--project` | str | | Project that owns the dataset; falls back to OUMI\_PROJECT\_ID or the active profile. | *** ## VERSIONS LIST List versions of a dataset, newest first by default. ```bash theme={null} oumi-cli datasets versions list [OPTIONS] {dataset_id} ``` **Arguments** | Argument | Type | Required | Description | | ------------ | ---- | -------- | --------------------------------------------------------------- | | `DATASET_ID` | int | ✓ | ID of the dataset whose versions to list (see `datasets list`). | **Options** | Option | Type | Required | Description | | ------------------ | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------- | | `--project` | str | | Project that owns the dataset; falls back to OUMI\_PROJECT\_ID or the active profile. | | `--limit` | int range | | Return at most N versions (default 100). The CLI fetches and loops over pages internally; you never pass a page token. | | `--all` | flag | | Return every version, looping until the cursor is exhausted (bounded by `--max-items`). Mutually exclusive with `--limit`. | | `--max-items` | int range | | Hard safety cap for `--all` (default 10000). | | `--sort-by` | choice | | Field to sort by. One of: `created_at`, `updated_at`, `version_id`. | | `--sort-direction` | choice | | Sort order (asc is oldest-first). | *** ## VERSIONS RESTORE Restore a dataset to a prior version by creating a new version with its content. ```bash theme={null} oumi-cli datasets versions restore [OPTIONS] {dataset_id} {version_id} ``` **Arguments** | Argument | Type | Required | Description | | ------------ | ---- | -------- | --------------------------------------------------------------- | | `DATASET_ID` | int | ✓ | ID of the dataset (see `datasets list`). | | `VERSION_ID` | int | ✓ | ID of the version to restore to (see `datasets versions list`). | **Options** | Option | Type | Required | Description | | ---------------- | ---- | -------- | ------------------------------------------------------------------------------------- | | `--project` | str | | Project that owns the dataset; falls back to OUMI\_PROJECT\_ID or the active profile. | | `--display-name` | str | | Display name for the new version. Defaults to 'Restore to v\'. | | `--description` | str | | Description for the new version. | ***