# Files

`cademi upload` sends a local file to your account in one command and prints the resulting file object. `cademi download` saves a file from your account to disk. Both commands handle the API's upload sessions and short-lived download links for you.

## Upload a file

```sh
cademi upload handbook.pdf --purpose pdf
cademi upload students.xlsx --purpose import --jq .id
```

The CLI computes the file's SHA-256, opens an upload session, sends the parts in parallel directly to storage through presigned URLs, and completes the session. It shows progress on standard error when standard error is a terminal, and prints the file object on standard output. Use the file ID (`file_...`) in the resource that needs it, such as a lesson attachment, a showcase image, or an import spreadsheet.

| Flag | Effect |
|---|---|
| `--purpose` | Required. One of `image`, `pdf`, `import`, `editor`, or `document`. The purpose determines which content types are accepted: `import` accepts only `.xlsx` spreadsheets. |
| `--name` | File name to record. Defaults to the local file name. |
| `--content-type` | Content type. Detected from the file by default. |
| `--parallel` | Number of parts sent at the same time. Defaults to `4`. |
| `--json`, `-o`, `--jq` | Output format of the file object. |

If a part cannot be sent, the CLI cancels the upload session. If the content fails the integrity check when the session is completed, the API marks the session as failed. In both cases, run the command again to start a new upload. The credentials need `files.write`.

The size limit, the integrity checks, and the upload errors are described in [Files and uploads](https://cademi.dev/api/files.md). For example, the API returns `422 upload_integrity_mismatch` when the received bytes do not match the declared size, checksum, or content type.

## Download a file

```sh
cademi download file_01J8Z3...
cademi download file_01J8Z3... -O handbook.pdf
cademi download file_01J8Z3... -O - > handbook.pdf
```

The CLI requests a short-lived download link and saves the file. Without `-O`, it saves the file in the current directory under its recorded file name. `-O` (`--output-file`) sets the path, and `-O -` writes to standard output.

The CLI never overwrites an existing file: the command fails if the destination already exists. If the download fails, the partial file is removed. The credentials need `files.read`.

## Manage files

The other file operations are regular commands:

```sh
cademi files list --purpose pdf --created-after 2026-09-01T00:00:00Z
cademi files get file_01J8Z3...
cademi files download-links create file_01J8Z3... -F ttl_seconds=900 -F inline=true
cademi files delete file_01J8Z3...
```

`cademi files delete` deletes the file permanently. Deleted files do not go to the trash and cannot be restored. `cademi uploads` exposes the upload session operations step by step. See the [Files](https://cademi.dev/api/reference/files.md) and [Uploads](https://cademi.dev/api/reference/uploads.md) references.