Skip to content
Build with Mammoth › CLI reference: open the docs menu

mammoth file

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

CommandWhat it doesEffectConfirmation
file bulk-deletePermanently delete several files by id. Prompt or '--yes' required.Destructive--yes or prompt
file deletePermanently delete one file by id. Prompt or '--yes' required.Destructive--yes or prompt
file extract-sheetsExtract named sheets from a file. File id is positional.Benign mutation—
file getGet one file by id.Read—
file listList files, optionally filtered and paginated.Read—
file multi-sheet-extractCreate datasets from accepted sheet reads of a multi-sheet file. File id is positional.Benign mutation—
file multi-sheet-previewPreview how one sheet of a multi-sheet file reads. File id is positional.Benign mutation—
file set-passwordSet a file's password. High-impact: requires '--yes --confirm FILE_ID'.High impact--yes --confirm TARGET
file updateApply a patch request to one file. File id is positional.Benign mutation—
file uploadUpload local files: one path as the argument, several via the 'files' input field.Benign mutation—
file upload-folderUpload 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.

mammoth file bulk-delete --input '{"file_ids": [1]}' --yes
NamePassed asRequiredDefaultTypeNotes
file_ids--input fieldyes—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.

mammoth file delete 123 --yes
NamePassed asRequiredDefaultTypeNotes
FILE_IDpositionalyes—intID 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.

mammoth file extract-sheets 123 --input '{"sheets": ["Sheet1"]}'
NamePassed asRequiredDefaultTypeNotes
FILE_IDpositionalyes—intID of the file.
sheets--input fieldyes—list[str]
delete_file_after_extract--input fieldnotruebool
combine_after_extract--input fieldnofalsebool
  • 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.

mammoth file get 123
NamePassed asRequiredDefaultTypeNotes
FILE_IDpositionalyes—intID of the file.
fields--input fieldno—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.

mammoth file list
NamePassed asRequiredDefaultTypeNotes
fields--input fieldno—str
file_ids--input fieldno—list[int]
names--input fieldno—list[str]
statuses--input fieldno—list[str]
created_at--input fieldno—str
updated_at--input fieldno—str
limit--input fieldno50int
offset--input fieldno0int
sort--input fieldno—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.

mammoth file multi-sheet-extract 123 --input '{"tables": [{"name": "Status"}]}'
NamePassed asRequiredDefaultTypeNotes
FILE_IDpositionalyes—intID of the file.
tables--input fieldyes—list[dict[str, any]]
delete_file_after_extract--input fieldnotruebool
  • 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.

mammoth file multi-sheet-preview 123 --input '{"sheet_name": "Revenue report"}'
NamePassed asRequiredDefaultTypeNotes
FILE_IDpositionalyes—intID of the file.
sheet_name--input fieldyes—str
block_id--input fieldno—str
user_instruction--input fieldno—str
structure_map--input fieldno—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'.

mammoth file set-password 123 --input /private/path/request.json --yes --confirm 123
NamePassed asRequiredDefaultTypeNotes
FILE_IDpositionalyes—intID of the file.
password--input fieldyes—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.

mammoth file update 123 --input '{"patch_request": {"patch": [{"op": "replace", "path": "extract_sheets", "value": "Sheet1"}]}}'
NamePassed asRequiredDefaultTypeNotes
FILE_IDpositionalyes—intID of the file.
patch_request--input fieldyes—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.

mammoth file upload ./sales.csv
NamePassed asRequiredDefaultTypeNotes
FILESpositionalno—strPath to a local file to upload; or pass one or more via the 'files' field. Or the files input field.
files--input fieldno—list[str | Path | BinaryIO] | str | Path | BinaryIO | None
folder_resource_id--input fieldno—str | int | None
append_to_ds_id--input fieldno—int
override_target_schema--input fieldno—bool
wait_for_completion--input fieldnotruebool
timeout--input fieldno300int
mode--input fieldno—str
sheets--input fieldno—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'.

mammoth file upload-folder ./sales.csv
NamePassed asRequiredDefaultTypeNotes
FOLDER_PATHpositionalno—strPath to a local folder to upload; or pass it via the 'folder_path' input field. Or the folder_path input field.
folder_path--input fieldno—str | Path
folder_resource_id--input fieldno—str
wait_for_completion--input fieldnotruebool
timeout--input fieldno300int
  • 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

Report an issue · support@mammoth.io