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]
guara catalog query
guara catalog schema
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 de observabilidade
guara services metrics
guara services traces list
guara services traces get <traceId>
guara projects map
guara projects observatory
Cron Workers
guara crons list
guara crons info <slug>
guara crons create -f <file>
guara crons update <slug> -f <file>
guara crons delete <slug>
guara crons suspend <slug>
guara crons resume <slug>
guara crons trigger <slug>
guara crons runs <slug>
Profiling
guara services profiles get

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`.

`guara catalog query`

Executa uma única instrução SQL somente leitura em um serviço gerenciado de PostgreSQL ou MySQL do catálogo. O SQL pode vir inline, de um arquivo ou pelo stdin.

guara catalog query --query "SELECT id, email FROM users LIMIT 10"
guara catalog query --file ./reports/active.sql --format csv > active.csv
cat ./reports/active.sql | guara catalog query --service my-postgres
guara catalog query --query "SELECT count(*) FROM users" --quiet     # imprime o total de linhas

Flag	Atalho	Descrição
`--query <sql>`		Instrução SQL inline (mutuamente exclusiva com `--file`).
`--file <caminho>`	`-f`	Lê o SQL de um arquivo (use `-` para ler do stdin).
stdin (auto)		Quando nenhum flag é passado e o stdin não é TTY, o SQL é lido do pipe.
`--format <table\|csv\|tsv>`		Formato de saída quando o stdout é TTY (padrão: `table`).
`--no-csv-safe`		Desativa a neutralização de injeção de fórmula em CSV/TSV.

A plataforma aplica timeout de 30 s por instrução, limite de 50 KB por consulta, teto de 1 000 linhas por resposta (truncated: true quando excede) e até 3 consultas simultâneas por usuário × serviço. Veja Consulta SQL para o modelo completo de segurança e os códigos de erro.

`guara catalog schema`

Inspeciona o esquema vivo de um serviço gerenciado de PostgreSQL ou MySQL do catálogo.

guara catalog schema
guara catalog schema --filter users          # filtro por substring (case-insensitive)
guara catalog schema --json | jq .
guara catalog schema --quiet                 # um nome de tabela por linha

Flag	Descrição
`--filter <substr>`	Inclui apenas tabelas cujo nome contém a substring.

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`, `unknown`.

