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

# CLI

> basaltic, a interface de linha de comando para a plataforma.

`basaltic` é o cliente de linha de comando. É o caminho mais curto para conduzir a plataforma a partir de um terminal ou de um trabalho de CI e fala a mesma API que os SDKs.

<a id="install" />

## Instalar

```bash theme={null}
curl -fsSL https://get.basaltic.sh/cli | sh
```

O script escolhe a compilação para sua plataforma, verifica-a contra a soma de verificação publicada com a versão, e instala em `/usr/local/bin` quando isso for gravável ou `~/.local/bin` caso contrário. Leia-o primeiro se preferir — ele é [`install.sh`](https://github.com/basaltic-sh/cli/blob/main/install.sh) no repositório, e esse URL serve o mesmo arquivo.

```bash theme={null}
BASALTIC_INSTALL_DIR=~/bin  curl -fsSL https://get.basaltic.sh/cli | sh
BASALTIC_VERSION=0.1.1      curl -fsSL https://get.basaltic.sh/cli | sh
```

Compilações para Linux, macOS e Windows em amd64 e arm64 estão na página [releases](https://github.com/basaltic-sh/cli/releases), e `go install github.com/basaltic-sh/cli@latest` funciona se você tiver o Go.

Para atualizar:

```bash theme={null}
basaltic upgrade          # install the latest version
basaltic upgrade --check  # only say whether one exists
```

A CLI menciona quando uma versão mais recente está disponível e nunca a instala para você. O aviso vai para stderr, somente em um terminal, e nunca quando a saída é JSON ou YAML — então ele não pode aterrissar em algo sendo analisado. `BASALTIC_NO_UPDATE_CHECK=1` desliga-o.

<a id="command-shape" />

## Forma de comando

```
basaltic <service> <resource> <verb> [flags]
```

```bash theme={null}
basaltic compute instance list
basaltic compute instance start i-abc123
basaltic network vpc create --name prod --cidr-ipv4 10.0.0.0/16
basaltic storage volume list
basaltic loadbalancer listener create lb-1 --port 443
```

Os argumentos posicionais são os identificadores do recurso, na ordem em que o caminho da API os leva. Tudo o resto é uma bandeira.

Nomes de serviços mais longos têm aliases curtos, e cada recurso aceita o plural: `basaltic lb` é `basaltic loadbalancer`, `basaltic net` é `basaltic network`, e `basaltic compute instances list` é `basaltic compute instance list`. Os formulários abaixo são os que devem ser preenchidos.

Um serviço com um único recurso do mesmo nome deixa cair a palavra do meio: `basaltic certificate list`, não `basaltic certificate certificate list`.

`basaltic --help` lista os serviços; `basaltic <service> --help` e `basaltic <service> <resource> --help` descem a partir daí.

<a id="authenticating" />

## A autenticar

A descoberta de regiões funciona antes de você entrar:

```bash theme={null}
basaltic catalog region list
basaltic catalog region get sa-saopaulo-1
```

Esses comandos usam o catálogo público [region](/pt/regions) sem enviar credenciais ou uma seleção de conta. Faça login para gerenciar seus recursos.

As configurações estão em um **perfil** em `~/.config/basaltic/config.yaml`. Tokens não: eles são escritos em `~/.config/basaltic/credentials.yaml`, modo 0600, então um arquivo de configuração permanece seguro para copiar entre máquinas ou fazer check-in em arquivos de ponto.

```bash theme={null}
basaltic login           # browser sign-in, as you
basaltic auth status     # who you are, which org, when it expires
basaltic auth logout     # revoke the session and delete the credential
```

`basaltic login` faz o login como uma **pessoa** — ele imprime uma URL onde você aprova a CLI e escolhe uma organização, mostra um código para colar de volta no terminal e armazena um token de curta duração que age como você. Isso é o que permite que você crie uma organização, aceite um convite ou mude de organização a partir da CLI; uma conta de serviço não pode fazer nada disso. O navegador não precisa estar na mesma máquina, então isso funciona via SSH. Veja [login como você mesmo](/pt/authentication#signing-in-as-yourself).

Os comandos de espaço de trabalho gerenciam recursos da organização, como usuários, grupos, contas e políticas da organização. Os comandos do IAM gerenciam funções, contas de serviço, políticas e sessões na conta selecionada. Estes são domínios de política separados, mesmo que ambos os serviços sejam globais.

Um login pessoal não concede automaticamente acesso a recursos de conta a uma pessoa, incluindo o proprietário da organização. Use uma função atribuída e a API AssumeRole para trabalhar com contas. Alterar a conta de um perfil sozinho não pode alterar o escopo de conta de uma credencial. Consulte [acesso à conta](/pt/workspace/accounts).

Para um programa que tem que ser executado sem você, use uma chave de acesso de uma [conta de serviço](/pt/authentication#getting-credentials) em vez disso:

```bash theme={null}
basaltic auth login --api-key ACCESS_KEY_ID:SECRET_ACCESS_KEY
```

Isso armazena a chave no perfil ativo e a verifica antes de relatar o sucesso. O par de chaves permanece como sua única credencial de longa duração — a CLI a troca por um token de curta duração em cada execução e o armazena em cache separadamente.

<Tip>
  Prefere armazenar uma chave sobre passar `--api-key` em cada invocação. O sinalizador coloca o segredo no seu histórico de shell e na lista de processos de cada usuário na máquina.
</Tip>

<a id="output" />

## Saída

`--output text` é o padrão e imprime tabelas. `--output json` e `--output yaml` imprimem os próprios nomes de campo da API, para pipeline.

```bash theme={null}
basaltic compute instance list -o json | jq -r '.[].id'
basaltic compute instance list --no-headers | awk '{print $1}'
```

## Paging

Os comandos de lista retornam uma página e dizem quando há mais. `--all` vai a cada página:

```bash theme={null}
basaltic compute instance list --limit 50
basaltic compute instance list --all
```

<a id="creating-things" />

## Criando coisas novas

Campos escalares são flags. Qualquer coisa estruturada usa JSON, porque um objeto aninhado não tem representação plana honesta:

```bash theme={null}
basaltic compute instance create \
  --name web-01 \
  --flavor f-1 \
  --image debian-13 \
  --networks '[{"subnet":"<subnet-id>","floating_ip_assignment":"ipv4"}]'
```

Para qualquer coisa maior, `--from-file` leva o corpo inteiro como JSON ou YAML, e as bandeiras substituem os campos individuais dele:

```bash theme={null}
basaltic compute instance create --from-file instance.yaml --name web-02
```

O arquivo carrega os campos necessários — `networks` entre eles — e as bandeiras ao lado dele substituem chaves individuais.

<a id="retrying-a-create" />

### Retentando uma criação

Uma criação que tenha expirado pode já ter sido bem sucedida, então a CLI não irá repetir uma por conta própria. Dê uma chave e ele se torna seguro para tentar novamente — a plataforma retorna o resultado original em vez de criar um segundo recurso:

```bash theme={null}
basaltic compute instance create --name web-01 --flavor f-1 \
  --image debian-13 --networks '[{"subnet":"<subnet-id>"}]' \
  --idempotency-key "$(uuidgen)"
```

<a id="global-flags" />

## Bandeiras globais

| Bandeira da Alemanha | Objectivo |
| - | - |
| `-p, --profile` | Usar um perfil específico da configuração |
| `--region` | Região-alvo, por ex. `sa-saopaulo-1` |
| `-o, --output` | Formato de saída: `text`, `json`, ou `yaml` |
| `--no-headers` | Omitir a linha de cabeçalho em tabelas de texto |
| `--account-id` | Agir contra outra conta à qual você tem acesso |
| `--api-key` | `ACCESS_KEY_ID:SECRET_ACCESS_KEY`, sobrepondo env e config |
| `-v, --version` | Imprimir a versão |

`--output json` é o que se deve procurar em scripts.

<Note>
  `--account-id` é necessário para chegar a outra conta que você está autorizado. Sem ele, os recursos dessa conta respondem "não encontrado" em vez de "não permitido" — uma conta na qual você não está atuando é aquela cujos recursos você não pode ver.
</Note>

As variáveis de ambiente substituem o perfil: `BASALTIC_API_KEY`, `BASALTIC_REGION`, `BASALTIC_ACCOUNT_ID`, `BASALTIC_PROFILE`. Um sinalizador substitui ambos.

<a id="configuration" />

## Configuração

```bash theme={null}
basaltic config list                # the configured profiles
basaltic config get <key>           # print one value
basaltic config set <key> <value>   # write one value on the active profile
basaltic config use <profile>       # make a profile the default
basaltic config path                # where the files live
```

As chaves são `region`, `api_key`, `account_id` e `domain`. Use `--profile` para escrever em um perfil diferente do ativo:

```bash theme={null}
basaltic config set region sa-saopaulo-1
basaltic config set region sa-saopaulo-1 --profile staging
```

Os arquivos estão em `~/.config/basaltic/`, honrando `XDG_CONFIG_HOME`.

<a id="serial-console" />

## Consola de série

```bash theme={null}
basaltic compute instance serial-console i-abc123
```

Abre um console serial interativo. O terminal é colocado em modo raw, então cada tecla chega ao convidado — incluindo `Ctrl-C`, que é geralmente o que você quer. Pressione <kbd>Ctrl-]</kbd> para desconectar.

Esse é um terminal ao vivo, não um log. Para o que a instância já imprimiu:

```bash theme={null}
basaltic compute instance console-output i-abc123
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.