# CLI: Object Storage

Manage S3-compatible object storage buckets and access keys using the DanubeData CLI.

## Prerequisites

- [DanubeData CLI installed](https://docs.danubedata.ro/cli-overview)
- Authenticated via `danube auth`, `danube login`, or `DANUBE_TOKEN`

## Quick start

List your buckets:

```bash
danube storage buckets ls
```

Create a new bucket:

```bash
danube storage buckets create --name my-bucket --region fsn1
```

## Bucket management

### List buckets

```bash
danube storage buckets ls
```

Shows all buckets with ID, name, region, status, storage usage, and object count.

### Create a bucket

#### Interactive

```bash
danube storage buckets create
```

The CLI guides you through naming, region selection, and optional settings.

#### With flags

```bash
danube storage buckets create --name my-bucket --region fsn1 --versioning
```

### View bucket details

```bash
danube storage buckets get <id>
```

Displays full bucket details including endpoint URL, storage usage, object count, and configuration.

### Update bucket settings

```bash
danube storage buckets update <id> --size-limit 10GB --encryption
danube storage buckets update <id> --public --display-name "My Assets"
```

Available settings:

- `--size-limit` — Maximum storage size
- `--encryption` — Enable server-side encryption
- `--public` / `--private` — Toggle public access
- `--display-name` — Set a display name

### View bucket metrics

```bash
danube storage buckets metrics <id>
```

Shows the current snapshot: storage usage, object count, 24h requests, error rate, p50/p95 latency, egress/ingress bytes, and a freshness badge.

#### Trend (time-series)

```bash
danube storage buckets metrics trend <id>
danube storage buckets metrics trend <id> --window 7d --format table
```

- `-w, --window` — `24h` (default), `7d`, or `30d`
- `-r, --resolution` — `1m`, `5m`, `1h`, `1d` (auto by default)
- `-f, --format` — `sparkline` (default), `table`, `csv`, or `json`

#### Top objects

```bash
danube storage buckets metrics top <id> --by size
```

- `-b, --by` — `size` (default), `egress`, or `requests`
- `-l, --limit` — number of objects to return (default `10`)

#### Health

```bash
danube storage buckets metrics health <id>
```

Shows pending multipart uploads, deleted-version size (reclaimable space), and the last health-check time.

> **Freshness in scripts:** these commands exit with code **3** when the underlying data is stale or not yet available, so automation can branch on data freshness.

### Delete a bucket

```bash
danube storage buckets delete <id>
```

Prompts for confirmation. Deletion may take time for buckets with many objects.

## Access key management

Access keys provide S3-compatible credentials for connecting to your buckets from applications, backup tools, or S3 clients.

### List access keys

```bash
danube storage keys ls
```

Shows all access keys with ID, name, access key ID, and creation date.

### Create an access key

```bash
danube storage keys create --name "deploy-key"
```

**Important:** The secret key is displayed only once. Save it immediately.

### View access key details

```bash
danube storage keys get <id>
```

Shows key details (the secret key is not shown again after creation).

### Revoke an access key

```bash
danube storage keys revoke <id>
```

Immediately revokes the key. Any applications using this key will lose access.

## Using with S3 clients

After creating an access key, use it with any S3-compatible client:

```bash
# AWS CLI
aws configure
# Access Key ID: <from danube storage keys create>
# Secret Access Key: <from danube storage keys create>
# Region: fsn1

aws --endpoint-url https://s3.danubedata.ro s3 ls

# rclone
rclone config
# Type: s3
# Provider: Other
# Endpoint: https://s3.danubedata.ro
```

## Complete workflow example

```bash
# Install the CLI
npm install -g @danubedata/cli

# Authenticate
danube auth

# Create a bucket with versioning
danube storage buckets create --name my-backups --region fsn1 --versioning

# Create an access key for your application
danube storage keys create --name "app-key"
# Save the access key ID and secret key!

# Check bucket metrics
danube storage buckets metrics <id>

# List all keys
danube storage keys ls
```

## Next steps

- [CLI Overview](https://docs.danubedata.ro/cli-overview) — Installation, auth, and configuration
- [CLI: VPS Instances](https://docs.danubedata.ro/cli-vps) — Manage VPS instances
- [Object Storage overview](https://docs.danubedata.ro/object-storage) — Full object storage reference
- [Object Storage quick start](https://docs.danubedata.ro/object-storage-quickstart) — Dashboard-based guide

---

**Questions?** Contact support at support@danubedata.ro