Autenticação da CLI

A CLI do GuaraCloud suporta dois métodos de autenticação: login OAuth pelo navegador para uso interativo, e chaves de API para scripts e pipelines de CI/CD.

Login pelo navegador

A forma mais simples de autenticar é com o fluxo de login pelo navegador:

guara login

Isso abre seu navegador padrão na página de login do GuaraCloud. Após fazer login, a CLI recebe uma chave de API automaticamente e a armazena com segurança no keychain do sistema (macOS Keychain, Windows Credential Manager ou Linux Secret Service). Se o keychain não estiver disponível, a chave é armazenada em um arquivo de configuração local.

$ guara login
Opening browser to authenticate...
  https://api.guaracloud.com/v1/auth/cli-login?callback=...
✓ Authenticated as voce@exemplo.com
  API key stored in system keychain.

Você pode forçar o fluxo pelo navegador explicitamente com:

guara login --browser

Login com chave de API

Você também pode autenticar diretamente com uma chave de API. Gere uma chave nas suas configurações de conta:

guara login --api-key gk_live_abc123def456

A CLI valida a chave chamando a API e depois a armazena no keychain do sistema.

Variáveis de ambiente

Para pipelines de CI/CD e ambientes não interativos, use variáveis de ambiente ao invés de guara login:

Variável	Descrição
GUARA_API_KEY	Chave de API para autenticação. Quando definida, a CLI ignora completamente o keychain.
GUARA_API_URL	Sobrescreve a URL base da API. Útil para apontar para um ambiente de staging.
GUARA_PROJECT	Slug do projeto padrão. Equivalente a --project.
GUARA_SERVICE	Slug do serviço padrão. Equivalente a --service.

# Autenticar e fazer deploy em uma única linha
GUARA_API_KEY=gk_live_xxxxx guara deploy --project meu-projeto --service minha-api # gitleaks:allow

Usando um ambiente de staging

Para apontar a CLI para uma instância de staging do GuaraCloud:

# Via variável de ambiente
export GUARA_API_URL=https://api.staging.guaracloud.com
guara whoami

# Via flag
guara whoami --api-url https://api.staging.guaracloud.com

# Via config (persistido)
guara config set apiUrl https://api.staging.guaracloud.com

Verificando autenticação

Verifique com qual conta você está logado:

guara whoami

✓ Authenticated as voce@exemplo.com

  Account
  Name        Seu Nome
  Email       voce@exemplo.com
  Tier        pro
  Role        owner
  Founder     No
  ID          abc123...

Fazendo logout

Remova as credenciais armazenadas:

guara logout

Isso remove a chave de API do keychain do sistema e de qualquer arquivo de configuração local.

Armazenamento de credenciais

A CLI armazena credenciais usando esta prioridade:

1. Keychain do sistema (preferido) — macOS Keychain, Windows Credential Manager ou Linux Secret Service via a biblioteca keytar
2. Arquivo de configuração (fallback) — ~/.config/guara/config.json com permissões de arquivo restritas

O keychain é sempre tentado primeiro. O arquivo de configuração é usado apenas quando o keychain não está disponível (por exemplo, em um servidor headless sem servidor de display).

Prioridade de autenticação

Ao resolver a chave de API, a CLI verifica estas fontes em ordem:

1. Flag --api-key na linha de comando
2. Variável de ambiente GUARA_API_KEY
3. Keychain do sistema
4. Arquivo de configuração (~/.config/guara/config.json)

A primeira chave encontrada é utilizada. Se nenhuma chave for encontrada, comandos que requerem autenticação solicitarão que você faça login (ou falharão em modo não interativo).