# uip or bucket-files

> Syntax and options for `uip or bucket-files`, which manages files inside Orchestrator storage buckets.

Manage **files inside buckets**: list, inspect, download, upload, delete, and fetch pre-signed URLs. Every subcommand takes `<bucket-key>` as its first argument. For the bucket itself (create / share / list across folders), see [`uip or buckets`](./uip-or-buckets.md).

For the cross-resource conventions (auth, folder scoping, key types, output envelope), see the [`uip or` overview](./uip-or.md).

## Synopsis

```
uip or bucket-files list              <bucket-key> --folder-path <path> | --folder-key <key> [--prefix <path> | -d <directory>] [--take-hint <n>] [--continuation-token <token>] [--expiry-in-minutes <n>] [--all-fields]
uip or bucket-files list-dirs         <bucket-key> --folder-path <path> | --folder-key <key> [-d <directory>] [--file-name-glob <pattern>] [-l <n>] [--offset <n>] [--all-fields]
uip or bucket-files get               <bucket-key> <path> --folder-path <path> | --folder-key <key> [--all-fields]
uip or bucket-files delete            <bucket-key> <path> --folder-path <path> | --folder-key <key> --yes
uip or bucket-files download          <bucket-key> <path> --folder-path <path> | --folder-key <key> [-d <local-file>]
uip or bucket-files upload            <bucket-key> <path> --folder-path <path> | --folder-key <key> --file <local-file> [--content-type <mime>]
uip or bucket-files get-download-url  <bucket-key> <path> --folder-path <path> | --folder-key <key> [--expiry-in-minutes <n>]
uip or bucket-files get-upload-url    <bucket-key> <path> --folder-path <path> | --folder-key <key> [--expiry-in-minutes <n>] [--content-type <mime>]
```

## list

List files in a bucket. Two mutually exclusive modes: the default (flat, prefix-filtered) mode is paginated via `--take-hint` (default 500, max 1000) and `--continuation-token`, and accepts `--prefix <path>` and `--expiry-in-minutes <n>` (for the pre-signed download URLs included in each item). Passing `-d, --directory <path>` switches to Orchestrator's directory-listing API instead — a different response shape with no continuation token — and is incompatible with `--prefix`, `--take-hint`, `--continuation-token`, and `--expiry-in-minutes`. `--all-fields` returns the full API response.

```bash
uip or bucket-files list a1b2c3d4-0000-0000-0000-000000000001 \
  --folder-path Shared
```

## list-dirs

List virtual directories. Optional `-d, --directory <path>` (lists root if omitted), `--file-name-glob <pattern>`, `-l, --limit`, `--offset`, `--all-fields`.

## get

Get file metadata at `<path>`. `--all-fields` returns the full API response.

## delete

Delete file at `<path>`. Requires `-y, --yes` — the CLI never prompts for destructive operations.

```bash
uip or bucket-files delete a1b2c3d4-0000-0000-0000-000000000001 \
  "reports/summary.csv" --folder-path Shared --yes
```

## download

Download a file. With `-d, --destination <file>`, writes to disk (emits a `BucketFileDownload` envelope); without, streams content to stdout.

```bash
uip or bucket-files download a1b2c3d4-0000-0000-0000-000000000001 \
  "reports/summary.csv" --folder-path Shared --destination ./summary.csv
```

## upload

Upload a local file. Requires `--file <local-file>`. Optional `--content-type <mime>` (auto-detected if omitted).

```bash
uip or bucket-files upload a1b2c3d4-0000-0000-0000-000000000001 \
  "reports/summary.csv" --folder-path Shared --file ./summary.csv
```

## get-download-url / get-upload-url

Return a pre-signed URL to the file location, without transferring any data through the CLI. Optional `--expiry-in-minutes <n>`; the upload variant also accepts `--content-type`. To upload a local file end-to-end (presign and transfer in one step), use `bucket-files upload` instead.

## Exit codes

See [Exit codes](./exit-codes.md) for the shared contract. `delete` exits `1` if `-y, --yes` is omitted.

## Related commands

- [`uip or buckets`](./uip-or-buckets.md) — bucket-level CRUD.

## See also

- [`uip or` overview](./uip-or.md) — shared conventions for every `uip or` verb.
- [How-to: manage Orchestrator assets and queues](./howto-manage-resources.md) — bucket-file upload / download patterns.