Nesta página

Autenticação
guara login
guara logout
guara whoami
Contexto
guara link
guara unlink
guara open
Projetos
guara projects create
guara projects list
guara projects info
Serviços
guara services create
guara services list
guara services info
guara services start
guara services stop
guara services restart
guara services delete
guara services auto-deploy
guara services resize
guara services backups
guara services restore
guara services credentials
Catálogo de Serviços
guara catalog list
guara catalog info <slug>
guara catalog deploy [slug]
Deployments
guara deploy
guara deployments list
guara rollback
Logs
guara logs
guara build-logs
Sessões
guara exec
guara proxy
Escalabilidade
guara scale
Variáveis de Ambiente
guara env set
guara env list
guara env unset
Domínios
guara domains add
guara domains list
guara domains remove
Configuração
guara config get
guara config set
guara config list
guara config reset
Plataforma
guara status

Comandos da CLI

Referência completa de todos os comandos guara. Todos os comandos suportam --json, --quiet e as flags globais descritas na visão geral.

Autenticação

`guara login`

Autentica com o GuaraCloud.

guara login                          # OAuth pelo navegador (padrão)
guara login --api-key gk_live_abc123 # Login direto com chave de API
guara login --browser                # Forçar login pelo navegador

Flag	Descrição
`--api-key <key>`	Autentica diretamente com uma chave de API. Também lê `GUARA_API_KEY`.
`--browser`	Força o login OAuth pelo navegador.

`guara logout`

Faz logout e remove credenciais armazenadas do keychain e arquivo de configuração.

guara logout

`guara whoami`

Mostra o usuário autenticado.

guara whoami
guara whoami --json

A saída inclui nome, email, tier, role e status de founder.

Contexto

`guara link`

Vincula o diretório atual a um projeto do GuaraCloud e opcionalmente a um serviço. Cria um arquivo .guara.json.

guara link                                              # Seleção interativa
guara link --project meu-projeto                        # Vincular apenas ao projeto
guara link --project meu-projeto --service minha-api    # Vincular ao projeto + serviço
guara link --yes                                        # Sobrescrever vínculo existente sem prompt

Flag	Abreviação	Descrição
`--project <slug>`	`-p`	Slug do projeto (ignora seleção interativa).
`--service <slug>`	`-s`	Slug do serviço (ignora seleção interativa).

`guara unlink`

Remove o arquivo .guara.json do diretório atual.

guara unlink

`guara open`

Abre o projeto ou serviço no painel web (ou a URL ao vivo).

guara open                                                  # Abrir painel
guara open --url                                            # Abrir URL ao vivo do serviço
guara open --project meu-projeto --service minha-api --url  # Alvo explícito

Flag	Descrição
`--url`	Abre a URL ao vivo do serviço ao invés do painel.

Projetos

`guara projects create`

Cria um novo projeto.

guara projects create                                  # Prompt interativo
guara projects create --name meu-projeto               # Não interativo
guara projects create --name meu-projeto --json        # Saída JSON

Flag	Abreviação	Descrição
`--name <nome>`	`-n`	Nome do projeto.
`--description <texto>`	`-d`	Descrição do projeto.
`--region <região>`	`-r`	Região de deploy (padrão: `br-gru`).

`guara projects list`

Lista todos os projetos da sua conta.

guara projects list
guara projects list --json

`guara projects info`

Mostra detalhes de um projeto.

guara projects info --project meu-projeto
guara projects info --json

Serviços

`guara services create`

Cria um novo serviço em um projeto.

guara services create                                                  # Interativo
guara services create --name minha-api --build-method dockerfile --port 3000
guara services create --name minha-api --build-method buildpack --repo https://github.com/user/repo --port 8080

