> For the complete documentation index, see [llms.txt](https://docs.khotan.com/llms.txt). A markdown version of any page is available at its `index.md` URL.

# Files

Use the `khotan` CLI to operate Khotan files. Add `--json` for machine-readable output; results go to stdout, diagnostics to stderr.

## Commands

### khotan files delete

Usage: `khotan files delete <fileId>`

Permanently delete a file.

Arguments & options:
- `<fileId>` — The file id. (required, path)

Safety: destructive — prompts for confirmation in a terminal and refuses in non-interactive sessions unless you pass `--yes`.

### khotan files download-url

Usage: `khotan files download-url <fileId>`

Return a short-lived presigned GET URL for a ready file.

Arguments & options:
- `<fileId>` — The file id. (required, path)

### khotan files get

Usage: `khotan files get <fileId>`

Get one file's metadata by id.

Arguments & options:
- `<fileId>` — The file id. (required, path)

### khotan files list

Usage: `khotan files list [--folder-id <string>] [--path <string>] [--limit <number>] [--cursor <string>]`

List files, optionally scoped to a folder.

Arguments & options:
- `--folder-id` — Scope to a folder id. (optional, query)
- `--path` — Scope to a folder path. (optional, query)
- `--limit` — Page size (1-200). (optional, query)
- `--cursor` — Opaque pagination cursor. (optional, query)

### khotan files preview-url

Usage: `khotan files preview-url <fileId>`

Return a short-lived presigned inline GET URL for a ready, preview-eligible file (images and PDFs).

Arguments & options:
- `<fileId>` — The file id. (required, path)

### khotan files update

Usage: `khotan files update <fileId> [--name <string>] [--folder-id <string>] [--folder-path <string>]`

Update a file's name and/or containing folder.

Arguments & options:
- `<fileId>` — The file id. (required, path)
- `--name` — New file name. (optional, body)
- `--folder-id` — Destination folder id (null moves to root). (optional, body)
- `--folder-path` — Destination folder path. (optional, body)

### khotan files uploads complete

Usage: `khotan files uploads complete --files <json>`

Finalize uploads after bytes are PUT to the presigned URLs.

Arguments & options:
- `--files` — Array of { fileId } to finalize. (required, body)

### khotan files uploads prepare

Usage: `khotan files uploads prepare --files <json> [--folder-id <string>] [--folder-path <string>]`

Reserve pending file records and return presigned PUT URLs.

Arguments & options:
- `--files` — Array of { name, size, type? } descriptors. (required, body)
- `--folder-id` — Target folder id. (optional, body)
- `--folder-path` — Target folder path (created if missing). (optional, body)

## Local file transfer (presigned)

These commands move bytes between your machine and object storage using presigned URLs. They are CLI-only helpers (not catalog operations) that wrap the upload/download-url operations:

- `khotan files upload <localPath> [--name <n>] [--folder-id <id>] [--folder-path <p>] [--content-type <t>]` — upload a local file.
- `khotan files download <fileId> --output <path>` — download a file to a local path.

<!-- generated from khotan catalog v2026-10-30 (adapter 0.10.0); do not edit by hand -->