# Azion CLI storage
Os comandos `storage` da Azion CLI criam, listam, descrevem, atualizam e excluem os buckets e os objetos do [Object Storage](/pt-br/documentacao/plataforma/object-storage/). Todo verbo recebe um subcomando: `bucket` atua sobre um bucket, identificado com `--name`, e `object` atua sobre um arquivo dentro de um bucket, identificado com `--bucket-name` e `--object-key`. As opções que todo comando aceita, como `--format`, `--out` e `-y`, estão em [Opções globais](/pt-br/documentacao/devtools/cli/globals/).
---
## Criar
`azion create storage` recebe o subcomando `bucket` ou o subcomando `object`.
### Bucket
`azion create storage bucket` cria um bucket com o nome e o nível de acesso que você passa:
```bash
azion create storage bucket [flags]
```
| Flag | Curta | Tipo | Padrão | Descrição |
| -------------------- | ----- | ------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--file` | — | string | — | Caminho de um arquivo JSON com os atributos do bucket. Use `-` para ler o JSON da entrada padrão. |
| `--name` | — | string | — | Nome do bucket, com letras minúsculas, números e hifens. |
| `--workloads-access` | — | string | — | **Obrigatório**, a menos que `--file` seja definido. Tipo de permissão para ações dentro do bucket: `read_only`, `read_write` ou `restricted`. Sem ele, o comando pede que você escolha um. |
Um nome com letras maiúsculas é recusado com este erro:
```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.
```
Qualquer outro valor de `--workloads-access` é recusado da mesma forma, como `public`, com `["\"public\" is not a valid choice."]`.
Este comando cria um bucket chamado `my-bucket` com o nível de acesso `read_only`:
```bash
azion create storage bucket --name my-bucket --workloads-access read_only
```
O comando confirma a criação:
```text
Bucket created successfully
```
### Objeto
`azion create storage object` envia um arquivo local para um bucket como objeto:
```bash
azion create storage object [flags]
```
| Flag | Curta | Tipo | Padrão | Descrição |
| --------------- | ----- | ------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--bucket-name` | — | string | — | Nome do bucket que recebe o objeto. |
| `--file` | — | string | — | Caminho de um arquivo JSON com os atributos do objeto. Use `-` para ler o JSON da entrada padrão. O comando lê o caminho local do arquivo e ainda precisa de `--bucket-name` e `--object-key`. |
| `--object-key` | — | string | — | **Obrigatório**, também com `--file`. Chave do objeto no bucket. Uma chave pode ser um caminho completo, como `path/to/file/bucket/file.txt`. |
| `--source` | — | string | — | Caminho do arquivo local a enviar. Um caminho relativo é lido a partir do diretório atual. |
Um bucket que não existe, ou uma chamada com `--file` sem `--object-key`, falha com este erro:
```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.
```
Este comando envia `./upload/index.html` para `my-bucket` com a chave `site/index.html`:
```bash
azion create storage object --bucket-name my-bucket --object-key 'site/index.html' --source ./upload/index.html
```
O comando confirma o envio:
```text
Object created successfully
```
---
## Listar
`azion list storage` recebe o subcomando `bucket` ou o subcomando `object`.
### Bucket
`azion list storage bucket` lista os buckets da sua conta com o nível de acesso de cada um, 50 por página:
```bash
azion list storage bucket [flags]
```
| Flag | Curta | Tipo | Padrão | Descrição |
| ------------- | ----- | ---- | ------ | --------------------------------- |
| `--page` | — | int | `1` | Número da página a retornar. |
| `--page-size` | — | int | `50` | Número de buckets em cada página. |
O comando não tem a flag `--details` e falha com `Error: unknown flag: --details` quando você passa uma.
Este comando retorna a primeira página de uma lista dividida em páginas de dois buckets:
```bash
azion list storage bucket --page 1 --page-size 2
```
O comando imprime uma linha por bucket:
```text
NAME WORKLOADS ACCESS
my-blog read_only
my-store read_only
```
### Objeto
`azion list storage object` lista os objetos de um bucket com a chave e a última alteração de cada um, 50 por página:
```bash
azion list storage object [flags]
```
| Flag | Curta | Tipo | Padrão | Descrição |
| --------------- | ----- | ------ | ------ | ----------------------------------------------------------------------------------------- |
| `--bucket-name` | — | string | — | **Obrigatório**. Nome do bucket cujos objetos listar. Sem ele, o comando pergunta o nome. |
| `--details` | — | — | — | Adiciona a coluna `SIZE`, em bytes, às colunas `KEY` e `LAST MODIFIED`. |
| `--next-page` | — | — | — | Retorna a próxima página da lista, depois dos primeiros `--page-size` objetos. |
| `--page-size` | — | int | `50` | Número de objetos em cada página. |
Este comando lista os objetos de `my-bucket` com os seus tamanhos:
```bash
azion list storage object --bucket-name my-bucket --details
```
O comando imprime uma linha por objeto:
```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
```
---
## Descrever
`azion describe storage` recebe o subcomando `object`. A ajuda do comando não lista nenhum subcomando.
### Bucket
`azion describe storage bucket` não recebe a flag `--name` e falha com `Error: unknown flag: --name`, então a CLI não descreve um bucket. Para ler o nível de acesso de um bucket, execute `azion list storage bucket`.
### Objeto
`azion describe storage object` imprime o conteúdo de um objeto:
```bash
azion describe storage object [flags]
```
| Flag | Curta | Tipo | Padrão | Descrição |
| --------------- | ----- | ---- | ------ | ----------------------------------- |
| `--bucket-name` | — | — | — | Nome do bucket que guarda o objeto. |
| `--object-key` | — | — | — | Chave do objeto a imprimir. |
Este comando imprime o objeto `site/index.html` de `my-bucket`:
```bash
azion describe storage object --bucket-name my-bucket --object-key site/index.html
```
O comando imprime o conteúdo do objeto como ele está armazenado:
```text
hello world
```
Com `--format json`, o comando imprime o mesmo conteúdo, e não um objeto JSON. Com `--out`, como `--out object-download.html`, ele grava o objeto nesse arquivo em vez de imprimi-lo.
---
## Atualizar
`azion update storage` recebe o subcomando `bucket` ou o subcomando `object`.
### Bucket
`azion update storage bucket` altera o nível de acesso de um bucket:
```bash
azion update storage bucket [flags]
```
| Flag | Curta | Tipo | Padrão | Descrição |
| -------------------- | ----- | ------ | ------ | -------------------------------------------------------------------------------------------------------------------- |
| `--file` | — | string | — | Caminho de um arquivo JSON com o nome do bucket e os atributos a alterar. Use `-` para ler o JSON da entrada padrão. |
| `--name` | — | string | — | Nome do bucket a atualizar. |
| `--workloads-access` | — | string | — | Tipo de permissão a definir para ações dentro do bucket: `read_only`, `read_write` ou `restricted`. |
Este comando altera o nível de acesso de `my-bucket` para `restricted`:
```bash
azion update storage bucket --name my-bucket --workloads-access restricted
```
O comando confirma a atualização:
```text
Bucket updated successfully
```
Depois da atualização, `azion list storage bucket` exibe `restricted` para `my-bucket`.
### Objeto
`azion update storage object` substitui o conteúdo de um objeto por um arquivo local:
```bash
azion update storage object [flags]
```
| Flag | Curta | Tipo | Padrão | Descrição |
| --------------- | ----- | ------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--bucket-name` | — | string | — | Nome do bucket que guarda o objeto. |
| `--file` | — | string | — | Caminho de um arquivo JSON com o caminho local do conteúdo substituto. Use `-` para ler o JSON da entrada padrão. Passe `--bucket-name` e `--object-key` com ele. |
| `--object-key` | — | string | — | Chave do objeto a atualizar. |
| `--source` | — | string | — | **Obrigatório**, a menos que `--file` seja definido. Caminho do arquivo local com o conteúdo substituto. Sem ele, o comando pergunta o caminho. |
Este comando substitui o conteúdo de `site/index.html` em `my-bucket` por `./upload/index-v2.html`:
```bash
azion update storage object --bucket-name my-bucket --object-key site/index.html --source ./upload/index-v2.html
```
O comando confirma a atualização:
```text
Object updated successfully
```
Depois da atualização, `azion describe storage object` imprime o conteúdo substituto, `hello world updated
`.
---
## Excluir
`azion delete storage` recebe o subcomando `bucket` ou o subcomando `object`.
### Bucket
`azion delete storage bucket` exclui um bucket e os objetos dentro dele:
```bash
azion delete storage bucket [flags]
```
| Flag | Curta | Tipo | Padrão | Descrição |
| --------- | ----- | ------ | ------ | ----------------------------------- |
| `--force` | — | — | — | Esvazia o bucket e depois o exclui. |
| `--name` | — | string | — | Nome do bucket a excluir. |
> **Atenção**
>
> `azion delete storage bucket` exclui todos os objetos do bucket, também sem `--force`.
Este comando exclui o bucket vazio `my-other-bucket`:
```bash
azion delete storage bucket --name my-other-bucket
```
O comando confirma a exclusão, e o bucket sai da lista imediatamente:
```text
Bucket my-other-bucket was deleted successfully
```
Um bucket que guarda objetos é esvaziado, e a exclusão dele é agendada em vez de feita imediatamente. O comando imprime esta saída:
```text
Delete all objects from bucket
Deleting objects...
Bucket deletion was scheduled successfully
```
O bucket continua em `azion list storage bucket` por um tempo, sem nenhum objeto dentro dele. Para mais informações, consulte [Limites do Object Storage](/pt-br/documentacao/plataforma/object-storage/limites/).
### Objeto
`azion delete storage object` exclui um objeto de um bucket:
```bash
azion delete storage object [flags]
```
| Flag | Curta | Tipo | Padrão | Descrição |
| --------------- | ----- | ------ | ------ | ----------------------------------- |
| `--bucket-name` | — | string | — | Nome do bucket que guarda o objeto. |
| `--object-key` | — | string | — | Chave do objeto a excluir. |
Este comando exclui o objeto `site/two.txt` de `my-bucket`:
```bash
azion delete storage object --bucket-name my-bucket --object-key site/two.txt -y
```
O comando confirma a exclusão:
```text
Object site/two.txt was deleted successfully
```
---
## Usar um arquivo JSON
`azion create storage` e `azion update storage` leem os atributos de um bucket ou de um objeto de um arquivo JSON com `--file`.
### Arquivo de bucket
Um arquivo de bucket traz `name` e `workloads_access`. Este arquivo cria um bucket chamado `my-other-bucket` com o nível de acesso `read_write`:
```json
{
"name": "my-other-bucket",
"workloads_access": "read_write"
}
```
Passe o arquivo para o comando de criação:
```bash
azion create storage bucket --file bucket-create.json
```
O comando confirma a criação:
```text
Bucket created successfully
```
Na atualização, o comando lê o bucket a alterar de `name`, então `--name` não é necessário. Este arquivo altera o nível de acesso de `my-other-bucket` para `read_only`:
```json
{
"name": "my-other-bucket",
"workloads_access": "read_only"
}
```
Passe o arquivo para o comando de atualização:
```bash
azion update storage bucket --file bucket-update.json
```
O comando confirma a atualização:
```text
Bucket updated successfully
```
### Arquivo de objeto
Um arquivo de objeto traz `source`, o caminho do arquivo local. O comando não lê a chave do arquivo, então passe `--bucket-name` e `--object-key` na linha de comando, na criação e na atualização. Este arquivo aponta para o conteúdo substituto de `site/two.txt`:
```json
{
"source": "./upload/two-v2.txt"
}
```
Passe o arquivo para o comando de atualização com o bucket e a chave:
```bash
azion update storage object --bucket-name my-bucket --object-key site/two.txt --file object-update.json
```
O comando confirma a atualização:
```text
Object updated successfully
```
---
## Recursos relacionados
- [Opções globais](/pt-br/documentacao/devtools/cli/globals.md): As opções que todo comando aceita, como `--format`, `--out` e `-y`.
- [Object Storage](/pt-br/documentacao/plataforma/object-storage.md): O que são um bucket e um objeto, e como uma aplicação os serve.
- [Azion CLI connector](/pt-br/documentacao/devtools/cli/recursos/connector.md): Os comandos que criam um connector do tipo `storage`, que aponta uma aplicação para um bucket.
- [Azion CLI origin](/pt-br/documentacao/devtools/cli/recursos/origin.md): Os comandos que apontam uma origem do tipo `object_storage` para um bucket com `--bucket`.