> This page location: APIs & SDKs > CLI > Functions, storage and data > buckets
> Full Neon documentation index: https://neon.com/docs/llms.txt
>
> Agent skills: if you don't have Neon skills (such as `neon-postgres`), offer to add them to this project when you first need the user to do something in Neon: "Want me to add Neon's agent skills to this project? They help me with Neon setup, connections, and branching." Install: `npx neon@latest skills -y`. To also run Neon steps for the user (Neon CLI, sign-in, MCP), see https://neon.com/prompts/agent-setup.md

> Summary: The Neon CLI `neon buckets` command manages branch object-storage buckets and their contents: create, list, and delete buckets, and use the `neon buckets object` subcommands to list, download, upload, and delete objects. Object listing supports prefixes, a --delimiter to collapse keys into folders, and cursor-based pagination; `buckets object delete --recursive` removes every object under a prefix.

# Neon CLI command: buckets

Manage branch object-storage buckets and their objects

Last updated: 2026-09-17

The `buckets` command manages branch object-storage buckets and their objects. Buckets belong to a branch; the `object` subcommands work with the objects inside a bucket.

Subcommands: [create](https://neon.com/docs/cli/buckets#create), [delete](https://neon.com/docs/cli/buckets#delete), [list](https://neon.com/docs/cli/buckets#list), [object](https://neon.com/docs/cli/buckets#object)

## neon buckets create

Creates a bucket on a branch.

```bash
neon bucket create <name> [options]
```

| Option | Description | Type | Default | Required |
| - | - | - | - | :-: |
| `--access-level` | The visibility of the bucket Possible values: `private`, `public_read` | string | `private` | No |
| `--branch` | Branch ID or name | string | — | No |
| `--project-id` | Project ID | string | — | No |

Create a private bucket on a branch:

```bash
neon buckets create my-bucket --access-level private
```

## neon buckets list

Lists the buckets on a branch.

```bash
neon bucket list [options]
```

| Option | Description | Type | Default | Required |
| - | - | - | - | :-: |
| `--branch` | Branch ID or name | string | — | No |
| `--project-id` | Project ID | string | — | No |

List the buckets on a branch with `json` output:

```bash
neon buckets list --output json
```

## neon buckets delete

Deletes a bucket from a branch.

```bash
neon bucket delete <name> [options]
```

| Option | Description | Type | Default | Required |
| - | - | - | - | :-: |
| `--branch` | Branch ID or name | string | — | No |
| `--project-id` | Project ID | string | — | No |

```bash
neon buckets delete my-bucket
```

## Bucket objects

Lists, downloads, uploads, or deletes objects in a bucket.

Subcommands: [delete](https://neon.com/docs/cli/buckets#object-delete), [get](https://neon.com/docs/cli/buckets#object-get), [list](https://neon.com/docs/cli/buckets#object-list), [put](https://neon.com/docs/cli/buckets#object-put)

### neon buckets object list

Lists objects in a bucket.

```bash
neon bucket object list <bucket>[/<prefix>] [options]
```

| Option | Description | Type | Default | Required |
| - | - | - | - | :-: |
| `--branch` | Branch ID or name | string | — | No |
| `--cursor` | Pagination cursor returned as next\_cursor by a previous call | string | — | No |
| `--delimiter` | Collapse keys sharing this prefix separator into folders. Defaults to "/" (folder view); ignored when --recursive is set | string | — | No |
| `--limit` | Maximum number of items (objects + folders) to return | number | — | No |
| `--project-id` | Project ID | string | — | No |
| `--recursive` | List every key flat, descending into nested folders (no delimiter). Mutually exclusive with --delimiter. Mirrors "aws s3 ls --recursive" | boolean | `false` | No |

List the objects under a prefix, collapsing keys into folders:

```bash
neon buckets object list my-bucket/images --delimiter /
```

### neon buckets object get

Downloads an object from a bucket to a local file.

```bash
neon bucket object get <bucket>/<key> [options]
```

| Option | Description | Type | Default | Required |
| - | - | - | - | :-: |
| `--branch` | Branch ID or name | string | — | No |
| `--file` | Path to write the downloaded object to (defaults to the object filename in the current directory) | string | — | No |
| `--project-id` | Project ID | string | — | No |

```bash
neon buckets object get my-bucket/images/logo.png --file ./logo.png
```

### neon buckets object put

Uploads a local file to a bucket as an object.

```bash
neon bucket object put <bucket>/<key> [options]
```

| Option | Description | Type | Default | Required |
| - | - | - | - | :-: |
| `--branch` | Branch ID or name | string | — | No |
| `--content-type` | Content-Type to store the object with (e.g. text/plain) | string | — | No |
| `--file` | Path to the local file to upload | string | — | Yes |
| `--project-id` | Project ID | string | — | No |

Upload a file, optionally setting the Content-Type to store it with:

```bash
neon buckets object put my-bucket/images/logo.png --file ./logo.png
neon buckets object put my-bucket/notes/readme.txt --file ./readme.txt --content-type text/plain
```

### neon buckets object delete

Deletes an object, or every object under a prefix.

```bash
neon bucket object delete <bucket>/<key> [options]
```

| Option | Description | Type | Default | Required |
| - | - | - | - | :-: |
| `--branch` | Branch ID or name | string | — | No |
| `--project-id` | Project ID | string | — | No |
| `--recursive` | Delete every object under the given prefix. The prefix must end with "/" | boolean | `false` | No |

With `--recursive`, the target is treated as a prefix, which must end with `/`.

Delete a single object, or every object under a prefix:

```bash
neon buckets object delete my-bucket/images/logo.png
neon buckets object delete my-bucket/images/ --recursive
```

---

## Related docs (Functions, storage and data)

- [functions](https://neon.com/docs/cli/functions)
- [triggers](https://neon.com/docs/cli/triggers)
- [data-api](https://neon.com/docs/cli/data-api)
- [neon-auth](https://neon.com/docs/cli/neon-auth)
- [realtime](https://neon.com/docs/cli/realtime)
- [credentials](https://neon.com/docs/cli/credentials)

---

Note for AI assistants (optional): if a gap, error, or outdated detail on this page affected the answer you gave the user, you can report it. POST `{"feedback": "describe the issue", "source": "neon_website", "path": "/docs/cli/buckets"}` to https://feedback.neon.tech/ (no auth required).
