# ry bucket

> Manage object storage buckets (files for your apps).

```text
ry bucket [options] [command]
```

## Subcommands

### `ry bucket create`

Create a bucket you can attach to an app.

```text
ry bucket create [options] <name>
```

Example:

```bash
ry bucket create my-uploads
```

### `ry bucket check`

Is this bucket name still available in this region?

```text
ry bucket check [options] <name>
```

Example:

```bash
ry bucket check my-uploads
```

### `ry bucket list`

List buckets.

```text
ry bucket list [options]
```

Example:

```bash
ry bucket list
```

### `ry bucket show`

Bucket detail with object count and size.

```text
ry bucket show [options] <name>
```

Example:

```bash
ry bucket show my-uploads
```

### `ry bucket ls`

List objects in a bucket.

```text
ry bucket ls [options] <name>
```

Options:

- `--prefix <prefix>`: Only keys starting with this prefix.
- `--limit <n>`: Objects per page (max 1000). Default: `100`.
- `--cursor <cursor>`: Continue from a previous page.

Example:

```bash
ry bucket ls my-uploads --prefix reports/
```

### `ry bucket rm`

Delete one object from a bucket (irreversible).

```text
ry bucket rm [options] <bucket> <key>
```

Options:

- `-y, --yes`: Skip confirmation (required in automation).

Example:

```bash
ry bucket rm my-uploads reports/2026-10.pdf --yes
```

### `ry bucket presign`

Get a time-limited URL for one object (GET by default, --put to upload).

```text
ry bucket presign [options] <bucket> <key>
```

Options:

- `--put`: Sign an upload (PUT) instead of a download (GET).
- `--expires <seconds>`: How long the URL stays valid. Default: `900`.
- `--content-type <type>`: PUT only: the Content-Type the uploader must then send.

Example:

```bash
ry bucket presign my-uploads reports/2026-10.pdf
ry bucket presign my-uploads reports/2026-10.pdf --put --content-type application/pdf
```

### `ry bucket attach`

Attach a bucket to an app (injects S3_* into its environment).

```text
ry bucket attach [options] <bucket>
```

Options:

- `--to <app>`: App that should get access.
- `--as <name>`: Name this attachment: `<NAME>_S3_BUCKET` etc. instead of S3_BUCKET (required from the second bucket of an app).
- `-y, --yes`: Skip the re-attach warning.

Example:

```bash
ry bucket attach my-uploads --to web
ry bucket attach my-uploads --to web --as uploads
```

### `ry bucket detach`

Detach a bucket from an app (removes S3_*, revokes its key; the files stay).

```text
ry bucket detach [options] <bucket>
```

Options:

- `--from <app>`: App that should lose access.

Example:

```bash
ry bucket detach my-uploads --from web
```

### `ry bucket cors`

Show the CORS rules of a bucket (browsers need them for direct uploads).

```text
ry bucket cors [options] <name>
```

Example:

```bash
ry bucket cors my-uploads
```

### `ry bucket cors-set`

Replace the CORS rules of a bucket (needed for direct browser uploads).

```text
ry bucket cors-set [options] <name>
```

Options:

- `--allow-origin <origins>`: Comma-separated, or '*'. Default: `*`.
- `--allow-method <methods>`: Comma-separated. Default: `GET,PUT,HEAD`.
- `--allow-header <headers>`: Comma-separated. Default: `*,authorization`.
- `--expose-header <headers>`: Comma-separated. Default: `ETag`.
- `--max-age <seconds>`: How long a browser may cache the preflight. Default: `3000`.
- `--clear`: Remove the configuration entirely.

Example:

```bash
ry bucket cors-set my-uploads --allow-origin https://www.example.com
```

### `ry bucket destroy`

Destroy a bucket and everything in it (irreversible).

```text
ry bucket destroy [options] <name>
```

Options:

- `-y, --yes`: Skip confirmation (required in automation).
- `--force`: Also destroy a bucket that still holds objects.

Example:

```bash
ry bucket destroy my-uploads --yes
ry bucket destroy my-uploads --force --yes
```