Flag	Abreviação	Descrição
`--name <nome>`	`-n`	Nome do serviço.
`--build-method <método>`	`-b`	Método de build: `dockerfile` ou `buildpack`.
`--repo <url>`		URL do repositório GitHub.
`--branch <branch>`		Branch do Git (padrão: main).
`--port <número>`		Porta do container.
`--root-dir <caminho>`		Diretório raiz para o build (padrão: `.`).
`--dockerfile-path <caminho>`		Caminho do Dockerfile relativo à raiz (padrão: `Dockerfile`).
`--build-cmd <comando>`		Comando de build customizado para builds buildpack em monorepos.
`--start-cmd <comando>`		Comando de start customizado para builds buildpack em monorepos.
`--public`		Torna o serviço acessível publicamente.
`--service-type <tipo>`		Tipo do serviço: `web` (padrão) ou `worker`. Workers executam em background sem endpoint HTTP.
`--auto-deploy`		Ativa deploys automáticos no push do GitHub (padrão: on). Use `--no-auto-deploy` para desabilitar.

`guara services list`

Lista todos os serviços de um projeto.

guara services list --project meu-projeto
guara services list --json

`guara services info`

Mostra detalhes de um serviço incluindo recursos, autoscaling e informações do repositório.

guara services info --project meu-projeto --service minha-api
guara services info --json

`guara services start`

Inicia um serviço parado.

guara services start --project meu-projeto --service minha-api

`guara services stop`

Para um serviço (escala para zero).

guara services stop --project meu-projeto --service minha-api

`guara services restart`

Dispara um restart com rolling update de um serviço.

guara services restart --project meu-projeto --service minha-api

`guara services delete`

Exclui um serviço. Requer confirmação.

guara services delete --project meu-projeto --service minha-api          # Confirmação interativa
guara services delete --project meu-projeto --service minha-api --yes    # Pular confirmação

`guara services auto-deploy`

Habilita ou desabilita deploys automáticos no push do GitHub.

guara services auto-deploy on --project meu-projeto --service minha-api
guara services auto-deploy off --project meu-projeto --service minha-api

Recebe on ou off como argumento posicional. Quando habilitado, pushes na branch configurada disparam um novo deployment automaticamente.

`guara services resize`

Redimensiona o armazenamento persistente de um serviço do catálogo. Funciona apenas para serviços do catálogo com a capacidade persistent-storage.

guara services resize --project meu-projeto --service meu-db --size 5

Flag	Descrição
`--size <gi>`	Novo tamanho do armazenamento em GiB (deve ser maior que o tamanho atual).

O armazenamento só pode ser expandido, nunca reduzido.

`guara services backups`

Lista snapshots de backup de um serviço do catálogo. Apenas para serviços com a capacidade backup.

guara services backups --project meu-projeto --service meu-db
guara services backups --json

`guara services restore`

Restaura um serviço do catálogo a partir de um snapshot de backup. Apenas para serviços com a capacidade backup.

guara services restore --project meu-projeto --service meu-db --snapshot snap-name
guara services restore --project meu-projeto --service meu-db --snapshot snap-name --async

Flag	Descrição
`--snapshot <nome>`	Nome do snapshot para restaurar (obrigatório).
`--async`	Não aguardar o serviço atingir o status `running`.

`guara services credentials`

Exibe as credenciais de conexão de um serviço do catálogo.

guara services credentials --project meu-projeto --service meu-db
guara services credentials --json

Exibe a string de conexão e os campos individuais (host, porta, usuário, senha).

Catálogo de Serviços

`guara catalog list`

Lista os serviços gerenciados disponíveis no catálogo (PostgreSQL, Redis, MongoDB, etc.).

guara catalog list
guara catalog list --json

Exibe nome, slug, categoria, versões suportadas e capacidades de cada serviço.

`guara catalog info <slug>`

Exibe os detalhes de uma definição de serviço do catálogo.

guara catalog info postgres
guara catalog info redis --json

Exibe versões, opções de armazenamento e configurações disponíveis.

`guara catalog deploy [slug]`

Implanta um serviço gerenciado do catálogo no seu projeto.

guara catalog deploy                                          # Seleção interativa
guara catalog deploy postgres                                 # Implantar PostgreSQL
guara catalog deploy redis --name meu-cache --version 7.4-alpine
guara catalog deploy postgres --name meu-db --storage 5 --config databaseName=myapp
guara catalog deploy postgres --async                         # Não aguardar status running

