CLI atlas
A CLI coda opera o Coda Cloud pelo terminal: login, contexto, deploy, status, logs, variáveis, segredos, domínios, tokens e shell. É um binário único, sem runtime para instalar, para Linux, macOS e Windows (amd64 e arm64). O código é aberto, sob a licença Apache-2.0.
A CLI chama a mesma API pública do portal, com as mesmas regras de autorização: o que o seu papel não permite no portal também não é permitido pela CLI.
Instalar
Homebrew (macOS e Linux)
brew install --cask coda-cloud/tap/coda
A fórmula fica no tap coda-cloud/homebrew-tap.
Scoop (Windows)
scoop bucket add coda https://github.com/coda-cloud/scoop-bucket
scoop install coda
Download direto
Cada versão é publicada nos releases do repositório coda-cloud/coda-cli no GitHub, com um arquivo por alvo:
| Sistema | amd64 | arm64 |
|---|---|---|
| Linux | atlas_<versão>_linux_amd64.tar.gz | atlas_<versão>_linux_arm64.tar.gz |
| macOS | atlas_<versão>_darwin_amd64.tar.gz | atlas_<versão>_darwin_arm64.tar.gz |
| Windows | atlas_<versão>_windows_amd64.zip | atlas_<versão>_windows_arm64.zip |
Cada release traz também checksums.txt (SHA-256 de todos os arquivos), a assinatura checksums.txt.sig e um SBOM SPDX (.spdx.json) por arquivo.
Depois de extrair, coloque o binário coda (ou atlas.exe) num diretório do PATH e confira com coda version.
Verificar o download
Verifique sempre o checksum e a assinatura antes de usar um binário baixado direto. Você precisa do cosign e da chave pública abaixo, salva como coda-cli.pub.
# 1. o checksums.txt foi assinado pelo Coda Cloud
cosign verify-blob --key coda-cli.pub --signature checksums.txt.sig checksums.txt
# 2. o arquivo baixado corresponde ao checksums.txt
sha256sum --ignore-missing -c checksums.txt
No macOS, troque sha256sum por shasum -a 256. As duas verificações precisam passar. Se alguma falhar, não use o binário.
Chave pública
A chave pública de assinatura da CLI será publicada aqui junto com a primeira release (cli-v0.1.0). Até lá, não há binário oficial para verificar. Não use chaves obtidas de outras fontes.
-----BEGIN PUBLIC KEY-----
(a chave será publicada com a primeira release)
-----END PUBLIC KEY-----
Primeiro uso
Apontar para a plataforma
O perfil guarda os endereços da API e do login. Configure uma vez:
coda use --api-url https://api.<domínio> --auth-url https://auth.<domínio>/realms/atlas
Os perfis ficam em ~/.config/coda/config.toml. Para manter mais de um ambiente, dê nome ao perfil (coda use prod --api-url …) e troque com coda use <perfil> ou --profile <perfil>.
Login interativo
coda login
O login usa o device flow:
- A CLI mostra um código e uma URL de verificação e tenta abrir o navegador (
--no-browsersó mostra). - No navegador, entre no Coda Cloud, confira que a tela mostra Coda CLI e o mesmo código e aprove. O código vale por 10 minutos.
- A CLI mostra "Conectado como <seu e-mail>".
Nunca aprove um código que você não gerou. Se o código expirar ou for negado, a CLI termina com o código de saída 4 e não guarda nada.
A credencial fica no chaveiro do sistema operacional (Keychain, Credential Manager ou Secret Service) e é renovada sozinha. Sem chaveiro disponível, como num contêiner, a CLI grava em ~/.config/coda/credentials com permissão 0600 e mostra um aviso. A sessão da CLI expira depois de 7 dias sem uso e dura no máximo 30 dias. Quando as suas sessões são revogadas, a CLI pede um novo coda login.
coda logout apaga a credencial guardada do perfil.
Login por token (CI e scripts)
Em pipelines, use um token de API, de preferência de uma conta de serviço. Há duas formas, e o token nunca vai em argumento de linha de comando:
# variável de ambiente: tem precedência sobre a credencial guardada
export CODA_TOKEN="$TOKEN_DO_SEGREDO_DA_PIPELINE"
# ou: guardar o token no perfil, lido do stdin
printf '%s' "$TOKEN" | coda login --with-token
Quem sou eu
coda whoami
Mostra o usuário autenticado e as organizações com o seu papel em cada uma.
Contexto: organização, projeto, ambiente e aplicação
Quase todo comando age sobre uma aplicação de um ambiente. O alvo vem de três lugares, nesta ordem de precedência:
- Flags:
--org,--project,--enve--app(slug ou id). - Vínculo do diretório: o arquivo
.atlas/project.jsongravado porcoda link, procurado no diretório atual e nos superiores. - Perfil: os padrões gravados por
coda use.
# padrões do perfil
coda use --org acme --project web --env production
# vincular o repositório a uma aplicação (pergunta o que faltar)
coda link --org acme --project web --env production --app api
O .atlas/project.json guarda só ids e slugs, nunca credenciais, e pode ser versionado com o código.
Comandos
| Comando | O que faz |
|---|---|
coda orgs list|get|create|delete | Organizações |
coda projects list|get|create|delete | Projetos da organização |
coda envs list|get|create|delete | Ambientes do projeto |
coda apps list|get|create|delete | Aplicações do ambiente |
coda deploy --image <imagem>@sha256:<digest> [--wait] [--timeout 15m] | Cria um deployment. Com --wait, acompanha até RUNNING (código 0) ou FAILED (código 1, com o motivo) |
coda status | Estado da aplicação, versão atual e instâncias |
coda rollback [--to <versão>] | Volta para um deployment anterior que chegou a RUNNING (padrão: o mais recente antes do atual) |
coda scale <instâncias> | Muda o número de instâncias |
coda logs [--follow] [--lines 100] [--instance <id>] | Últimas linhas de log; --follow acompanha até Ctrl+C |
coda env list|set NOME=valor…|unset NOME… | Variáveis não secretas |
coda secrets list|set NOME|rm NOME | Segredos. list mostra só nomes, versões e datas |
coda domains list|add <domínio>|verify <domínio> | Domínios próprios; add mostra o registro TXT de verificação |
coda tokens list|create|revoke | Seus tokens de API (só com login interativo) |
coda exec [--instance <id>] [-t] -- <comando> [args…] | Executa um comando numa instância (veja Terminal e exec) |
coda shell [--instance <id>] | Abre um shell interativo numa instância |
coda mcp serve|login|config claude-code|vscode|cursor | Servidor MCP local para assistentes de IA: ponte stdio com o servidor remoto, login próprio e trechos de configuração |
coda version | Versão da CLI |
Use coda <comando> --help para ver todas as flags.
Segredos só pelo stdin
O valor de um segredo nunca é aceito como argumento, para não ficar no histórico do shell nem na lista de processos:
printf '%s' "$DB_PASSWORD" | coda secrets set DB_PASSWORD
coda secrets set DB_PASSWORD # sem stdin: pede o valor sem eco
coda secrets set DB_PASSWORD=s3cr3t é recusado com o código de saída 2. Nenhum comando imprime o valor de um segredo.
Operações destrutivas
delete, rm e revoke pedem confirmação no terminal. Sem terminal (pipeline), passe --yes; sem ele, nada é excluído e a CLI termina com o código 2.
Saída para scripts
| Flag | Efeito |
|---|---|
--output table|json|yaml (-o) | Formato da saída. O JSON segue o contrato da API, com campos em camelCase |
--all | Percorre todas as páginas de uma listagem (páginas de até 100 itens) |
--limit, --cursor | Uma página específica de uma listagem |
--debug | Mostra as requisições no stderr, com o token mascarado (Bearer atl_sat_****) |
coda apps list --output json --all | jq -r '.[].slug'
Códigos de saída
| Código | Significado | Exemplos |
|---|---|---|
| 0 | Sucesso | |
| 1 | Erro da operação | Deployment terminou FAILED |
| 2 | Uso inválido | Flag errada, valor recusado pela validação da API, segredo como argumento, falta --yes, CLI abaixo da versão mínima |
| 3 | Não encontrado | Recurso inexistente ou de outra organização |
| 4 | Não autenticado | Sem login, token expirado ou revogado |
| 5 | Sem permissão | Papel ou escopo insuficiente, recurso fora do plano |
| 6 | Limite ou quota | Quota do plano esgotada, rate limit, organização suspensa |
| 7 | Conflito | Estado mudou entre a leitura e a escrita |
coda exec termina com o código de saída do processo remoto.
Versão da CLI
A CLI envia User-Agent: atlas-cli/<versão> (<sistema>/<arquitetura>) e consulta GET /api/v1/meta/cli, que informa a versão mínima suportada e a mais recente:
- Abaixo da mínima: comandos que alteram estado são recusados com o código 2 e a instrução de atualização. Comandos de leitura funcionam com aviso.
- Abaixo da mais recente: um aviso no stderr, no máximo uma vez por dia.
Para atualizar, use brew upgrade atlas, scoop update atlas ou baixe a nova versão.
Variáveis de ambiente
| Variável | Uso |
|---|---|
CODA_TOKEN | Token de API; tem precedência sobre a credencial guardada |
CODA_PROFILE | Perfil a usar |
CODA_API_URL, CODA_AUTH_URL | Endereços da API e do login, no lugar dos do perfil |
CODA_CA_FILE | CA adicional em PEM |
CODA_CONFIG_DIR | Diretório de configuração (padrão ~/.config/coda) |
CODA_CREDENTIAL_STORE | keyring ou file, para forçar onde a credencial é guardada |
Exemplo de pipeline
# CODA_TOKEN vem de um segredo da pipeline: token atl_sat_ de uma conta de serviço
# com o modelo "Deploy por CI".
script:
- coda deploy --org acme --project web --env production --app api \
--image registry.example/web@sha256:$DIGEST --wait
A auditoria registra a conta de serviço como autora, com o canal service-account e o cliente atlas-cli.