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

# FILES

> Upload and manage project files and data sources

| Command                 | Description                                                       |
| ----------------------- | ----------------------------------------------------------------- |
| [`delete`](#delete)     | Permanently delete a file from the project.                       |
| [`download`](#download) | Download a file to local disk.                                    |
| [`get`](#get)           | Show metadata for a single file.                                  |
| [`list`](#list)         | List files in a project, optionally filtered by kind.             |
| [`update`](#update)     | Rename a file.                                                    |
| [`upload`](#upload)     | Upload a local file, waiting for the ingest to finish by default. |

***

## DELETE

Permanently delete a file from the project.

```bash theme={null}
oumi-cli files delete [OPTIONS] {file_id}
```

**Arguments**

| Argument  | Type | Required | Description                                  |
| --------- | ---- | -------- | -------------------------------------------- |
| `FILE_ID` | int  | ✓        | ID of the file to delete (see `files list`). |

**Options**

| Option      | Type | Required | Description                                                                        |
| ----------- | ---- | -------- | ---------------------------------------------------------------------------------- |
| `--project` | str  |          | Project that owns the file; 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.                                   |

***

## DOWNLOAD

Download a file to local disk.

```bash theme={null}
oumi-cli files download [OPTIONS] {file_id}
```

**Arguments**

| Argument  | Type | Required | Description                                    |
| --------- | ---- | -------- | ---------------------------------------------- |
| `FILE_ID` | int  | ✓        | ID of the file to download (see `files list`). |

**Options**

| Option         | Type | Required | Description                                                                              |
| -------------- | ---- | -------- | ---------------------------------------------------------------------------------------- |
| `--project`    | str  |          | Project that owns the file; falls back to OUMI\_PROJECT\_ID or the active profile.       |
| `--out`        | path |          | Destination file or directory. Defaults to ./file-\<id>.\<ext> in the current directory. |
| `--expiration` | int  |          | Lifetime of the download's presigned URL, in seconds (default 3600).                     |

***

## GET

Show metadata for a single file.

```bash theme={null}
oumi-cli files get [OPTIONS] {file_id}
```

**Arguments**

| Argument  | Type | Required | Description                                   |
| --------- | ---- | -------- | --------------------------------------------- |
| `FILE_ID` | int  | ✓        | ID of the file to inspect (see `files list`). |

**Options**

| Option      | Type | Required | Description                                                                        |
| ----------- | ---- | -------- | ---------------------------------------------------------------------------------- |
| `--project` | str  |          | Project that owns the file; falls back to OUMI\_PROJECT\_ID or the active profile. |

***

## LIST

List files in a project, optionally filtered by kind.

```bash theme={null}
oumi-cli files list [OPTIONS]
```

**Options**

| Option        | Type      | Required | Description                                                                                                               |
| ------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------- |
| `--project`   | str       |          | Project to list files in; falls back to OUMI\_PROJECT\_ID or the active profile.                                          |
| `--limit`     | int range |          | Return at most N files (default 100). The CLI fetches and loops over pages internally; you never pass a page token.       |
| `--all`       | flag      |          | Return every file, 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).                                                                              |
| `--kind`      | choice    |          | Filter by file kind: STRUCTURED (tabular data) or UNSTRUCTURED (free-text documents). Omit to return files of every kind. |

***

## UPDATE

Rename a file.

```bash theme={null}
oumi-cli files update [OPTIONS] {file_id}
```

**Arguments**

| Argument  | Type | Required | Description                                  |
| --------- | ---- | -------- | -------------------------------------------- |
| `FILE_ID` | int  | ✓        | ID of the file to update (see `files list`). |

**Options**

| Option           | Type | Required | Description                                                                        |
| ---------------- | ---- | -------- | ---------------------------------------------------------------------------------- |
| `--project`      | str  |          | Project that owns the file; falls back to OUMI\_PROJECT\_ID or the active profile. |
| `--display-name` | str  |          | New display name for the file.                                                     |

***

## UPLOAD

Upload a local file, waiting for the ingest to finish by default.

```bash theme={null}
oumi-cli files upload [OPTIONS] {file}
```

**Arguments**

| Argument | Type | Required | Description                                  |
| -------- | ---- | -------- | -------------------------------------------- |
| `FILE`   | path | ✓        | Path to the local file to upload (max 5 GB). |

**Options**

| Option                 | Type   | Required | Description                                                                                     |
| ---------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------- |
| `--project`            | str    |          | Project to upload the file into; falls back to OUMI\_PROJECT\_ID or the active profile.         |
| `--display-name`       | str    |          | Display name for the file. Defaults to the local filename.                                      |
| `--kind`               | choice |          | STRUCTURED (tabular data) or UNSTRUCTURED (free-text documents). Defaults to UNSTRUCTURED.      |
| `--expiration`         | int    |          | Lifetime of the upload's presigned URL, in seconds (default 3600).                              |
| `--wait` / `--no-wait` | flag   |          | Wait for the file ingest to finish (default); `--no-wait` returns the operation ID immediately. |

***