# uip or buckets

> Syntax and options for `uip or buckets`, which manages Orchestrator storage containers used by automations.

Manage Orchestrator **buckets** — storage containers for files used by automations. Bucket operations are folder-scoped. For per-file operations inside a bucket, see [`uip or bucket-files`](./uip-or-bucket-files.md).

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

## Synopsis

```
uip or buckets list          [--folder-path <path> | --folder-key <key> | --all-folders] [-n <name>] [--exclude-folder-path <path>] [--exclude-folder-key <key>] [-l, --limit <n>] [--offset <n>] [--sort-by <field>] [--all-fields]
uip or buckets get           <bucket-key> [--folder-path <path> | --folder-key <key>] [--all-fields]
uip or buckets create        <name> --folder-path <path> | --folder-key <key> [options below]
uip or buckets update        <bucket-key> [options as for create]
uip or buckets delete        <bucket-key> --yes | --force
uip or buckets share         <bucket-key> --folder-path <path> | --folder-key <key>
uip or buckets unshare       <bucket-key> --folder-path <path> | --folder-key <key>
uip or buckets list-folders  <bucket-key>
```

## list

List buckets. **Requires `--folder-path`, `--folder-key`, or `--all-folders`.** With a folder, lists buckets inside that folder. With `--all-folders`, lists across every accessible folder (optionally excluding one via `--exclude-folder-path` / `--exclude-folder-key`, which apply only in that mode). Filter: `-n, --name <name>`. `--sort-by <field>` sorts results (default `Id desc`); `--all-fields` returns the full API response.

```bash
uip or buckets list --folder-path Shared
```

## get

Get bucket details by key. `--all-fields` returns the full API response, including storage container, credential-store link, and tags.

```bash
uip or buckets get a1b2c3d4-0000-0000-0000-000000000001
```

## create

Create a bucket in a folder. Requires `<name>`. Optional flags include `--identifier <guid>` (auto-generated if omitted), `-d, --description`, `--storage-provider <Azure|Amazon|Minio|S3Compatible|FileSystem>` (omit for Orchestrator built-in), `--storage-parameters`, `--storage-container`, `--credential-store-key` (required for `Azure` and `Amazon`), `--external-name`, `--password`, `--options <None|ReadOnly|AuditReadAccess|AccessDataThroughOrchestrator>`, `--tags <json>` (a JSON array, e.g. `'[{"name":"env","value":"prod"}]'`).

```bash
uip or buckets create invoices --folder-path Shared \
  --description "Invoice attachments"
```

## update

Update bucket properties by key. Same flags as `create` (all optional; `-n, --name` renames the bucket on `update`).

## delete

Delete a bucket by key. Requires `-y, --yes` — the CLI never prompts for destructive operations. Refuses to delete a bucket that still has files unless you also pass `-f, --force` (which deletes the files too, and implies `--yes`).

```bash
uip or buckets delete a1b2c3d4-0000-0000-0000-000000000010 --yes
uip or buckets delete a1b2c3d4-0000-0000-0000-000000000010 --force
```

## share / unshare

Add or remove the bucket from a folder.

## list-folders

List the folders a bucket is shared with.

## Exit codes

See [Exit codes](./exit-codes.md) for the shared contract. `delete` exits `1` if `-y, --yes` / `-f, --force` is omitted, or if the bucket still has files and `--force` was not passed.

## Related commands

- [`uip or bucket-files`](./uip-or-bucket-files.md) — per-file operations inside a bucket.
- [`uip or credential-stores list`](./uip-or-credential-stores.md) — find the `--credential-store-key` required for `Azure`/`Amazon` storage providers.

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