> ## Documentation Index
> Fetch the complete documentation index at: https://vetta.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# vetta storage

> Buckets and objects on a fullstack app's object store, from the terminal.

Object [storage](/docs/api/storage) on the organization's `fullstack` [app](/docs/api/apps). Every command takes `--app <id>`; without it the organization's single `fullstack` app is used — two candidates is `409 ambiguous_app` naming both, none is `404 not_found`.

Reads require the `agents:read` scope; `mb`, `rb`, `put`, `rm` and `url --upload` require `agents:write`.

## Commands

| Command                                   | Description                                                                  |
| ----------------------------------------- | ---------------------------------------------------------------------------- |
| `vetta storage buckets`                   | The app's buckets.                                                           |
| `vetta storage mb <bucket>`               | Make a bucket. `--public` serves its objects without a signature.            |
| `vetta storage rb <bucket>`               | Remove a bucket. A non-empty bucket needs `--force`, which empties it first. |
| `vetta storage ls <bucket>[/<prefix>]`    | The objects, or only those under the prefix.                                 |
| `vetta storage put <bucket>/<key> <file>` | Upload a file as the object.                                                 |
| `vetta storage get <bucket>/<key> [file]` | Download the object to the file, or to stdout.                               |
| `vetta storage rm <bucket>/<key>`         | Delete the object. Idempotent.                                               |
| `vetta storage url <bucket>/<key>`        | A one-hour download URL, or with `--upload` a PUT URL.                       |

## buckets, mb, rb

```bash theme={"system"}
vetta storage buckets
vetta storage mb avatars --public
vetta storage rb avatars --force
```

| Flag       | Description                                                       |
| ---------- | ----------------------------------------------------------------- |
| `--app`    | The app, when the organization has more than one `fullstack` app. |
| `--public` | `mb`: a public bucket.                                            |
| `--force`  | `rb`: empty the bucket before removing it.                        |

## ls

```bash theme={"system"}
vetta storage ls avatars
vetta storage ls avatars/users/ --limit 50
```

| Flag      | Description                                  |
| --------- | -------------------------------------------- |
| `--limit` | Page size.                                   |
| `--after` | Cursor from a previous page's `next_cursor`. |

## put, get, rm

```bash theme={"system"}
vetta storage put avatars/users/alice.json ./alice.json
vetta storage get avatars/users/alice.json            # bytes on stdout
vetta storage get avatars/users/alice.json ./out.json # bytes into the file
vetta storage rm avatars/users/alice.json
```

`put` sends the file's bytes inline (up to 50 MiB) with a `Content-Type` taken from `--content-type`, else from the file's suffix (`.json`, `.png`, `.pdf`, …), else `application/octet-stream`. For a larger upload take a URL with `url --upload` and `PUT` the bytes to it directly.

| Flag             | Description                                      |
| ---------------- | ------------------------------------------------ |
| `--content-type` | `put`: the type to store, overriding the suffix. |

## url

```bash theme={"system"}
vetta storage url avatars/users/alice.json
vetta storage url avatars/video.mp4 --upload --content-type video/mp4 --expires 3600
```

| Flag             | Description                                                                 |
| ---------------- | --------------------------------------------------------------------------- |
| `--upload`       | A `PUT` URL for the bytes instead of a `GET` URL for them.                  |
| `--content-type` | `--upload`: the type the upload will carry; defaults from the key's suffix. |
| `--expires`      | `--upload`: seconds the URL is good for, 60–3600, default 900.              |