Flag	Descrição
`--name <nome>`	Nome do serviço.
`--version <tag>`	Tag da versão (ex: `17-alpine` para PostgreSQL).
`--storage <gi>`	Tamanho do armazenamento em GiB (padrão: 1).
`--config chave=valor`	Configuração específica do serviço (repetível, ex: `--config databaseName=app`).
`--async`	Não aguardar o serviço atingir o status `running`.

Deployments

`guara deploy`

Dispara um novo deployment para um serviço.

guara deploy                           # Deploy da branch padrão
guara deploy --branch develop          # Deploy de uma branch específica
guara deploy --commit abc123f          # Deploy de um commit específico
guara deploy --json                    # Saída JSON (aguarda até estado terminal)
guara deploy --quiet                   # Imprime apenas o ID do deployment

Flag	Abreviação	Descrição
`--branch <nome>`	`-b`	Branch do Git para deploy.
`--commit <sha>`	`-c`	SHA do commit específico para deploy.

No modo interativo, a CLI mostra um spinner que acompanha o deployment pelas etapas pending, building, deploying e healthy com um timer de tempo decorrido.

`guara deployments list`

Lista o histórico de deployments de um serviço.

guara deployments list
guara deployments list --project meu-projeto --service minha-api
guara deployments list --json

`guara rollback`

Faz rollback para um deployment anterior.

guara rollback                         # Seleção interativa dos deployments saudáveis
guara rollback --deployment <id>       # Rollback para um deployment específico
guara rollback --deployment <id> --json

Flag	Abreviação	Descrição
`--deployment <id>`	`-d`	ID do deployment para rollback.

Logs

`guara logs`

Visualiza logs do serviço com filtros e acompanhamento em tempo real.

guara logs                                                  # Últimas 100 linhas
guara logs --follow                                         # Acompanhar em tempo real
guara logs --lines 500 --level error                        # Últimas 500 linhas de erro
guara logs --since 1h --search "connection refused"         # Buscar na última hora
guara logs --since 2026-03-30T00:00:00Z --until 2026-03-30T12:00:00Z  # Intervalo de tempo

Flag	Abreviação	Descrição
`--follow`	`-f`	Acompanhar logs em tempo real (polling a cada 2.5s).
`--lines <n>`	`-n`	Número de linhas de log a buscar (padrão: 100).
`--since <tempo>`		Tempo inicial. Relativo (`1h`, `30m`, `2d`, `90s`) ou ISO8601.
`--until <tempo>`		Tempo final (ISO8601).
`--search <texto>`		Filtrar logs por texto de busca.
`--level <nível>`		Filtrar por nível de log: `trace`, `debug`, `info`, `warn`, `error`, `fatal`.

`guara build-logs`

Visualiza os logs de build de um deployment. Os logs de build mostram a saída da construção da imagem de container (builds Dockerfile ou buildpack).

guara build-logs                                             # Último deployment com logs de build
guara build-logs --deployment abc12345                       # Deployment específico
guara build-logs --follow                                    # Acompanhar em tempo real (para quando o build conclui)
guara build-logs --lines 500 --search "npm error"            # Últimas 500 linhas com "npm error"
guara build-logs --since 1h                                  # Logs de build da última hora

Flag	Abreviação	Descrição
`--deployment <id>`	`-d`	ID do deployment. Usa o último deployment `dockerfile` ou `buildpack` por padrão.
`--follow`	`-f`	Acompanhar logs de build em tempo real. Para automaticamente quando o deployment atinge um estado terminal.
`--lines <n>`	`-n`	Número de linhas de log a buscar (padrão: 100).
`--since <tempo>`		Tempo inicial. Relativo (`1h`, `30m`, `2d`, `90s`) ou ISO8601.
`--until <tempo>`		Tempo final (ISO8601).
`--search <texto>`		Filtrar logs de build por texto de busca.

Sessões

`guara exec`

Executa um comando ou inicia um shell interativo no container de um serviço em execução.

guara exec                                                   # Shell interativo (padrão: /bin/sh)
guara exec --shell /bin/bash                                 # Shell interativo com bash
guara exec -- ls -la /app                                    # Executar um comando e sair
guara exec --project meu-app --service web -- cat /etc/hostname

