# Azion CLI storage
The Azion CLI `storage` commands create, list, describe, update, and delete the buckets and objects of [Object Storage](/en/documentation/platform/object-storage/). Every verb takes a subcommand: `bucket` acts on a bucket, named with `--name`, and `object` acts on a file inside a bucket, named with `--bucket-name` and `--object-key`. The options every command accepts, such as `--format`, `--out`, and `-y`, are on [Global options](/en/documentation/devtools/cli/globals/).
---
## Create
`azion create storage` takes the `bucket` or the `object` subcommand.
### Bucket
`azion create storage bucket` creates a bucket with the name and the access level you pass:
```bash
azion create storage bucket [flags]
```
| Flag | Short | Type | Default | Description |
| -------------------- | ----- | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--file` | — | string | — | Path to a JSON file with the attributes of the bucket. Use `-` to read the JSON from standard input. |
| `--name` | — | string | — | Name of the bucket, in lowercase letters, numbers, and hyphens. |
| `--workloads-access` | — | string | — | **Required** unless `--file` is set. Permission type for actions within the bucket: `read_only`, `read_write`, or `restricted`. Without it, the command asks you to choose one. |
A name with capital letters is refused with this error:
```text
Error: Failed to create the bucket: ["Names can contain hyphen, numbers and letters (alphanumeric)."]. Check your settings and try again. If the error persists, contact Azion support.
```
Any other `--workloads-access` value is refused the same way, such as `public` with `["\"public\" is not a valid choice."]`.
This command creates a bucket named `my-bucket` with the `read_only` access level:
```bash
azion create storage bucket --name my-bucket --workloads-access read_only
```
The command confirms the creation:
```text
Bucket created successfully
```
### Object
`azion create storage object` uploads a local file to a bucket as an object:
```bash
azion create storage object [flags]
```
| Flag | Short | Type | Default | Description |
| --------------- | ----- | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--bucket-name` | — | string | — | Name of the bucket that receives the object. |
| `--file` | — | string | — | Path to a JSON file with the attributes of the object. Use `-` to read the JSON from standard input. The command reads the local path from the file and still needs `--bucket-name` and `--object-key`. |
| `--object-key` | — | string | — | **Required**, also with `--file`. Key of the object in the bucket. A key can be a full path, such as `path/to/file/bucket/file.txt`. |
| `--source` | — | string | — | Path to the local file to upload. A relative path is read from the current directory. |
A bucket that does not exist, or a `--file` call without `--object-key`, fails with this error:
```text
Error: Failed to create the object: The given ID or API's endpoint doesn't exist or isn't available. Check that the identifying information is correct. Check your settings and try again. If the error persists, contact Azion support.
```
This command uploads `./upload/index.html` to `my-bucket` under the key `site/index.html`:
```bash
azion create storage object --bucket-name my-bucket --object-key 'site/index.html' --source ./upload/index.html
```
The command confirms the upload:
```text
Object created successfully
```
---
## List
`azion list storage` takes the `bucket` or the `object` subcommand.
### Bucket
`azion list storage bucket` lists the buckets of your account with the access level of each, 50 to a page:
```bash
azion list storage bucket [flags]
```
| Flag | Short | Type | Default | Description |
| ------------- | ----- | ---- | ------- | ------------------------------- |
| `--page` | — | int | `1` | Number of the page to return. |
| `--page-size` | — | int | `50` | Number of buckets on each page. |
The command has no `--details` flag and fails with `Error: unknown flag: --details` when you pass one.
This command returns the first page of a list split into pages of two buckets:
```bash
azion list storage bucket --page 1 --page-size 2
```
The command prints one row per bucket:
```text
NAME WORKLOADS ACCESS
my-blog read_only
my-store read_only
```
### Object
`azion list storage object` lists the objects of one bucket with the key and the last change of each, 50 to a page:
```bash
azion list storage object [flags]
```
| Flag | Short | Type | Default | Description |
| --------------- | ----- | ------ | ------- | -------------------------------------------------------------------------------------------------- |
| `--bucket-name` | — | string | — | **Required**. Name of the bucket whose objects to list. Without it, the command asks for the name. |
| `--details` | — | — | — | Adds the `SIZE` column, in bytes, to the `KEY` and `LAST MODIFIED` columns. |
| `--next-page` | — | — | — | Returns the next page of the list, after the first `--page-size` objects. |
| `--page-size` | — | int | `50` | Number of objects on each page. |
This command lists the objects of `my-bucket` with their sizes:
```bash
azion list storage object --bucket-name my-bucket --details
```
The command prints one row per object:
```text
KEY LAST MODIFIED SIZE
site/index.html 2026-01-01 12:00:00.91 +0000 UTC 21
site/three.txt 2026-01-01 12:00:33.931 +0000 UTC 7
site/two.txt 2026-01-01 12:00:24.561 +0000 UTC 7
```
---
## Describe
`azion describe storage` takes the `object` subcommand. Its help lists no subcommand.
### Bucket
`azion describe storage bucket` takes no `--name` flag and fails with `Error: unknown flag: --name`, so the CLI does not describe a bucket. To read the access level of a bucket, run `azion list storage bucket`.
### Object
`azion describe storage object` prints the content of one object:
```bash
azion describe storage object [flags]
```
| Flag | Short | Type | Default | Description |
| --------------- | ----- | ---- | ------- | ----------------------------------------- |
| `--bucket-name` | — | — | — | Name of the bucket that holds the object. |
| `--object-key` | — | — | — | Key of the object to print. |
This command prints the object `site/index.html` of `my-bucket`:
```bash
azion describe storage object --bucket-name my-bucket --object-key site/index.html
```
The command prints the content of the object as stored:
```text
hello world
```
With `--format json`, the command prints the same content, not a JSON object. With `--out`, such as `--out object-download.html`, it writes the object to that file instead of printing it.
---
## Update
`azion update storage` takes the `bucket` or the `object` subcommand.
### Bucket
`azion update storage bucket` changes the access level of a bucket:
```bash
azion update storage bucket [flags]
```
| Flag | Short | Type | Default | Description |
| -------------------- | ----- | ------ | ------- | --------------------------------------------------------------------------------------------------------------------------- |
| `--file` | — | string | — | Path to a JSON file with the name of the bucket and the attributes to change. Use `-` to read the JSON from standard input. |
| `--name` | — | string | — | Name of the bucket to update. |
| `--workloads-access` | — | string | — | Permission type to set for actions within the bucket: `read_only`, `read_write`, or `restricted`. |
This command changes the access level of `my-bucket` to `restricted`:
```bash
azion update storage bucket --name my-bucket --workloads-access restricted
```
The command confirms the update:
```text
Bucket updated successfully
```
After the update, `azion list storage bucket` shows `restricted` for `my-bucket`.
### Object
`azion update storage object` replaces the content of an object with a local file:
```bash
azion update storage object [flags]
```
| Flag | Short | Type | Default | Description |
| --------------- | ----- | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--bucket-name` | — | string | — | Name of the bucket that holds the object. |
| `--file` | — | string | — | Path to a JSON file with the local path of the replacement content. Use `-` to read the JSON from standard input. Pass `--bucket-name` and `--object-key` with it. |
| `--object-key` | — | string | — | Key of the object to update. |
| `--source` | — | string | — | **Required** unless `--file` is set. Path to the local file with the replacement content. Without it, the command asks for the path. |
This command replaces the content of `site/index.html` in `my-bucket` with `./upload/index-v2.html`:
```bash
azion update storage object --bucket-name my-bucket --object-key site/index.html --source ./upload/index-v2.html
```
The command confirms the update:
```text
Object updated successfully
```
After the update, `azion describe storage object` prints the replacement content, `hello world updated
`.
---
## Delete
`azion delete storage` takes the `bucket` or the `object` subcommand.
### Bucket
`azion delete storage bucket` deletes a bucket and the objects in it:
```bash
azion delete storage bucket [flags]
```
| Flag | Short | Type | Default | Description |
| --------- | ----- | ------ | ------- | ------------------------------------ |
| `--force` | — | — | — | Empties the bucket, then deletes it. |
| `--name` | — | string | — | Name of the bucket to delete. |
> **Caution**
>
> `azion delete storage bucket` deletes every object in the bucket, also without `--force`.
This command deletes the empty bucket `my-other-bucket`:
```bash
azion delete storage bucket --name my-other-bucket
```
The command confirms the deletion, and the bucket leaves the list at once:
```text
Bucket my-other-bucket was deleted successfully
```
A bucket that holds objects is emptied, and its deletion is scheduled instead of done at once. The command prints this output:
```text
Delete all objects from bucket
Deleting objects...
Bucket deletion was scheduled successfully
```
The bucket then stays in `azion list storage bucket` for a while, with no objects in it. For more information, refer to [Object Storage limits](/en/documentation/platform/object-storage/limits/).
### Object
`azion delete storage object` deletes one object from a bucket:
```bash
azion delete storage object [flags]
```
| Flag | Short | Type | Default | Description |
| --------------- | ----- | ------ | ------- | ----------------------------------------- |
| `--bucket-name` | — | string | — | Name of the bucket that holds the object. |
| `--object-key` | — | string | — | Key of the object to delete. |
This command deletes the object `site/two.txt` from `my-bucket`:
```bash
azion delete storage object --bucket-name my-bucket --object-key site/two.txt -y
```
The command confirms the deletion:
```text
Object site/two.txt was deleted successfully
```
---
## Use a JSON file
`azion create storage` and `azion update storage` read the attributes of a bucket or an object from a JSON file with `--file`.
### Bucket file
A bucket file carries `name` and `workloads_access`. This file creates a bucket named `my-other-bucket` with the `read_write` access level:
```json
{
"name": "my-other-bucket",
"workloads_access": "read_write"
}
```
Pass the file to the create command:
```bash
azion create storage bucket --file bucket-create.json
```
The command confirms the creation:
```text
Bucket created successfully
```
On update, the command reads the bucket to change from `name`, so `--name` is not needed. This file changes the access level of `my-other-bucket` to `read_only`:
```json
{
"name": "my-other-bucket",
"workloads_access": "read_only"
}
```
Pass the file to the update command:
```bash
azion update storage bucket --file bucket-update.json
```
The command confirms the update:
```text
Bucket updated successfully
```
### Object file
An object file carries `source`, the path to the local file. The command does not read the key from the file, so pass `--bucket-name` and `--object-key` on the command line, on create and on update. This file points to the replacement content of `site/two.txt`:
```json
{
"source": "./upload/two-v2.txt"
}
```
Pass the file to the update command with the bucket and the key:
```bash
azion update storage object --bucket-name my-bucket --object-key site/two.txt --file object-update.json
```
The command confirms the update:
```text
Object updated successfully
```
---
## Related resources
- [Global options](/en/documentation/devtools/cli/globals.md): The options every command accepts, such as `--format`, `--out`, and `-y`.
- [Object Storage](/en/documentation/platform/object-storage.md): What a bucket and an object are, and how an application serves them.
- [Azion CLI connector](/en/documentation/devtools/cli/resources/connector.md): The commands that create a connector of type `storage`, which points an application at a bucket.
- [Azion CLI origin](/en/documentation/devtools/cli/resources/origin.md): The commands that point an origin of type `object_storage` at a bucket with `--bucket`.