Visão Geral da CLI

A CLI do GuaraCloud (guara) permite fazer deploy, gerenciar e monitorar seus serviços diretamente pelo terminal. Foi projetada tanto para uso interativo durante o desenvolvimento quanto para uso automatizado em pipelines de CI/CD.

Instalação

Instale a CLI globalmente com npm:

npm install -g @guaracloud/cli

Após instalar, verifique que está funcionando:

guara --version

Início rápido

O que a CLI pode fazer

A CLI cobre todo o ciclo de vida dos seus serviços no GuaraCloud:

• Autenticação — login via navegador OAuth ou chave de API
• Gerenciamento de projetos — criar, listar e inspecionar projetos
• Gerenciamento de serviços — criar, iniciar, parar, reiniciar, excluir e inspecionar serviços
• Catálogo de serviços — navegar e implantar bancos de dados, caches e filas de mensagens gerenciados
• Deploys — disparar deploys, listar histórico de deployments, fazer rollback para versões anteriores
• Logs — consultar e acompanhar logs do serviço com filtros
• Sessões — executar comandos em containers (exec) e encaminhar portas para serviços privados (proxy)
• Escalabilidade — habilitar ou desabilitar autoscaling
• Variáveis de ambiente — definir, listar e remover variáveis (suporte a arquivos .env)
• Domínios — adicionar, listar e remover domínios customizados
• Configuração — gerenciar configurações da CLI como URL da API

Flags globais

Todo comando suporta essas flags:

Flag	Abreviação	Descrição
--json		Saída em JSON (ideal para scripts)
--quiet	-q	Suprime toda saída não essencial
--project <slug>	-p	Sobrescreve o projeto (ignora .guara.json)
--service <slug>	-s	Sobrescreve o serviço (ignora .guara.json)
--api-key <key>		Sobrescreve a chave de API para esta requisição
--api-url <url>		Sobrescreve a URL base da API
--yes	-y	Pula prompts de confirmação

Modos de saída

A CLI suporta três modos de saída para diferentes fluxos de trabalho:

• Interativo (padrão) — saída colorida com spinners, tabelas e prompts
• JSON (--json) — saída JSON estruturada para usar com jq ou outras ferramentas
• Silencioso (--quiet) — saída mínima com apenas o valor essencial (ID, slug ou URL)

# Modo interativo (padrão)
guara services list

# JSON para scripts
guara services list --json | jq '.[].slug'

# Silencioso para variáveis de shell
SERVICE_ID=$(guara deploy --quiet)

Resolução de contexto

A CLI resolve qual projeto e serviço operar usando esta ordem de prioridade:

1. Flags — --project e --service sempre têm prioridade
2. Variáveis de ambiente — GUARA_PROJECT e GUARA_SERVICE
3. Arquivo de vínculo — .guara.json no diretório atual (criado por guara link)
4. Prompt interativo — se nenhum dos anteriores estiver definido, a CLI solicita que você escolha

Próximos passos