Flag	Descrição
`--shell <caminho>`	Shell a utilizar para sessões interativas (padrão: `/bin/sh`).

Quando nenhum argumento é passado após --, a CLI abre uma sessão PTY totalmente interativa com suporte a redimensionamento do terminal. Quando argumentos são fornecidos, o comando é executado uma vez e a CLI encerra com o código de saída do processo remoto.

`guara proxy`

Encaminha uma porta local para um serviço em execução, permitindo conectar-se a serviços privados a partir da sua máquina.

guara proxy                                                  # Porta local aleatória
guara proxy --local-port 8080                                # Porta local específica
guara proxy --project meu-app --service db --local-port 5432 # Conectar a um banco de dados
guara proxy --json                                           # Saída JSON com detalhes da conexão

Flag	Descrição
`--local-port <porta>`	Porta local para escutar (1–65535). Uma porta aleatória disponível é usada se não especificada.

A CLI exibe as informações de conexão (ex: Forwarding localhost:8080 → pod-name:3000) e permanece ativa até que você pressione Ctrl+C. A porta remota é derivada automaticamente da configuração do serviço.

Escalabilidade

`guara scale`

Habilita ou desabilita autoscaling para um serviço.

guara scale --autoscaling on
guara scale --autoscaling off --project meu-projeto --service minha-api
guara scale --autoscaling on --json

Flag	Descrição
`--autoscaling <on\|off>`	Habilita ou desabilita autoscaling (obrigatório).

Quando o autoscaling é habilitado, a CLI exibe o número máximo de réplicas. A CLI mostra o estado antes e depois.

Variáveis de Ambiente

`guara env set`

Define variáveis de ambiente. Dispara um rolling restart.

guara env set KEY=valor                                        # Definir uma variável
guara env set KEY1=valor1 KEY2=valor2                          # Definir múltiplas
guara env set --from-file .env                                 # Carregar de um arquivo .env
guara env set DATABASE_URL=postgres://... --project meu-projeto --service minha-api
guara env set NPM_TOKEN=xxx --build                            # Disponibilizar no build

Flag	Abreviação	Descrição
`--from-file <caminho>`		Ler pares KEY=VALUE de um arquivo `.env`.
`--build`	`-b`	Marca as variáveis como disponíveis durante o build da imagem (passadas como Docker `ARG`).

As variáveis são mescladas com as existentes. Para sobrescrever uma variável, defina-a novamente com o novo valor.

`guara env list`

Lista variáveis de ambiente de um serviço. A saída inclui uma coluna Build que indica se a variável está disponível durante o build da imagem.

guara env list --project meu-projeto --service minha-api
guara env list --json

`guara env unset`

Remove variáveis de ambiente. Dispara um rolling restart.

guara env unset DATABASE_URL                                   # Remover uma
guara env unset DATABASE_URL REDIS_URL                         # Remover múltiplas

Domínios

`guara domains add`

Adiciona um domínio customizado a um serviço.

guara domains add --domain api.meuapp.com --project meu-projeto --service minha-api

Flag	Descrição
`--domain <nome>`	Nome do domínio a adicionar (obrigatório).

A CLI exibe o alvo CNAME que você precisa configurar no seu provedor de DNS.

`guara domains list`

Lista domínios de um serviço.

guara domains list --project meu-projeto --service minha-api
guara domains list --json

`guara domains remove`

Remove um domínio customizado de um serviço. Requer confirmação.

guara domains remove --domain api.meuapp.com --yes

Flag	Descrição
`--domain <nome>`	Nome do domínio a remover (obrigatório).

Configuração

`guara config get`

Obtém um valor de configuração da CLI.

guara config get apiUrl

`guara config set`

Define um valor de configuração da CLI.

guara config set apiUrl https://api.staging.guaracloud.com

`guara config list`

Lista todos os valores de configuração da CLI.

guara config list
guara config list --json

`guara config reset`

Restaura a configuração da CLI para os valores padrão.

guara config reset

Plataforma

`guara status`

Mostra o status da plataforma GuaraCloud. Não requer autenticação.

guara status
guara status --json

Exibe o status geral da plataforma, saúde dos componentes individuais e quaisquer incidentes ativos.