> 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 file

> All 11 mammoth file commands with examples, arguments and confirmation flags.

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

Upload files (file upload; a whole local directory: file upload-folder) and manage uploaded source files. An uploaded file becomes a dataset: delete it with 'dataset delete'. 11 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 |
|---|---|---|---|
| [`file bulk-delete`](#mammoth-file-bulk-delete) | Permanently delete several files by id. Prompt or '--yes' required. | Destructive | `--yes` or prompt |
| [`file delete`](#mammoth-file-delete) | Permanently delete one file by id. Prompt or '--yes' required. | Destructive | `--yes` or prompt |
| [`file extract-sheets`](#mammoth-file-extract-sheets) | Extract named sheets from a file. File id is positional. | Benign mutation | — |
| [`file get`](#mammoth-file-get) | Get one file by id. | Read | — |
| [`file list`](#mammoth-file-list) | List files, optionally filtered and paginated. | Read | — |
| [`file multi-sheet-extract`](#mammoth-file-multi-sheet-extract) | Create datasets from accepted sheet reads of a multi-sheet file. File id is positional. | Benign mutation | — |
| [`file multi-sheet-preview`](#mammoth-file-multi-sheet-preview) | Preview how one sheet of a multi-sheet file reads. File id is positional. | Benign mutation | — |
| [`file set-password`](#mammoth-file-set-password) | Set a file's password. High-impact: requires '--yes --confirm FILE_ID'. | High impact | `--yes --confirm TARGET` |
| [`file update`](#mammoth-file-update) | Apply a patch request to one file. File id is positional. | Benign mutation | — |
| [`file upload`](#mammoth-file-upload) | Upload local files: one path as the argument, several via the 'files' input field. | Benign mutation | — |
| [`file upload-folder`](#mammoth-file-upload-folder) | Upload every file in a local folder. Folder path is positional or 'folder_path'. | Benign mutation | — |

## file commands

### mammoth file bulk-delete

Permanently delete several files by id. Prompt or '--yes' required.

```bash
mammoth file bulk-delete --input '{"file_ids": [1]}' --yes
```

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

- **Effect:** Destructive, scope `project` · **Confirmation:** `--yes`, or answer the prompt at an interactive terminal
- **Preconditions:** Deletes every listed uploaded file for good and cannot be undone. List them first (`file list`). Needs a prompt or --yes.
- **Id:** `file.bulk-delete` · **Result:** `FileBulkDeleteResult` · **Backed by:** SDK `mammoth.api.files.FilesAPI.bulk_delete`, API `DELETE /workspaces/{workspace_id}/projects/{project_id}/files` (DeleteFiles)

### mammoth file delete

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

```bash
mammoth file delete 123 --yes
```

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

- **Effect:** Destructive, scope `project` · **Confirmation:** `--yes`, or answer the prompt at an interactive terminal
- **Preconditions:** Canonical file delete FILE_ID... accepts one or more IDs; resolve every ID before confirmation.
- **Id:** `file.delete` · **Result:** `FileDeleteResult` · **Backed by:** SDK `mammoth.api.files.FilesAPI.delete`, API `DELETE /workspaces/{workspace_id}/projects/{project_id}/files/{file_id}` (DeleteFile)

### mammoth file extract-sheets

Extract named sheets from a file. File id is positional.

```bash
mammoth file extract-sheets 123 --input '{"sheets": ["Sheet1"]}'
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `FILE_ID` | positional | yes | — | `int` | ID of the file. |
| `sheets` | `--input` field | yes | — | `list[str]` |  |
| `delete_file_after_extract` | `--input` field | no | `true` | `bool` |  |
| `combine_after_extract` | `--input` field | no | `false` | `bool` |  |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** none · **Waits:** waits for the job to finish (`--job-timeout`, `--return-running`)
- **Preconditions:** Requires unique nonempty sheet names. Live upload permission is currently blocked.
- **Id:** `file.extract-sheets` · **Result:** `FileExtractSheetsResult`

### mammoth file get

Get one file by id.

```bash
mammoth file get 123
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `FILE_ID` | positional | yes | — | `int` | ID of the file. |
| `fields` | `--input` field | no | — | `str` |  |

- **Effect:** Read, scope `project` · **Confirmation:** none
- **Preconditions:** Required inputs: FILE_ID.
- **Id:** `file.get` · **Result:** `FileGetResult` · **Backed by:** SDK `mammoth.api.files.FilesAPI.get`, API `GET /workspaces/{workspace_id}/projects/{project_id}/files/{file_id}` (GetFileDetails)

### mammoth file list

List files, optionally filtered and paginated.

```bash
mammoth file list
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `fields` | `--input` field | no | — | `str` |  |
| `file_ids` | `--input` field | no | — | `list[int]` |  |
| `names` | `--input` field | no | — | `list[str]` |  |
| `statuses` | `--input` field | no | — | `list[str]` |  |
| `created_at` | `--input` field | no | — | `str` |  |
| `updated_at` | `--input` field | no | — | `str` |  |
| `limit` | `--input` field | no | `50` | `int` |  |
| `offset` | `--input` field | no | `0` | `int` |  |
| `sort` | `--input` field | no | — | `str` |  |

- **Effect:** Read, scope `project` · **Confirmation:** none · **Pages:** `offset`
- **Id:** `file.list` · **Result:** `FileListResult` · **Backed by:** SDK `mammoth.api.files.FilesAPI.list`, API `GET /workspaces/{workspace_id}/projects/{project_id}/files` (ListFiles)

### mammoth file multi-sheet-extract

Create datasets from accepted sheet reads of a multi-sheet file. File id is positional.

```bash
mammoth file multi-sheet-extract 123 --input '{"tables": [{"name": "Status"}]}'
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `FILE_ID` | positional | yes | — | `int` | ID of the file. |
| `tables` | `--input` field | yes | — | `list[dict[str, any]]` |  |
| `delete_file_after_extract` | `--input` field | no | `true` | `bool` |  |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** none · **Waits:** waits for the job to finish (`--job-timeout`, `--return-running`)
- **Preconditions:** Input: {tables: \[{sheet_name, dataset_name, structure_map, block_id?, combine_group_id?, source_label?, sheet_block_count?}\] (1 to 100 accepted reads from file multi-sheet-preview), delete_file_after_extract?}. The file is deleted after extraction unless delete_file_after_extract is false.
- **Id:** `file.multi-sheet-extract` · **Result:** `FileMultiSheetExtractResult` · **Backed by:** SDK `mammoth.api.files.FilesAPI.create_datasets_from_multi_sheet`, API `POST /workspaces/{workspace_id}/projects/{project_id}/files/{file_id}/multi-sheet-extraction` (CreateDatasetsFromMultiSheetFile)

### mammoth file multi-sheet-preview

Preview how one sheet of a multi-sheet file reads. File id is positional.

```bash
mammoth file multi-sheet-preview 123 --input '{"sheet_name": "Revenue report"}'
```

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

- **Effect:** Benign mutation, scope `project` · **Confirmation:** none
- **Preconditions:** Input: {sheet_name (required), block_id?, user_instruction?, structure_map?}. Shows how one sheet reads before any dataset exists; nothing is saved.
- **Id:** `file.multi-sheet-preview` · **Result:** `FileMultiSheetPreviewResult` · **Backed by:** SDK `mammoth.api.files.FilesAPI.preview_multi_sheet`, API `POST /workspaces/{workspace_id}/projects/{project_id}/files/{file_id}/sheets/interpretation/preview` (PreviewMultiSheetInterpretation)

### mammoth file set-password

Set a file's password. High-impact: requires '--yes --confirm FILE_ID'.

```bash
mammoth file set-password 123 --input /private/path/request.json --yes --confirm 123
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `FILE_ID` | positional | yes | — | `int` | ID of the file. |
| `password` | `--input` field | yes | — | `str` |  |

- **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) · **Waits:** waits for the job to finish (`--job-timeout`, `--return-running`)
- **Preconditions:** Unlocks a password-protected file: ask the user for the file's password and pass it in --input; never ask for an unlocked copy. The password is secret and never a normal flag.
- **Id:** `file.set-password` · **Result:** `FileSetPasswordResult`

### mammoth file update

Apply a patch request to one file. File id is positional.

```bash
mammoth file update 123 --input '{"patch_request": {"patch": [{"op": "replace", "path": "extract_sheets", "value": "Sheet1"}]}}'
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `FILE_ID` | positional | yes | — | `int` | ID of the file. |
| `patch_request` | `--input` field | yes | — | `FilePatchRequest` |  |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** none · **Waits:** waits for the job to finish (`--job-timeout`, `--return-running`)
- **Preconditions:** Existing method waits but returns the pre-wait response; must return stable final state. Path extract_pdf_tables takes a typed value (filename, extraction_method tables_only, all_content or custom, optional user_instruction with instruction and instruction_type, preview_page, extract_full_document, delete_file_after_extract) - the extraction setting a dataset's saved recipe replays for PDFs an automation receives.
- **Id:** `file.update` · **Result:** `FileUpdateResult` · **Backed by:** SDK `mammoth.api.files.FilesAPI.update`, API `PATCH /workspaces/{workspace_id}/projects/{project_id}/files/{file_id}` (UpdateFileConfigs)

### mammoth file upload

Upload local files: one path as the argument, several via the 'files' input field.

```bash
mammoth file upload ./sales.csv
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `FILES` | positional | no | — | `str` | Path to a local file to upload; or pass one or more via the 'files' field. Or the `files` input field. |
| `files` | `--input` field | no | — | `list[str \| Path \| BinaryIO] \| str \| Path \| BinaryIO \| None` |  |
| `folder_resource_id` | `--input` field | no | — | `str \| int \| None` |  |
| `append_to_ds_id` | `--input` field | no | — | `int` |  |
| `override_target_schema` | `--input` field | no | — | `bool` |  |
| `wait_for_completion` | `--input` field | no | `true` | `bool` |  |
| `timeout` | `--input` field | no | `300` | `int` |  |
| `mode` | `--input` field | no | — | `str` |  |
| `sheets` | `--input` field | no | — | `list[str]` |  |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** none · **Waits:** starts a job; waits or returns it depending on input
- **Preconditions:** Accepted extensions: csv tsv psv txt xls xlsx xml pdf tiff jpeg jpg png heic webp and archives zip gz bz2 tar 7z (not json). Request size is capped by the ingress in front of the API: a 60 MB upload is refused with HTTP 413 (invalid_argument) before the API sees it; 16 MB is accepted (measured on release 2026-09-19; the cap between them is not pinned down). Keep one upload well under 16 MB: split larger files or upload a zip/gz. Parsing is asynchronous; use --timeout 300 for files past a few MB and poll the returned job on timeout. Upload authorization is tenant- and scope-specific; a permission failure does not make this route universally unavailable. On success retain returned IDs, read them back, and verify owned cleanup; do not assume other upload variants are qualified. Each sheet of an Excel file becomes its own dataset. The input field mode (replace or add) sets the update method of the dataset the file is appended to: it needs append_to_ds_id and cannot be combined with wait_for_completion false (both are usage errors). An upload into a dataset whose columns do not match is not appended: the command fails with code schema_mismatch, rows_added 0 and kept_dataset_ids (the file's own dataset stays in the project as a separate dataset; delete it or fix the file and upload again). The input field override_target_schema (make the file's columns the dataset's) is honoured by the server only when the dataset's update method is replace, which deletes the rows it holds: the CLI refuses it under any other method before sending the file, and without append_to_ds_id or with wait_for_completion false.
- **Id:** `file.upload` · **Result:** `FileUploadResult` · **Backed by:** SDK `mammoth.api.files.FilesAPI.upload`, API `POST /workspaces/{workspace_id}/projects/{project_id}/files` (CreateFileDataset)

### mammoth file upload-folder

Upload every file in a local folder. Folder path is positional or 'folder_path'.

```bash
mammoth file upload-folder ./sales.csv
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `FOLDER_PATH` | positional | no | — | `str` | Path to a local folder to upload; or pass it via the 'folder_path' input field. Or the `folder_path` input field. |
| `folder_path` | `--input` field | no | — | `str \| Path` |  |
| `folder_resource_id` | `--input` field | no | — | `str` |  |
| `wait_for_completion` | `--input` field | no | `true` | `bool` |  |
| `timeout` | `--input` field | no | `300` | `int` |  |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** none · **Waits:** starts a job; waits or returns it depending on input
- **Preconditions:** Nonrecursive; rejects an empty folder. Live upload permission is currently blocked.
- **Id:** `file.upload-folder` · **Result:** `FileUploadFolderResult`

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