> AI agents: this is one page from Mammoth Analytics documentation. The index of all pages as Markdown is https://mammoth.io/docs/llms.txt. Append `.md` to any docs URL, or send `Accept: text/markdown`, to get Markdown.

# mammoth dataset

> All 37 mammoth dataset commands with examples, arguments and confirmation flags: Create, inspect, and manage datasets.

> Generated from mammoth-cli 2.4.2, released 2026-11-02: `mammoth schema list`, `mammoth capability list` and the CLI's own `--help`. Do not edit by hand; run `npm run docs:capabilities`.

Create, inspect, and manage datasets. 37 commands.

Every command also takes the [global flags](https://mammoth.io/docs/build/cli/global-flags/) (`--output`, `--yes`, `--confirm`, `--dry-run`, `--input`, `--profile`, ...), which are not repeated below. `--input` takes a JSON or YAML document of the input fields; `mammoth schema get COMMAND_ID` prints a command's full input schema.

**Confirmation.** Commands marked `--yes --confirm TARGET` or `--yes` always need those flags, even at a terminal: they never prompt. Commands marked "`--yes` or prompt" ask at an interactive terminal (table output, no `--no-input`) and otherwise need `--yes`. `--dry-run` skips confirmation and sends nothing.

## Summary

| Command | What it does | Effect | Confirmation |
|---|---|---|---|
| [`dataset batch-data`](#mammoth-dataset-batch-data) | Fetch data for a specific dataset batch. | Read | — |
| [`dataset bulk-delete`](#mammoth-dataset-bulk-delete) | Permanently delete the listed datasets. 'dataset_ids' from '--input'; '--yes' required. | Destructive | `--yes` or prompt |
| [`dataset bulk-update`](#mammoth-dataset-bulk-update) | Apply a bulk patch across the active project's datasets. High-impact. | High impact | `--yes --confirm TARGET` |
| [`dataset column-stats`](#mammoth-dataset-column-stats) | Every column's blanks, type and distinct count for each dataset in the project. | Read | — |
| [`dataset create`](#mammoth-dataset-create) | Create a dataset (web URL, clone, or import from a connection such as SFTP). | Benign mutation | — |
| [`dataset create-from-pdf`](#mammoth-dataset-create-from-pdf) | Create dataset(s) from tables extracted out of a PDF file. | Benign mutation | — |
| [`dataset data`](#mammoth-dataset-data) | Fetch a dataset's data, waiting for the backing job to complete. | Read | — |
| [`dataset delete`](#mammoth-dataset-delete) | Permanently delete one dataset by id. Prompt or '--yes' required. | Destructive | `--yes` or prompt |
| [`dataset download`](#mammoth-dataset-download) | Download several datasets, views and folders as one csv, zip of csvs or xlsx file. | Benign mutation | — |
| [`dataset download-plan`](#mammoth-dataset-download-plan) | Say what downloading several datasets, views and folders would hold. | Read | — |
| [`dataset find`](#mammoth-dataset-find) | Search dataset names for a substring across every visible project. | Read | — |
| [`dataset get`](#mammoth-dataset-get) | Get one dataset by id in the active project. | Read | — |
| [`dataset list`](#mammoth-dataset-list) | List datasets in the active project, newest first, each with what tells them apart. | Read | — |
| [`dataset refresh`](#mammoth-dataset-refresh) | Fetch a URL dataset's link again into the same dataset. Prompt or '--yes' required. | Benign mutation | `--yes` or prompt |
| [`dataset rename`](#mammoth-dataset-rename) | Rename a dataset. Dataset id is positional; new name comes from '--input'. | Benign mutation | — |
| [`dataset restore`](#mammoth-dataset-restore) | Restore a trashed dataset. | Benign mutation | — |
| [`dataset schema-diff`](#mammoth-dataset-schema-diff) | Compare two datasets' columns and propose the 'batch create' mapping. | Read | — |
| [`dataset search`](#mammoth-dataset-search) | Find the project's datasets whose name, column names or sampled values hold TERM. | Read | — |
| [`dataset trash`](#mammoth-dataset-trash) | Move one dataset to the project trash (reversible). | Benign mutation | — |
| [`dataset update`](#mammoth-dataset-update) | Reject untyped dataset patches; use a typed dataset command instead. | High impact | `--yes --confirm TARGET` |
| [`dataset broken-rows list`](#mammoth-dataset-broken-rows-list) | List the lines of a dataset's uploaded file that could not be parsed. | Read | — |
| [`dataset broken-rows resolve`](#mammoth-dataset-broken-rows-resolve) | Add corrected set-aside lines to a dataset, or discard them. Prompt or '--yes'. | Destructive | `--yes` or prompt |
| [`dataset definition add`](#mammoth-dataset-definition-add) | Save what a term means for a dataset ('term' and 'definition' from '--input'). | Benign mutation | `--yes --confirm TARGET` |
| [`dataset definition list`](#mammoth-dataset-definition-list) | List what terms mean for one dataset, as its users saved them. | Read | — |
| [`dataset definition remove`](#mammoth-dataset-definition-remove) | Remove one definition from a dataset by its id. Prompt or '--yes' required. | Benign mutation | `--yes` or prompt |
| [`dataset file-settings get`](#mammoth-dataset-file-settings-get) | Get file settings (delimiter, header, dates, ...) for a dataset. | Read | — |
| [`dataset file-settings undo`](#mammoth-dataset-file-settings-undo) | Undo the last file settings change for a dataset. Prompt or '--yes' required. | Destructive | `--yes` or prompt |
| [`dataset file-settings update`](#mammoth-dataset-file-settings-update) | Update a dataset's file settings from '--input'. | Benign mutation | — |
| [`dataset from-url follow`](#mammoth-dataset-from-url-follow) | Make a dataset made from a link follow it again, or turn it into a copy. | Benign mutation | — |
| [`dataset from-url links`](#mammoth-dataset-from-url-links) | Show which of the project's datasets follow a link, with their last fetch. | Read | — |
| [`dataset from-url preview`](#mammoth-dataset-from-url-preview) | Read the CSV, Excel or JSON file at a link and show its tables, keeping nothing. | Read | — |
| [`dataset interpretation confirm`](#mammoth-dataset-interpretation-confirm) | Preview or confirm how a file that can be read several ways is interpreted. | Benign mutation | — |
| [`dataset interpretation preview`](#mammoth-dataset-interpretation-preview) | Preview or confirm how a file that can be read several ways is interpreted. | Benign mutation | — |
| [`dataset tool-claim get`](#mammoth-dataset-tool-claim-get) | Say what an emailed Open tables link opens. | Read | — |
| [`dataset tool-claim redeem`](#mammoth-dataset-tool-claim-redeem) | Add the tables of an emailed Open tables link to a project, in a new folder. | Benign mutation | — |
| [`dataset update-method get`](#mammoth-dataset-update-method-get) | Say whether a new file replaces this dataset's rows or adds to them. | Read | — |
| [`dataset update-method set`](#mammoth-dataset-update-method-set) | Set whether a new file replaces this dataset's rows ('replace') or adds to them. | Benign mutation | — |

## dataset commands

### mammoth dataset batch-data

Fetch data for a specific dataset batch.

```bash
mammoth dataset batch-data 123 456
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `DATASET_ID` | positional | yes | — | `int` | ID of the dataset. |
| `BATCH_ID` | positional | yes | — | `int` | ID of the batch. |
| `columns` | `--input` field | no | — | `str \| list[str] \| None` |  |
| `limit` | `--input` field | no | `50` | `int` |  |
| `offset` | `--input` field | no | `0` | `int` |  |
| `timeout` | `--input` field | no | — | `int` |  |
| `poll_interval` | `--input` field | no | — | `float` |  |

- **Effect:** Read, scope `project` · **Confirmation:** none · **Pages:** `offset`
- **Preconditions:** Dataset and batch parent are explicit; limit is 0..100 and offset is non-negative.
- **Id:** `dataset.batch-data` · **Result:** `DatasetBatchDataResult` · **Backed by:** SDK `mammoth.api.datasets.DatasetsAPI.get_batch_data`, API `GET /workspaces/{workspace_id}/projects/{project_id}/datasets/{dataset_id}/batches/{batch_id}/data` (GetBatchData)

### mammoth dataset bulk-delete

Permanently delete the listed datasets. 'dataset_ids' from '--input'; '--yes' required.

```bash
mammoth dataset bulk-delete --input '{"dataset_ids": [456, 457]}' --yes
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `dataset_ids` | `--input` field | no | — | `list[int]` |  |

- **Effect:** Destructive, scope `project` · **Confirmation:** `--yes`, or answer the prompt at an interactive terminal
- **Preconditions:** Deletes every listed dataset for good and cannot be undone. A dataset that another view uses as a lookup or join source is kept, and the result says so. List them first (`dataset list`). Needs a prompt or --yes.
- **Id:** `dataset.bulk-delete` · **Result:** `DatasetBulkDeleteResult` · **Backed by:** SDK `mammoth.api.datasets.DatasetsAPI.bulk_delete`, API `DELETE /workspaces/{workspace_id}/projects/{project_id}/datasets` (DeleteDatasets)

### mammoth dataset bulk-update

Apply a bulk patch across the active project's datasets. High-impact.

```bash
mammoth dataset bulk-update --input '{"patch_data": {"name": "Status"}}' --yes
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `patch_data` | `--input` field | yes | — | `dict[str, any]` |  |

- **Effect:** High impact, scope `project` · **Confirmation:** always `--yes --confirm TARGET`, even at a terminal (TARGET is the exact id or name acted on; the `confirmation_required` error's hint names it)
- **Id:** `dataset.bulk-update` · **Result:** `DatasetBulkUpdateResult` · **Backed by:** SDK `mammoth.api.datasets.DatasetsAPI.bulk_update`, API `PATCH /workspaces/{workspace_id}/projects/{project_id}/datasets` (UpdateDatasets)

### mammoth dataset column-stats

Every column's blanks, type and distinct count for each dataset in the project.

```bash
mammoth dataset column-stats
```

- **Effect:** Read, scope `project` · **Confirmation:** none
- **Preconditions:** Needs a project. Use this instead of profiling each view when the question spans datasets ("missing values", "blanks", "data quality across the project"): one call returns every dataset's columns with their blank count and share, type and distinct count, from stats stored at the last load or pipeline run. Rank columns by blank_pct (or blank_count) and name the worst dataset and column.
- **Id:** `dataset.column-stats` · **Result:** `DatasetColumnStatsResult` · **Backed by:** SDK `mammoth.api.datasets.DatasetsAPI.column_stats`, API `GET /workspaces/{workspace_id}/projects/{project_id}/datasets/column-stats` (GetProjectColumnStats)

### mammoth dataset create

Create a dataset (web URL, clone, or import from a connection such as SFTP).

Allowed values: dataset_spec.query_properties.data_pull_file: 'Pull same file', 'Pull next file based on name pattern'

```bash
mammoth dataset create --input '{"dataset_spec": {"url": "https://sampledata.mammoth.io/Multi-Store_Retail_Sales.csv"}, "ds_creation_type": "weburl"}'
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `dataset_spec` | `--input` field | yes | — | `dict[str, any]` |  |
| `ds_creation_type` | `--input` field | yes | — | `str` |  |
| `folder_resource_id` | `--input` field | no | — | `str` |  |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** none · **Waits:** waits for the job to finish (`--job-timeout`, `--return-running`)
- **Preconditions:** ds_creation_type=weburl (dataset_spec.url), clone, or cloud (a file, REST API or database query from a connection); the command waits for the job and returns the new dataset_id. A weburl dataset keeps its link and can be refreshed on demand (dataset refresh DATASET_ID --yes, or Refresh from URL in the web app; a single CSV only), but never on a schedule: automation's run_data_retrieval task cannot refresh it (only a cloud-connected dataset can be refreshed); for a scheduled pull from a URL use the REST API connector. Say so rather than scheduling a refresh for it. The result's name is the dataset's real name; when the requested name was taken the server adds a suffix, and requested_name and note say so. Use name, not the name you asked for. To copy a dataset as a new independent one: {"ds_creation_type": "clone", "dataset_spec": {"ds_name": NEW_NAME, "source_ds_id": ID, "clone_dataview_ids": \[DEFAULT_VIEW_ID\], "exclude_data": false}}, DEFAULT_VIEW_ID being the id in dataset's `default_view` from view list (other views only when asked); an empty clone_dataview_ids is refused here because it makes a blank view. A clone waits and returns the new dataset_id; never use view export dataset for a plain copy, which leaves a live export on the source. A weburl import names the dataset after the downloaded file: follow it with dataset rename to the name the user picked. To import a file from an SFTP server (or another file connector) as a new dataset: connector connection create sftp, then {"ds_creation_type": "cloud", "dataset_spec": {"connector_key": "sftp", "connection_key": KEY, "query_properties": {"ds_name": NAME, "file_path": PATH_ON_SERVER, "data_pull_file": "Pull same file"}}}. data_pull_file is a string and may be left out, which means "Pull same file" (what the web app does); its only other value is "Pull next file based on name pattern", which also needs folder_path and name_pattern. A pull that finds no file at the path fails the create with the server's reason; the recipe is recipes/file-import.md. To import from a REST API or Elasticsearch: the connection must exist first (connector connection create generic_rest_api, in the same project); try the query with connector ds-config create (data_sample, creates no dataset; connector connection query takes SQL only and refuses a REST config); then {"ds_creation_type": "cloud", "dataset_spec": {"connector_key": "generic_rest_api", "connection_key": KEY, "query_properties": {"ds_name": NAME, "table_name": TABLE, "query": "\<JSON string of the endpoint config\>"}, "schedule_properties": {"schedule_type": "moment", "first_pull_at": "now", "on_refresh_action": "replace"}, "recurrence_info": {"interval": 1, "start_at": "\<future ISO time\>"}}}. schedule_properties and recurrence_info are required (without them the job fails with Invalid parameters); on_refresh_action combine appends every refresh, so rows duplicate. The recipe is recipes/rest-api-import.md. To make a dataset from a database query (SQL Server, MySQL, Postgres, ...): connector connection create for the database, try the SELECT with connector connection query (read-only, saves nothing), then connector ds-config create CONNECTOR_KEY CONNECTION_KEY with {"query": SELECT, "table": NAME}; the recipe is recipes/database-import.md. Other ds_creation_type values and dataset_spec shapes: variants beyond the documented path are not qualified.
- **Id:** `dataset.create` · **Result:** `DatasetCreateResult` · **Backed by:** SDK `mammoth.api.datasets.DatasetsAPI.create`, API `POST /workspaces/{workspace_id}/projects/{project_id}/datasets` (CreateDatasets)

### mammoth dataset create-from-pdf

Create dataset(s) from tables extracted out of a PDF file.

```bash
mammoth dataset create-from-pdf 123 --input '{"file_name": "./sales.csv"}'
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `FILE_OBJECT_ID` | positional | yes | — | `int` | ID of the file object. |
| `file_name` | `--input` field | yes | — | `str` |  |
| `file_id` | `--input` field | no | — | `str` |  |
| `table_list` | `--input` field | no | — | `list[int]` |  |
| `delete_file_after_extract` | `--input` field | no | `false` | `bool` |  |
| `is_preview_needed` | `--input` field | no | — | `bool` |  |
| `user_instruction` | `--input` field | no | — | `str` |  |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** none
- **Preconditions:** Add table_list (table indices to extract) to the input: {"file_name": "report.pdf", "table_list": \[0\]}. The API refuses a call with no table_list. user_instruction cannot be combined with table_list.
- **Id:** `dataset.create-from-pdf` · **Result:** `DatasetCreateFromPdfResult` · **Backed by:** SDK `mammoth.api.datasets.DatasetsAPI.create_from_pdf`, API `POST /workspaces/{workspace_id}/projects/{project_id}/datasets-from-pdf` (CreateDatasetFromPdf)

### mammoth dataset data

Fetch a dataset's data, waiting for the backing job to complete.

```bash
mammoth dataset data 123
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `DATASET_ID` | positional | yes | — | `int` | ID of the dataset. |
| `timeout` | `--input` field | no | `300` | `int` |  |
| `poll_interval` | `--input` field | no | — | `float` |  |

- **Effect:** Read, scope `project` · **Confirmation:** none · **Waits:** waits for the job to finish (`--job-timeout`, `--return-running`)
- **Preconditions:** Required inputs: DATASET_ID.
- **Id:** `dataset.data` · **Result:** `DatasetDataResult` · **Backed by:** SDK `mammoth.api.datasets.DatasetsAPI.get_data`, API `GET /workspaces/{workspace_id}/projects/{project_id}/datasets/{dataset_id}/data` (GetDatasetData)

### mammoth dataset delete

Permanently delete one dataset by id. Prompt or '--yes' required.

```bash
mammoth dataset delete 123 --yes
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `DATASET_ID` | positional | yes | — | `int` | ID of the dataset. |

- **Effect:** Destructive, scope `project` · **Confirmation:** `--yes`, or answer the prompt at an interactive terminal
- **Preconditions:** Immutable dataset-ID confirmation.
- **Id:** `dataset.delete` · **Result:** `DatasetDeleteResult` · **Backed by:** SDK `mammoth.api.datasets.DatasetsAPI.delete`, API `DELETE /workspaces/{workspace_id}/projects/{project_id}/datasets/{dataset_id}` (DeleteDataset)

### mammoth dataset download

Download several datasets, views and folders as one csv, zip of csvs or xlsx file.

```bash
mammoth dataset download --input '{"resource_ids": [12, 13], "name": "sales", "file_type": "csv"}'
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `resource_ids` | `--input` field | yes | — | `list[int]` |  |
| `name` | `--input` field | yes | — | `str` |  |
| `output_path` | `--input` field | no | — | `str \| Path \| None` |  |
| `file_type` | `--input` field | no | `csv` | `Literal['csv', 'xlsx']` | One of `csv`, `xlsx`. |
| `stack` | `--input` field | no | `false` | `bool` |  |
| `numbered` | `--input` field | no | `false` | `bool` |  |
| `views` | `--input` field | no | — | `dict[int, int]` |  |
| `timeout` | `--input` field | no | `300` | `int` |  |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** none · **Waits:** waits for the job to finish (`--job-timeout`, `--return-running`)
- **Preconditions:** Input: resource_ids (dataset, view and folder ids, in file order) and name (the file name without extension) are required; file_type is csv (a zip of CSVs when there are several) or xlsx (one workbook, a sheet per dataset); stack, numbered, views ({dataset id: view id}), output_path and timeout are optional. An existing output file is refused with file_exists unless --overwrite is given. Check the size first with dataset download-plan.
- **Id:** `dataset.download` · **Result:** `DatasetDownloadResult`

### mammoth dataset download-plan

Say what downloading several datasets, views and folders would hold.

```bash
mammoth dataset download-plan --input '{"resource_ids": [12, 13]}'
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `resource_ids` | `--input` field | yes | — | `list[int]` |  |
| `views` | `--input` field | no | — | `dict[int, int]` |  |

- **Effect:** Read, scope `project` · **Confirmation:** none
- **Preconditions:** Reads headers only: how many datasets a download holds and how many files it is with same-column datasets stacked.
- **Id:** `dataset.download-plan` · **Result:** `DatasetDownloadPlanResult`

### mammoth dataset find

Search dataset names for a substring across every visible project.

```bash
mammoth dataset find sales
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `NAME_SUBSTRING` | positional | no | — | `str` | Case-insensitive substring to match against dataset names; optional when --input gives 'columns'. Matches in other projects are listed too, marked in_project when --project is given. |
| `all_projects` | `--input` field | no | `false` | `bool` |  |

- **Effect:** Read, scope `project` · **Confirmation:** none
- **Id:** `dataset.find` · **Result:** `DatasetFindResult`

### mammoth dataset get

Get one dataset by id in the active project.

```bash
mammoth dataset get 123
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `DATASET_ID` | positional | yes | — | `int` | ID of the dataset. |

- **Effect:** Read, scope `project` · **Confirmation:** none
- **Preconditions:** Required inputs: DATASET_ID.
- **Id:** `dataset.get` · **Result:** `DatasetGetResult` · **Backed by:** SDK `mammoth.api.datasets.DatasetsAPI.get`, API `GET /workspaces/{workspace_id}/projects/{project_id}/datasets/{dataset_id}` (GetDataset)

### mammoth dataset list

List datasets in the active project, newest first, each with what tells them apart.

```bash
mammoth dataset list
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `limit` | `--input` field | no | `100` | `int` |  |
| `offset` | `--input` field | no | `0` | `int` |  |
| `sort` | `--input` field | no | `(created_at:desc)` | `str` |  |
| `ids` | `--input` field | no | — | `list[int]` |  |
| `full` | `--input` field | no | `false` | `bool` |  |
| `name` | `--input` field | no | — | `str` |  |
| `names` | `--input` field | no | `false` | `bool` |  |

- **Effect:** Read, scope `project` · **Confirmation:** none · **Pages:** `single_page`
- **Preconditions:** B01. Newest first. Each item carries rows and cols, created and updated time (updated is left out when it equals created), the source kind (file, connector, created in Mammoth, export of a view), and its column names with types, from the list route's stored stats, sources and data_schema, cut to fit the agent tool output cap: more is true with next_offset when the page was cut. full true returns the raw id and name list. name (input field, a case-insensitive substring) reads every page and returns only the matching datasets as short rows (id, name, rows, cols; no column lists) with matched, and more with next_offset when cut; limit and offset then page over the matches. limit must be at most 100. names true returns up to 500 bare id and name rows of the project in ONE call, newest first, with total and more: use it for a list of names (which files can I see), never page offsets. Without a project use dataset find NAME_SUBSTRING.
- **Id:** `dataset.list` · **Result:** `DatasetListResult` · **Backed by:** SDK `mammoth.api.datasets.DatasetsAPI.list`, API `GET /workspaces/{workspace_id}/projects/{project_id}/datasets` (GetDatasets)

### mammoth dataset refresh

Fetch a URL dataset's link again into the same dataset. Prompt or '--yes' required.

```bash
mammoth dataset refresh 123 --yes
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `DATASET_ID` | positional | yes | — | `int` | ID of the dataset. |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** `--yes`, or answer the prompt at an interactive terminal · **Waits:** waits for the job to finish (`--job-timeout`, `--return-running`)
- **Preconditions:** Fetches the link of a dataset made from a URL (dataset create with ds_creation_type weburl; dataset list shows it as source url with the link host) again into the same dataset, and waits for the job. Whether the new data replaces or adds to the old follows the dataset's own data addition setting. A dataset not made from a URL is refused, and so is a URL that serves JSON; the server's reason is shown. A single CSV only. It never refreshes on a schedule, and automation run_data_retrieval cannot refresh it; for a scheduled pull from a URL use the REST API connector.
- **Id:** `dataset.refresh` · **Result:** `DatasetRefreshResult`

### mammoth dataset rename

Rename a dataset. Dataset id is positional; new name comes from '--input'.

```bash
mammoth dataset rename 123 --input '{"name": "Revenue report"}'
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `DATASET_ID` | positional | yes | — | `int` | ID of the dataset. |
| `name` | `--input` field | yes | — | `str` |  |
| `unique` | `--input` field | no | `false` | `bool` |  |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** none
- **Preconditions:** Convenience alias implemented through DatasetsAPI.update but registered as its own canonical command.
- **Id:** `dataset.rename` · **Result:** `DatasetRenameResult`

### mammoth dataset restore

Restore a trashed dataset.

```bash
mammoth dataset restore 123
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `DATASET_ID` | positional | yes | — | `int` | ID of the dataset. |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** none
- **Preconditions:** Required inputs: DATASET_ID.
- **Id:** `dataset.restore` · **Result:** `DatasetRestoreResult` · **Backed by:** SDK `mammoth.api.datasets.DatasetsAPI.restore`, API `POST /workspaces/{workspace_id}/projects/{project_id}/datasets/{dataset_id}/restore` (RestoreDataset)

### mammoth dataset schema-diff

Compare two datasets' columns and propose the 'batch create' mapping.

```bash
mammoth dataset schema-diff 10 11
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `DESTINATION_ID` | positional | yes | — | `int` | Dataset the rows would be appended into (the DATASET_ID of batch create). |
| `SOURCE_ID` | positional | yes | — | `int` | Dataset whose rows would be appended (the SOURCE_ID of batch create). |

- **Effect:** Read, scope `project` · **Confirmation:** none
- **Preconditions:** Required inputs: DESTINATION_ID, SOURCE_ID.
- **Id:** `dataset.schema-diff` · **Result:** `DatasetSchemaDiffResult`

### mammoth dataset search

Find the project's datasets whose name, column names or sampled values hold TERM.

```bash
mammoth dataset search 'New Year Sale'
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `TERM` | positional | yes | — | `str` | Text to find in dataset names, column names or sampled column values (case-insensitive, at least 2 characters). |

- **Effect:** Read, scope `project` · **Confirmation:** none
- **Preconditions:** Required inputs: TERM.
- **Id:** `dataset.search` · **Result:** `DatasetSearchResult` · **Backed by:** SDK `mammoth.api.datasets.DatasetsAPI.search`, API `GET /workspaces/{workspace_id}/projects/{project_id}/datasets/search` (SearchDatasetsByContent)

### mammoth dataset trash

Move one dataset to the project trash (reversible).

```bash
mammoth dataset trash 123
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `DATASET_ID` | positional | yes | — | `int` | ID of the dataset. |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** none
- **Preconditions:** Required inputs: DATASET_ID.
- **Id:** `dataset.trash` · **Result:** `DatasetTrashResult` · **Backed by:** SDK `mammoth.api.datasets.DatasetsAPI.trash`, API `POST /workspaces/{workspace_id}/projects/{project_id}/datasets/{dataset_id}/trash` (TrashDataset)

### mammoth dataset update

Reject untyped dataset patches; use a typed dataset command instead.

```bash
mammoth dataset update --input '{"patch_data": [{"name": "Status"}]}' --yes
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `patch_data` | `--input` field | yes | — | `list[dict[str, any]]` |  |

- **Effect:** High impact, scope `project` · **Confirmation:** always `--yes --confirm TARGET`, even at a terminal (TARGET is the exact id or name acted on; the `confirmation_required` error's hint names it)
- **Id:** `dataset.update` · **Result:** `DatasetUpdateResult` · **Backed by:** SDK `mammoth.api.datasets.DatasetsAPI.update`, API `PATCH /workspaces/{workspace_id}/projects/{project_id}/datasets/{dataset_id}` (UpdateDataset)

## dataset broken-rows

### mammoth dataset broken-rows list

List the lines of a dataset's uploaded file that could not be parsed.

```bash
mammoth dataset broken-rows list 123
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `DATASET_ID` | positional | yes | — | `int` | ID of the dataset. |

- **Effect:** Read, scope `project` · **Confirmation:** none
- **Preconditions:** Returns the first 100 lines the upload could not parse, each with its line number, upload (batch_id) and why it does not fit the columns; row_count is the total. A dataset not made from a file upload has none.
- **Id:** `dataset.broken-rows.list` · **Result:** `DatasetBrokenRowsListResult` · **Backed by:** SDK `mammoth.api.datasets.DatasetsAPI.get_unstructured_rows`, API `GET /workspaces/{workspace_id}/projects/{project_id}/datasets/{dataset_id}/unstructured_rows` (GetUnstructuredRows)

### mammoth dataset broken-rows resolve

Add corrected set-aside lines to a dataset, or discard them. Prompt or '--yes'.

```bash
mammoth dataset broken-rows resolve 123 --input '{"op": "add", "batch_id": 1, "rows": [{"line_num": 2, "line": "corrected,line,here"}]}' --yes
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `DATASET_ID` | positional | yes | — | `int` | ID of the dataset. |
| `op` | `--input` field | yes | — | `Literal['add', 'remove']` | One of `add`, `remove`. |
| `batch_id` | `--input` field | yes | — | `int` |  |
| `rows` | `--input` field | yes | — | `list[dict[str, any]]` |  |

- **Effect:** Destructive, scope `project` · **Confirmation:** `--yes`, or answer the prompt at an interactive terminal
- **Preconditions:** op "add" takes each corrected line (line_num, batch_id and the original line from dataset broken-rows list, edited so its column count matches) into the dataset; op "remove" discards the lines for good. Returns a job: run job wait on it, then read broken-rows list (row_count 0 and dataset status ready mean it is finished). Confirm with the user first, and say that discarded lines do not come back.
- **Id:** `dataset.broken-rows.resolve` · **Result:** `DatasetBrokenRowsResolveResult` · **Backed by:** SDK `mammoth.api.datasets.DatasetsAPI.resolve_unstructured_rows`, API `PATCH /workspaces/{workspace_id}/projects/{project_id}/datasets/{dataset_id}/unstructured_rows` (PatchUnstructuredRows)

## dataset definition

### mammoth dataset definition add

Save what a term means for a dataset ('term' and 'definition' from '--input').

```bash
mammoth dataset definition add 123 --input '{"term": "late", "definition": "delivered more than 5 days after shipped_date"}' --yes --confirm 123
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `DATASET_ID` | positional | yes | — | `int` | ID of the dataset. |
| `term` | `--input` field | yes | — | `str` |  |
| `definition` | `--input` field | yes | — | `str` |  |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** always `--yes --confirm TARGET`, even at a terminal (TARGET is the exact id or name acted on; the `confirmation_required` error's hint names it)
- **Preconditions:** Saves what a term means for this dataset: term (1-60 characters) and definition (1-300 characters) from --input. A definition is shared by everyone's chats on this dataset, so the user confirms each save. Save one only when the user states what a term means for this data, not to answer a one-off question. Write the definition in terms of the dataset's real column names. A definition for an existing term (any case) replaces it; at most 20 per dataset. The project's definitions already appear in every turn's context, so there is no need to list them before answering.
- **Id:** `dataset.definition.add` · **Result:** `DatasetDefinitionAddResult` · **Backed by:** SDK `mammoth.api.datasets.DatasetsAPI.add_definition`, API `POST /workspaces/{workspace_id}/projects/{project_id}/datasets/{dataset_id}/definitions` (AddDatasetDefinition)

### mammoth dataset definition list

List what terms mean for one dataset, as its users saved them.

```bash
mammoth dataset definition list 123
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `DATASET_ID` | positional | yes | — | `int` | ID of the dataset. |

- **Effect:** Read, scope `project` · **Confirmation:** none
- **Preconditions:** Lists what terms mean for this dataset (id, term, definition), shared by everyone's chats on it. The project's definitions already appear in every turn's context, so there is no need to list them before answering; list them to find the id to remove.
- **Id:** `dataset.definition.list` · **Result:** `DatasetDefinitionListResult` · **Backed by:** SDK `mammoth.api.datasets.DatasetsAPI.list_definitions`, API `GET /workspaces/{workspace_id}/projects/{project_id}/datasets/{dataset_id}/definitions` (GetDatasetDefinitions)

### mammoth dataset definition remove

Remove one definition from a dataset by its id. Prompt or '--yes' required.

```bash
mammoth dataset definition remove 123 a1b2c3d4 --yes
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `DATASET_ID` | positional | yes | — | `int` | ID of the dataset. |
| `DEFINITION_ID` | positional | yes | — | `str` | ID of the definition. |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** `--yes`, or answer the prompt at an interactive terminal
- **Preconditions:** Removes one definition by the id dataset definition list returns; use it when the user asks to drop or forget what a term means for this dataset. Everyone's chats on the dataset stop using it.
- **Id:** `dataset.definition.remove` · **Result:** `DatasetDefinitionRemoveResult` · **Backed by:** SDK `mammoth.api.datasets.DatasetsAPI.remove_definition`, API `DELETE /workspaces/{workspace_id}/projects/{project_id}/datasets/{dataset_id}/definitions/{definition_id}` (RemoveDatasetDefinition)

## dataset file-settings

### mammoth dataset file-settings get

Get file settings (delimiter, header, dates, ...) for a dataset.

```bash
mammoth dataset file-settings get 123
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `DATASET_ID` | positional | yes | — | `int` | ID of the dataset. |

- **Effect:** Read, scope `project` · **Confirmation:** none
- **Preconditions:** Required inputs: DATASET_ID.
- **Id:** `dataset.file-settings.get` · **Result:** `DatasetFileSettingsGetResult` · **Backed by:** SDK `mammoth.api.datasets.DatasetsAPI.get_file_settings`, API `GET /workspaces/{workspace_id}/projects/{project_id}/datasets/{dataset_id}/file_settings` (GetFileSettings)

### mammoth dataset file-settings undo

Undo the last file settings change for a dataset. Prompt or '--yes' required.

```bash
mammoth dataset file-settings undo 123 --yes
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `DATASET_ID` | positional | yes | — | `int` | ID of the dataset. |

- **Effect:** Destructive, scope `project` · **Confirmation:** `--yes`, or answer the prompt at an interactive terminal
- **Preconditions:** Required inputs: DATASET_ID.
- **Id:** `dataset.file-settings.undo` · **Result:** `DatasetFileSettingsUndoResult` · **Backed by:** SDK `mammoth.api.datasets.DatasetsAPI.file_settings_undo`, API `DELETE /workspaces/{workspace_id}/projects/{project_id}/datasets/{dataset_id}/file_settings` (UndoFileSettings)

### mammoth dataset file-settings update

Update a dataset's file settings from '--input'.

```bash
mammoth dataset file-settings update 123 --input '{"initial_skip_count": 2}'
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `DATASET_ID` | positional | yes | — | `int` | ID of the dataset. |
| `delimiter` | `--input` field | no | — | `str` |  |
| `has_header` | `--input` field | no | — | `bool` |  |
| `initial_skip_count` | `--input` field | no | — | `int` |  |
| `quotechar` | `--input` field | no | — | `str` |  |
| `date_format` | `--input` field | no | — | `str` |  |
| `preview_mode` | `--input` field | no | `false` | `bool` |  |
| `skip_auto_process_check` | `--input` field | no | `true` | `bool` |  |
| `date_formats` | `--input` field | no | — | `dict[str, str]` |  |
| `set_project_level_date_format` | `--input` field | no | `false` | `bool` |  |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** none · **Waits:** waits for the job to finish (`--job-timeout`, `--return-running`)
- **Preconditions:** Required inputs: DATASET_ID.
- **Id:** `dataset.file-settings.update` · **Result:** `DatasetFileSettingsUpdateResult` · **Backed by:** SDK `mammoth.api.datasets.DatasetsAPI.file_settings_update`, API `POST /workspaces/{workspace_id}/projects/{project_id}/datasets/{dataset_id}/file_settings` (UpdateFileSettings)

## dataset from-url

### mammoth dataset from-url follow

Make a dataset made from a link follow it again, or turn it into a copy.

```bash
mammoth dataset from-url follow 123 --input '{"follow": false}'
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `DATASET_ID` | positional | yes | — | `int` | ID of the dataset. |
| `follow` | `--input` field | no | `true` | `bool` |  |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** none
- **Preconditions:** Follow true keeps the dataset refreshing from its link; follow false makes it a copy.
- **Id:** `dataset.from-url.follow` · **Result:** `DatasetFromUrlFollowResult`

### mammoth dataset from-url links

Show which of the project's datasets follow a link, with their last fetch.

```bash
mammoth dataset from-url links
```

- **Effect:** Read, scope `project` · **Confirmation:** none
- **Id:** `dataset.from-url.links` · **Result:** `DatasetFromUrlLinksResult`

### mammoth dataset from-url preview

Read the CSV, Excel or JSON file at a link and show its tables, keeping nothing.

```bash
mammoth dataset from-url preview https://example.com/data.csv
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `URL` | positional | yes | — | `str` | URL slug identifying the resource. |

- **Effect:** Read, scope `project` · **Confirmation:** none
- **Preconditions:** Reads the file at the link and keeps nothing; use it before creating a dataset from a URL.
- **Id:** `dataset.from-url.preview` · **Result:** `DatasetFromUrlPreviewResult`

## dataset interpretation

### mammoth dataset interpretation confirm

Preview or confirm how a file that can be read several ways is interpreted.

```bash
mammoth dataset interpretation confirm 123
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `DATASET_ID` | positional | yes | — | `int` | ID of the dataset. |
| `user_instruction` | `--input` field | no | — | `str` |  |
| `structure_map` | `--input` field | no | — | `dict[str, any]` |  |
| `destination_dataset_id` | `--input` field | no | — | `int` |  |
| `mode` | `--input` field | no | — | `str` |  |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** none
- **Preconditions:** Finalizes a dataset whose file has more than one plausible reading (status has_unstructured_data): applies the interpretation to the whole file and creates the table. Run interpretation preview first and pass the same input here, or the structure_map it returned. The suggestions stored on the dataset are under additional_info.interpretation.instruction_suggestions in dataset get. Pass mode "original" (alone: it takes no reshape field) to keep the file in the layout it was uploaded in; later files for the dataset are then ingested the same way, without review. The result state shows the dataset afterwards. Example: --input '{"user_instruction": "Skip preamble rows, row 5 is the header"}'.
- **Id:** `dataset.interpretation.confirm` · **Result:** `DatasetInterpretationConfirmResult` · **Backed by:** SDK `mammoth.api.datasets.DatasetsAPI.interpretation_confirm`, API `PATCH /workspaces/{workspace_id}/projects/{project_id}/datasets/{dataset_id}/interpretation` (ConfirmDatasetInterpretation)

### mammoth dataset interpretation preview

Preview or confirm how a file that can be read several ways is interpreted.

```bash
mammoth dataset interpretation preview 123
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `DATASET_ID` | positional | yes | — | `int` | ID of the dataset. |
| `user_instruction` | `--input` field | no | — | `str` |  |
| `structure_map` | `--input` field | no | — | `dict[str, any]` |  |
| `destination_dataset_id` | `--input` field | no | — | `int` |  |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** none
- **Preconditions:** Shows the rows the dataset would have under an interpretation, without finalizing it: preview_rows (header plus up to 50 rows), total_row_count, structure_map and header_types. --input needs user_instruction (plain English; the suggestions stored on the dataset are in dataset get under additional_info.interpretation.instruction_suggestions), a structure_map from an earlier preview, or destination_dataset_id. Nothing is applied to the file until interpretation confirm. Example: --input '{"user_instruction": "Skip preamble rows, row 5 is the header"}'.
- **Id:** `dataset.interpretation.preview` · **Result:** `DatasetInterpretationPreviewResult` · **Backed by:** SDK `mammoth.api.datasets.DatasetsAPI.interpretation_preview`, API `POST /workspaces/{workspace_id}/projects/{project_id}/datasets/{dataset_id}/interpretation/preview` (PreviewDatasetInterpretation)

## dataset tool-claim

### mammoth dataset tool-claim get

Say what an emailed Open tables link opens.

```bash
mammoth dataset tool-claim get --input '{"token": "replace-with-secret"}'
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `token` | `--input` field | yes | — | `str` |  |

- **Effect:** Read, scope `project` · **Confirmation:** none
- **Id:** `dataset.tool-claim.get` · **Result:** `DatasetToolClaimGetResult` · **Backed by:** SDK `mammoth.api.datasets.DatasetsAPI.tool_claim_get`, API `GET /tool-claims` (GetToolClaim)

### mammoth dataset tool-claim redeem

Add the tables of an emailed Open tables link to a project, in a new folder.

```bash
mammoth dataset tool-claim redeem --input '{"token": "replace-with-secret"}'
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `token` | `--input` field | yes | — | `str` |  |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** none
- **Preconditions:** The link must have been emailed to the signed-in user. Redeeming it again adds nothing and returns where the tables already are.
- **Id:** `dataset.tool-claim.redeem` · **Result:** `DatasetToolClaimRedeemResult` · **Backed by:** SDK `mammoth.api.datasets.DatasetsAPI.tool_claim_redeem`, API `POST /workspaces/{workspace_id}/projects/{project_id}/tool-claims` (RedeemToolClaim)

## dataset update-method

### mammoth dataset update-method get

Say whether a new file replaces this dataset's rows or adds to them.

```bash
mammoth dataset update-method get 123
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `DATASET_ID` | positional | yes | — | `int` | ID of the dataset. |

- **Effect:** Read, scope `project` · **Confirmation:** none
- **Preconditions:** mode "add" means each new file (an upload with append_to_ds_id, or a folder automation) adds its rows to the dataset; "replace" means it takes the place of the rows already there. A dataset with no setting stored adds.
- **Id:** `dataset.update-method.get` · **Result:** `DatasetUpdateMethodGetResult`

### mammoth dataset update-method set

Set whether a new file replaces this dataset's rows ('replace') or adds to them.

```bash
mammoth dataset update-method set 123 --input '{"mode": "replace"}'
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `DATASET_ID` | positional | yes | — | `int` | ID of the dataset. |
| `mode` | `--input` field | yes | — | `str` |  |
| `schema_mapping` | `--input` field | no | — | `dict[str, list[str]]` |  |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** none
- **Preconditions:** mode "replace" or "add". It stays on the dataset: every later upload into it (file upload with append_to_ds_id) and every folder automation feeding it follows it, until it is set again. Optional schema_mapping {"dataset column": \["file column"\]} matches a new file's columns to the dataset's. The other settings for new rows are kept as stored.
- **Id:** `dataset.update-method.set` · **Result:** `DatasetUpdateMethodSetResult`

---
Source: https://mammoth.io/docs/build/cli/dataset.md · Updated: 2026-11-02