`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.

Comandos de observabilidade

As superfícies de observabilidade da GuaraCloud permitem acompanhar o uso de recursos em tempo real e inspecionar traces distribuídos diretamente do terminal. Esses comandos respeitam o seu plano: a API limita janelas temporais, retenção e quantidade de spans conforme a sua assinatura, e a CLI mostra a janela visível que o servidor de fato retornou.

`guara services metrics`

Mostra o uso atual de recursos (CPU, memória, rede, pods, armazenamento e tráfego) de um serviço. Use --watch para atualizar no mesmo lugar a cada --interval segundos (padrão 5, mínimo 2).

guara services metrics
guara services metrics --metric cpu --watch
guara services metrics --history 6h --json | jq .

Flag	Descrição
`-m, --metric <nome>`	Foca em uma única métrica. Aceita `cpu`, `memory`, `network`, `requests`, `response-time` ou `storage`.
`-w, --watch`	Atualiza no mesmo lugar a cada `--interval` segundos.
`-i, --interval <segundos>`	Intervalo de polling em segundos (padrão `5`, mínimo `2`).
`--history <janela>`	Janela do sparkline. Aceita `15m`, `30m`, `1h` ou `6h` (padrão `1h`).
`--no-history`	Ignora o painel de sparkline e busca apenas o snapshot atual.
`--no-pods`	Ignora a tabela de pods.

Os sparklines renderizam a última janela definida em --history. O resultado pode ser limitado pelo plano — quando isso ocorre, a resposta inclui a janela visível efetiva. --json emite um objeto NDJSON por tick, ideal para encadear com jq ou um coletor sidecar. Em modo --quiet, o comando imprime apenas o valor atual de CPU em millicores, facilitando a integração com pipelines de shell.

`guara services traces list`

Lista os traces OpenTelemetry recentes de um serviço. Os filtros restringem por latência, status, nome de operação, serviço participante ou classe de status HTTP.

guara services traces list
guara services traces list --status error --min-duration-ms 500
guara services traces list --quiet | xargs -I{} guara services traces get {}

Flag	Descrição
`-t, --time-range <janela>`	Janela de busca. Aceita `15m`, `30m`, `1h`, `6h`, `24h` ou `7d` (padrão `15m`).
`-n, --limit <n>`	Máximo de linhas (1-100, padrão `20`).
`--status <estado>`	Filtro de status. Aceita `ok`, `error` ou `all` (padrão `all`).
`--operation <trecho>`	Casamento por substring no nome da operação.
`--service-name <nome>`	Filtra pelo `service.name` de qualquer span participante do trace.
`--min-duration-ms <ms>`	Latência mínima.
`--max-duration-ms <ms>`	Latência máxima.
`--http-status-class <classe>`	Classe de status HTTP. Aceita `2xx`, `4xx` ou `5xx`.
`-w, --watch`	Acompanha novos traces conforme chegam.
`-i, --interval <segundos>`	Intervalo de polling em segundos (padrão `5`, mínimo `2`).
`--ascii`	Usa apenas glifos ASCII (sem Unicode). Também ativado por `NO_UNICODE=1`.

--watch faz polling no endpoint de traces na cadência definida por --interval. --quiet emite um trace_id por linha, encaixando-se diretamente em xargs guara services traces get.

`guara services traces get <traceId>`

Renderiza um único trace como uma cascata ASCII. Cada linha mostra serviço · operação · barra posicionada · duração · status. Como traces são imutáveis, este comando nunca aceita --watch.

guara services traces get 4f2ab91d
guara services traces get 4f2ab91d --errors --depth 3
guara services traces get 4f2ab91d --json | jq .

Flag	Descrição
`--depth <n>`	Limita a profundidade dos spans aninhados exibidos.
`--errors`	Destaca apenas spans com erro; os demais aparecem esmaecidos.
`--width <colunas>`	Sobrescreve a largura da cascata (padrão: número de colunas do terminal).

Use --json para emitir a TraceDetailResponse bruta e alimentar ferramentas downstream. Em modo --quiet, o comando imprime uma linha serviço::operação duração_ms status por span.

`guara projects map`

Renderiza a topologia dos serviços do projeto no terminal — cada serviço como uma linha em uma tabela de nodes e cada aresta entre serviços em uma tabela de edges. Tem o alias guara projects topology.

guara projects map
guara projects map --graph
guara projects map --watch --interval 15 --time-range 1h

Flag	Descrição
`-t, --time-range <janela>`	Janela de busca. Aceita `15m`, `30m`, `1h`, `6h`, `24h` ou `7d` (padrão `15m`).
`-g, --graph`	Renderiza um grafo ASCII em camadas (best-effort) em vez da tabela de edges.
`--service <id>`	Destaca um serviço específico (por UUID) ao desenhar o grafo.
`-w, --watch`	Atualiza no mesmo lugar a cada `--interval` segundos.
`-i, --interval <segundos>`	Intervalo de polling em segundos (padrão `15`, mínimo `5`).

A renderização padrão usa duas tabelas (nodes + edges) porque cabe em qualquer largura de terminal e mantém latência e taxa de erro legíveis. --graph muda para um diagrama ASCII em camadas e cai automaticamente de volta para a tabela de edges quando o layout não couber na largura do terminal.

As edges seguem a mesma distinção entre paired (HTTP, via service-graphs do Tempo) e l4_flow (TCP, via fluxos de kernel do Beyla) que o dashboard usa — edges paired carregam percentis completos de latência e taxa de erro, enquanto edges l4_flow mostram uma célula tracejada nessas colunas e um sufixo de bytes/s na coluna de requisições. Veja Topologia e Observatório para o modelo completo.

--quiet imprime uma linha source_slug -> target_slug por edge, ideal para compor com awk, comm ou xargs em scripts.

`guara projects observatory`

Renderiza um centro de controle ao vivo do projeto: barra de saúde agregada, feed corrido de eventos e linha do tempo de traces ao vivo. Tem o alias guara projects obs. O modo watch é o padrão; use --no-watch para um snapshot único.

guara projects observatory
guara projects observatory --no-watch --json
guara projects observatory --interval 10 --traces 30

Flag	Descrição
`--no-watch`	Imprime um único snapshot e sai (use em scripts e checks de CI).
`-i, --interval <segundos>`	Intervalo de polling em segundos (padrão `5`, mínimo `2`).
`--traces <n>`	Linhas de trace no painel ao vivo (padrão `10`, máximo `30`).
`--events <n>`	Linhas de evento no feed (padrão `15`, máximo `60`).
`--no-health`	Esconde a barra de saúde do projeto.
`--no-events`	Esconde o painel de eventos.
`--no-traces`	Esconde o painel de traces ao vivo.

Cada frame mostra o cabeçalho do projeto, a barra de saúde em uma linha (servicos saudaveis · req/min · err · latencia media · p99), o feed de eventos (erros, deploys, alertas com timestamps relativos) e a linha do tempo de traces ao vivo (mais novos primeiro, com status ok/err e duração por trace). --no-watch --json emite um único snapshot NDJSON e sai — combine com jq para checks de prontidão automatizados. --quiet --no-watch imprime apenas a linha da barra de saúde, ideal para encaixar em pipelines de shell.

Cron Workers

O tópico crons gerencia cron workers — disparadores agendados que executam requisições HTTP, publicam em filas ou notificam bancos a partir de uma expressão cron. Todos os comandos são por projeto e aceitam as mesmas flags globais --project / --json / --quiet que os demais.

`guara crons list`

Lista os cron workers de um projeto.

guara crons list
guara crons list --status active
guara crons list --watch --interval 10
guara crons list --json | jq .

Flag	Abreviação	Descrição
`--status <estado>`		Filtra pelo status. Aceita `active` ou `suspended`.
`-w, --watch`	`-w`	Faz polling repetido e re-renderiza até ser interrompido.
`-i, --interval <segundos>`	`-i`	Intervalo de polling em segundos (padrão `5`, mínimo `2`).
`--ascii`		Usa apenas glifos ASCII (sem Unicode). Também ativado por `NO_UNICODE=1`.

Saída de exemplo:

 SLUG          STATUS     SCHEDULE        TZ                  LAST RUN
 hourly        active     0 * * * *       UTC                 ●
 nightly       active     0 3 * * *       America/Sao_Paulo   ●
 cleanup       suspended  */15 * * * *    UTC                 ✕

A coluna LAST RUN é um único dot de status — verde ● para o último run com sucesso, vermelho ✕ para o último que falhou, amarelo ◐ enquanto ainda está executando. Com --watch, a tabela é redesenhada no lugar a cada tick. Com --watch --json, cada tick emite uma linha NDJSON pronta para jq.

`guara crons info <slug>`

Mostra os detalhes de um cron worker, incluindo destino resolvido e template de payload.

guara crons info hourly
guara crons info hourly --json

Flag	Descrição
`--ascii`	Usa apenas glifos ASCII (sem Unicode). Também ativado por `NO_UNICODE=1`.

Saída de exemplo (visão de card no TTY):

┌─ hourly ───────────────────────────────────  active ─┐
│ Name         Hourly cleanup job                      │
│ Schedule     0 * * * *  ·  UTC                       │
│ Destination  POST /jobs/cleanup-stale-uploads        │
│              Authorization: ***                      │
│              X-Job-Source: cron                      │
│ Timeout      30s  ·  Max retries 3                   │
│ Payload      {                                       │
│                "job": "rotate-uploads",              │
│                "max_age_hours": 24                   │
│              }                                       │
└──────────────────────────────────────────────────────┘

Headers HTTP sensíveis (Authorization, Cookie, X-API-Key, X-Auth-Token) são redatados como ***. Use --json para obter o CronWorkerResponse cru e alimentar ferramentas downstream.

`guara crons create -f <file>`

Cria um cron worker a partir de um arquivo de spec YAML ou JSON.

guara crons create -f cron.yaml
guara crons create -f cron.json --json
guara crons create -f cron.yaml --project meu-projeto

Flag	Abreviação	Descrição
`-f, --file`	`-f`	Caminho do arquivo de spec (YAML por padrão, JSON detectado pela extensão `.json`).

O arquivo de spec espelha o body da API — veja Criar um Cron Worker → Pela CLI para um exemplo completo por destination_type. Erros de validação (HTTP 400 com issues de Zod por campo) são impressos de forma amigável, com a chave problemática em negrito e uma dica quando aplicável.

`guara crons update <slug> -f <file>`

Atualiza um cron worker a partir de um arquivo de spec YAML ou JSON. O tipo do destino não pode ser alterado — você só consegue editar a configuração do tipo já existente.

guara crons update hourly -f cron.yaml
guara crons update hourly -f patch.json --json

Flag	Abreviação	Descrição
`-f, --file`	`-f`	Caminho do arquivo de spec (YAML por padrão, JSON detectado pela extensão `.json`).

`guara crons delete <slug>`

Exclui um cron worker. O histórico de execuções também é removido. Requer confirmação.

guara crons delete hourly                # Confirmação interativa
guara crons delete hourly --yes          # Pula a confirmação
guara crons delete hourly --json --yes   # Amigável para scripts

Flag	Descrição
`--yes`	Pula o prompt de confirmação. Obrigatório quando se usa `--json` ou `--quiet`.

`guara crons suspend <slug>`

Suspende um cron worker para que o schedule pare de disparar. O worker mantém configuração e histórico; execuções já em voo terminam normalmente.

guara crons suspend hourly
guara crons suspend hourly --json

`guara crons resume <slug>`

Retoma um cron worker suspenso. O schedule reinicia a partir do próximo slot — execuções perdidas durante a suspensão não são repostas.

guara crons resume hourly
guara crons resume hourly --json

`guara crons trigger <slug>`

Dispara manualmente um cron worker. A execução é enfileirada de forma assíncrona — o comando retorna assim que a API aceita o disparo, não quando a execução termina.

guara crons trigger hourly
guara crons trigger hourly --json

Saída de exemplo:

✓ Triggered hourly
  Inspect with: guara crons runs hourly --watch

O disparo passa pelo mesmo pipeline de retry, timeout e auditoria que execuções agendadas e tem rate limit por worker. Use guara crons runs <slug> --watch para acompanhar a execução resultante chegar no histórico.

`guara crons runs <slug>`

Lista as execuções recentes de um cron worker. Por padrão renderiza uma tabela; passe --detail para cards com borda (um por execução), incluindo a explicação do motivo da falha, prévia do erro e payload resolvido.

guara crons runs hourly
guara crons runs hourly --detail
guara crons runs hourly --status failed --watch
guara crons runs hourly --limit 50 --cursor eyJ...

Flag	Abreviação	Descrição
`-n, --limit <n>`	`-n`	Máximo de linhas por página (1-100, padrão `20`).
`--cursor <token>`		Cursor de paginação (opaco, retornado pela página anterior).
`--status <estado>`		Filtra pelo status. Aceita `running`, `success` ou `failed`.
`--detail`		Renderiza cada execução como um card com borda em vez de tabela.
`-w, --watch`	`-w`	Faz polling repetido da página 1, deduplicando execuções já vistas.
`-i, --interval <segundos>`	`-i`	Intervalo de polling em segundos (padrão `5`, mínimo `2`).
`--ascii`		Usa apenas glifos ASCII (sem Unicode). Também ativado por `NO_UNICODE=1`.

Saída de exemplo (tabela):

 ID         STATUS       STARTED                    DURATION   REASON
 4f2ab91d   ● success    2026-05-02T15:00:01.120Z   842ms      —
 3a18cc02   ● success    2026-05-02T14:00:00.943Z   915ms      —
 2c9f8de4   ✕ failed     2026-05-02T13:00:01.214Z   30001ms    timeout
 1bd47a8e   ● success    2026-05-02T12:00:00.812Z   771ms      —

Com --watch, a página 1 é consultada a cada --interval segundos. No modo --detail, as execuções vistas são deduplicadas contra um conjunto limitado de IDs já renderizados, então a mesma execução nunca aparece duas vezes. Com --watch --json, cada tick emite uma página NDJSON.

Profiling

`guara services profiles get`

Renderiza um flamegraph de CPU para um serviço a partir do pipeline de profiling contínuo da plataforma. Veja Profiling Contínuo de CPU para o modelo subjacente.

guara services profiles get
guara services profiles get --time-range 1h --top 20
guara services profiles get --from 2026-05-02T15:00:00Z --to 2026-05-02T15:15:00Z
guara services profiles get --json | jq .data.metadata

Flag	Descrição
`--time-range <janela>`	Janela predefinida. Aceita `15m`, `30m`, `1h`, `6h`, `24h` ou `7d` (padrão `15m`). Mutuamente exclusiva com `--from`/`--to`.
`--from <iso>`	Início de janela explícita (ISO-8601). Precisa vir junto com `--to`.
`--to <iso>`	Fim de janela explícita (ISO-8601). Precisa vir junto com `--from`.
`--top <n>`	Quantidade de frames na tabela top-N por self time (padrão `10`).
`--width <colunas>`	Sobrescreve a largura do flamegraph em colunas (auto-detectado pelo terminal quando omitido, mínimo 40).
`--ascii`	Usa apenas glifos ASCII (compatível com terminais sem Unicode).

Saída de exemplo (truncada):

my-api · profile · 2026-05-02T15:00:00Z → 2026-05-02T15:15:00Z

▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇  100.0%  total
 ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇                         62.4%   handleRequest
  ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇                                        38.1%   db.query
   ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇                                               25.8%   pg.client.send
  ▇▇▇▇▇▇▇▇                                                         12.6%   serialize
 ▇▇▇▇▇▇▇▇▇▇▇▇                                                      18.7%   gc.minorMark

Top 10 by self time
   #  SELF %   FRAME
   1   25.8%   pg.client.send
   2   18.7%   gc.minorMark
   3   12.6%   serialize
   4    8.4%   crypto.randomFillSync
   5    7.1%   net.write
   …

Tier: Pro · retention 168h · window 15m

Quando stdout não é um TTY (piped para outro comando, redirecionado para arquivo), o flamegraph em si é omitido e apenas a tabela top-N é impressa, para legibilidade. Use --json para obter o envelope ProfileResponse cru ({ data: { flamebearer, metadata, … } }) e alimentar ferramentas downstream.