# Buckets

> Object storage per environment — private or public, with a CLI data plane and presigned URLs

URL: https://pier.run/docs/resources/buckets

```yaml title="pier.yaml"
environments:
  prod:
    buckets:
      - name: uploads
        access: private          # or public
    apps:
      - name: api
        env:
          UPLOADS_URL: { from: buckets.uploads.url }
          UPLOADS_KEY: { from: buckets.uploads.access_key }
          UPLOADS_SECRET: { from: buckets.uploads.secret_key }
```

```bash
pier ls buckets
```

```text title="output"
                         
 NAME    ACCESS  UPDATED 
                         
 uploads private 45s ago 
                         

```

A bucket holds objects under an HTTPS hostname of its own. `private` buckets answer only
to the bucket's credentials or a presigned URL; `public` buckets serve every object to
anyone with the key. Apps reach a bucket through a [link](/docs/vars) that resolves to
an S3-compatible endpoint and credentials.

## Configuration

| Key      | Meaning                         |
| -------- | ------------------------------- |
| `access` | `private` (default) or `public` |

Links: `buckets.<name>.url`, `.name`, `.endpoint`, `.access_key`, `.secret_key`.

## Commands

| Command                                                                                                                | Does                                    |
| ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| `pier add bucket --name uploads --access private`, `pier set bucket uploads --access public`, `pier rm bucket uploads` | declare, change, remove                 |
| `pier objects ls --bucket uploads`                                                                                     | list objects                            |
| `pier objects put --bucket uploads ./file.png`                                                                         | upload                                  |
| `pier objects get --bucket uploads file.png`                                                                           | download                                |
| `pier objects presign --bucket uploads file.png --method GET`                                                          | a time-limited URL for a private object |
| `pier objects rm --bucket uploads file.png`                                                                            | delete an object                        |
| `pier info uploads`, `pier monitor uploads`                                                                            | hostname, storage and egress            |

## Behaviour

* Any S3 client works with the link's endpoint and keys (`aws s3`, the AWS SDKs, `mc`).
* Egress through the bucket hostname is metered per bucket (`pier monitor uploads`).
* Removing a bucket keeps its objects in [trash](/docs/concepts#trash) for 30 days.

## Tasks

[Set environment variables](/docs/guides/set-environment-variables)