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

# Storage buckets

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

## Commands

### khotan buckets create

Usage: `khotan buckets create --name <string> [--idempotency-key <string>]`

Provision a Khotan-managed storage bucket: a private folder subtree in the organization's file storage, reached through the Files API with a scoped key. Provisioning is synchronous; branch on the returned status (ready or failed). Pass --idempotency-key to make retries safe — the same key returns the original bucket instead of creating a second one.

Arguments & options:
- `--name` — The bucket name (1-63 characters). (required, body)
- `--idempotency-key` — Optional client-chosen key; a retry with the same key returns the original bucket. (optional, body)

Examples:
- `khotan buckets create --name uploads --idempotency-key deploy-42`

### khotan buckets credentials

Usage: `khotan buckets credentials <bucketId>`

Issue a folder-scoped API key for the bucket and return its secret once. The key acts only through the Files API and only within the bucket's folder subtree. Each call rotates the credential: any previously issued key for this bucket is revoked. Returns { apiKey, keyId, prefix, filesApiBaseUrl }. Secret-bearing; explicit-only.

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

Safety: secret — returns credential-bearing values; never shown in list/table output.

### khotan buckets delete

Usage: `khotan buckets delete <bucketId>`

Permanently delete a storage bucket: empties its folder subtree, revokes its scoped credentials, then removes the record. Fails if deletion protection is enabled; remove protection from the dashboard first.

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

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

### khotan buckets get

Usage: `khotan buckets get <bucketId>`

Get one storage bucket by id, including status and failure state (no credentials).

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

### khotan buckets list

Usage: `khotan buckets list`

List the organization's storage buckets (no credentials).

### khotan buckets tags set

Usage: `khotan buckets tags set <bucketId> --tags <a,b>`

Replace the tags on a storage bucket and return the stored list.

Arguments & options:
- `<bucketId>` — The storage bucket id. (required, path)
- `--tags` — Full tag list, comma-separated or repeatable; it replaces the stored list, and an empty value clears it. The server lowercases each tag and turns spaces into hyphens. Up to 10 tags of 1-32 lowercase letters, digits, or single hyphens. (required, body)

Examples:
- `khotan buckets tags set <bucketId> --tags live,eu`

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