Referência de todos os comandos disponíveis na Veloz CLI.

Flags globais

`--output <format>`

Formato de saída para todos os comandos:

fancy, saída colorida com spinners (padrão em terminais interativos)
json, JSON estruturado para automação e parsing
github-actions, groups colapsáveis e outputs nativos do GitHub Actions
plain, texto simples sem cores (padrão em CI)

veloz deploy --output json
veloz projects list --output json

Auto-detecção: em GITHUB_ACTIONS=true usa github-actions, em CI=true usa plain. Também pode ser setado via VELOZ_OUTPUT=json.

`--json`

Atalho para --output json. Útil em pipelines.

`--mcp`

Inicia a CLI como servidor MCP (stdio JSON-RPC). Para uso em IDEs com IA, prefira veloz mcp add. Veja MCP & Agentes IA.

`--llms` / `--llms-full`

Imprime um manifesto da CLI em formato compacto, otimizado para agentes IA descobrirem comandos sem ler a doc inteira.

veloz --llms          # índice resumido
veloz --llms-full     # manifesto completo com schemas

`--help`, `-h`

Exibe ajuda do comando atual ou da raiz.

`--version`

Exibe a versão instalada da CLI.

Autenticação

`veloz login`

Autentica via navegador (Device Authorization Flow).

veloz login
veloz login --api-key "chave"     # para CI/automação
veloz login --api-url "https://..." # apontar para outro servidor

No CI, use API key diretamente:

VELOZ_API_KEY=veloz_xxx veloz deploy -y

`veloz logout`

Remove credenciais salvas.

`veloz whoami`

Mostra nome e email do usuário autenticado.

Setup inicial

`veloz init`

Wizard guiado por IA que prepara o projeto para deploy. Detecta o framework, configura veloz.json, cria o serviço, sobe o primeiro deploy e oferece registrar o GitHub para auto-deploy. Também conecta a CLI como servidor MCP no seu agente preferido (Claude Code, Cursor, Windsurf, etc).

veloz init                      # interativo (recomendado)
veloz init -f nextjs            # força framework
veloz init --ci                 # modo headless para automação

É o caminho recomendado para o primeiro contato com a Veloz. Veja Quickstart com veloz init.

Deploy

`veloz deploy`

Faz deploy do projeto. Detecta framework, cria projeto/serviço se necessário, faz upload e acompanha o build em tempo real.

veloz deploy                       # deploy interativo
veloz deploy -y                    # auto-confirma tudo (CI/automação)
veloz deploy --all                 # deploy de todos os serviços (monorepo)
veloz deploy --service web         # deploy de um serviço (por chave ou nome)
veloz deploy --app apps/web        # deploy de um app por path (monorepo)
veloz deploy --new --name api      # cria e adiciona um novo serviço
veloz deploy --dry-run             # simula o deploy sem enviar nada
veloz deploy -v                    # logs detalhados do servidor

Flags principais:

Flag	Descrição
`--all`	Deploy de todos os serviços do monorepo
`--service <chave>`	Deploy de um serviço específico (por chave ou nome)
`--app <path>`	Deploy de um app pelo path no monorepo
`--new`	Cria e adiciona um novo serviço durante o deploy
`--name <nome>`	Nome do novo serviço (usado com `--new`)
`--dry-run`	Simula o deploy sem upload nem build (não exige login)
`--yes`, `-y`	Auto-confirma todas as perguntas
`--verbose`, `-v`	Logs detalhados do servidor

Dica: --dry-run é seguro para rodar em qualquer máquina, inclusive sem autenticação. Mostra o que seria feito sem alterar nada no servidor.

Comportamento:

Detecta repositório git e framework
Se veloz.json existe, usa a configuração salva
Se não, busca projeto pelo GitHub remote ou cria um novo
Faz upload, inicia build e mostra logs em tempo real

Detecção automática

A CLI detecta automaticamente:

Framework: Next.js, Nuxt, Remix, SvelteKit, Astro, Hono, Express, Fastify, NestJS, Gatsby, Vite, Angular, Create React App
Package manager: npm, pnpm, yarn, bun
Comandos de build/start
Variáveis de ambiente (lendo .env.example, .env.sample)
Monorepo (pnpm workspaces, npm workspaces)

Tipos de serviço

Durante o deploy, a CLI pergunta o tipo:

? Tipo de serviço:
  ❯ Web (HTTP server)
    Static (site estático)
    Worker (background process)

Tipo	Use case
Web	APIs, Next.js, Express, Hono — qualquer servidor HTTP
Static	Sites estáticos, SPAs, landing pages
Worker	Filas de jobs, cron jobs, consumidores Kafka/RabbitMQ

Workers rodam em background sem expor porta HTTP — ideais para processamento assíncrono.

Projetos

`veloz projects list`

Lista todos os projetos da organização.

veloz projects list

Serviços

`veloz services list`

Lista todos os serviços do projeto com status, tipo e URL.

veloz services list

`veloz services delete <nome>`

Deleta um serviço do projeto.

veloz services delete api        # por nome
veloz services delete svc_xxx    # por ID

`veloz use [serviço]`

Em monorepos, seleciona qual serviço usar como padrão para os outros comandos.

veloz use              # seleção interativa
veloz use api          # seleciona por nome ou chave

Após selecionar, comandos como logs, env, config, domains usam esse serviço automaticamente. Use --service <nome> para sobrescrever pontualmente.

Link

`veloz link`

Mostra informações do projeto vinculado (lê veloz.json).

Variáveis de Ambiente

`veloz env set <CHAVE=VALOR...>`

Define uma ou mais variáveis de ambiente.

veloz env set DATABASE_URL=postgres://...
veloz env set KEY1=val1 KEY2=val2 KEY3=val3
veloz env set SECRET=valor --service api  # para um serviço específico

`veloz env list`

Lista variáveis (valores mascarados).

veloz env list
veloz env list --service web

`veloz env delete <chave>`

Remove uma variável.

`veloz env import [arquivo]`

Importa variáveis de um arquivo .env ou via colagem interativa.

veloz env import .env                 # importar de arquivo
veloz env import .env --replace       # substituir todas existentes
veloz env import                      # modo interativo (cola no terminal)
veloz env import --service api        # para um serviço específico

`veloz env export [arquivo]`

Exporta variáveis (mascaradas) para terminal ou arquivo.

veloz env export                  # mostra no terminal
veloz env export .env.backup      # salva em arquivo

Domínios

`veloz domains add <dominio>`

Adiciona um domínio personalizado ao serviço.

veloz domains add meuapp.com
veloz domains add api.meuapp.com --service api

`veloz domains list`

Lista domínios com status de verificação e TLS.

`veloz domains verify <domainId>`

Verifica configuração DNS de um domínio.

`veloz domains delete <domainId>`

Remove um domínio.

Configurações

`veloz config show`

Mostra configurações atuais do serviço.

veloz config show
veloz config show --service api

`veloz config set`

Altera configurações via flags.

veloz config set --build "npm run build"
veloz config set --start "npm run start"
veloz config set --port 8080
veloz config set --instances 3
veloz config set --cpu 500m --memory 512Mi
veloz config set --branch develop
veloz config set --root apps/web
veloz config set --name "meu-servico"

`veloz config edit`

Edição interativa de todas as configurações.

`veloz config reset`

Reseta configurações para os padrões.

veloz config reset --build    # reseta build command
veloz config reset --start    # reseta start command
veloz config reset --all      # reseta tudo

Logs

`veloz logs show`

Visualiza logs recentes ou acompanha em tempo real.

veloz logs show                    # últimas 50 linhas
veloz logs show --tail 100         # últimas 100 linhas
veloz logs show --follow           # streaming em tempo real
veloz logs show --service api      # logs de um serviço específico

Em monorepos, logs de múltiplos serviços são exibidos com tags coloridas para fácil identificação.

`veloz logs search <consulta>`

Pesquisa logs com sintaxe LogsQL.

veloz logs search "error"                       # buscar por palavra
veloz logs search "connection refused"          # frase exata
veloz logs search '~"status=[45]\d{2}"'         # regex
veloz logs search "error" --start 2026-03-01    # filtro por data
veloz logs search "error" --limit 50            # limitar resultados
veloz logs search "error" --deployment abc123   # filtrar por deploy
veloz logs search "error" --service api         # filtrar por serviço

`veloz logs query-help`

Exibe referência completa da sintaxe LogsQL: filtros, operadores lógicos, pipes, funções de agregação e exemplos práticos.

Métricas

`veloz metrics show`

Exibe métricas atuais do serviço ou banco de dados.

Serviços web/worker:

Tráfego: requisições/min, taxa de erros, latência P95, status HTTP
Recursos: restarts, uptime, eventos OOM, throttle de CPU

Bancos de dados (com insights ativado):

Conexões ativas/totais/idle, queries/s, cache hit ratio, tamanho do banco
Recursos: restarts, uptime, eventos OOM, throttle de CPU

veloz metrics show
veloz metrics show --service api
veloz metrics show --service postgres     # métricas do banco de dados

Para métricas detalhadas de banco, ative insights: veloz db update <nome> --insights

`veloz metrics range`

Exibe métricas em intervalo de tempo com sparklines Unicode no terminal.

veloz metrics range                  # última hora (padrão)
veloz metrics range --range 6h       # últimas 6 horas
veloz metrics range --range 24h      # últimas 24 horas
veloz metrics range --range 7d       # últimos 7 dias
veloz metrics range --service api    # para um serviço específico
veloz metrics range --service postgres  # sparklines do banco

Mostra sparklines para: requisições/min, latência P95/P50, CPU, memória, rede I/O. Para bancos de dados, também mostra conexões ativas, queries/s e cache hit ratio.

`veloz metrics query`

Executa queries MetricsQL personalizadas diretamente no VictoriaMetrics.

# Query instantânea (valor atual)
veloz metrics query "up"
veloz metrics query 'sum(rate(traefik_service_requests_total[5m]))'
 
# Query com intervalo (range query com sparklines)
veloz metrics query "rate(traefik_service_requests_total[5m])" --start 1h
veloz metrics query "veloz_service_memory_bytes" --start 6h --step 5m
veloz metrics query "pg_stat_activity_count" --start 24h

Opções:

Flag	Descrição
`--start`	Início do intervalo (ex: `1h`, `6h`, `24h`, `7d`, ISO 8601, unix timestamp)
`--end`	Fim do intervalo (padrão: agora)
`--step`	Resolução dos pontos (ex: `30s`, `1m`, `5m`). Calculado automaticamente se omitido

`veloz metrics list`

Lista nomes de métricas disponíveis na sua organização.

veloz metrics list                          # todas as métricas
veloz metrics list --match '{job="node"}'   # filtrar por seletor
veloz metrics list --limit 50               # limitar resultados

`veloz metrics labels`

Lista labels disponíveis ou valores de um label específico.

# Listar todos os labels
veloz metrics labels
 
# Listar labels filtrados por métrica
veloz metrics labels --match "veloz_service_cpu_seconds_total"
 
# Listar valores de um label específico
veloz metrics labels --label veloz_instance
veloz metrics labels --label state --match "pg_stat_activity_count"

`veloz metrics series`

Encontra séries de métricas por seletor, mostrando todos os labels de cada série.

veloz metrics series "traefik_service_requests_total"
veloz metrics series '{__name__=~"pg_.*"}'
veloz metrics series '{veloz_project="meu-projeto"}'

`veloz metrics query-help`

Exibe referência completa de MetricsQL: seletores, funções de taxa, agregação, rollup, histogramas, operadores, extensões MetricsQL, todas as métricas disponíveis na Veloz, exemplos de descoberta e queries práticas.

Traces

Requer observability.traces declarado no veloz.json. Veja Traces.

`veloz traces list`

Lista os traces recentes de um serviço.

veloz traces list                          # última 1h
veloz traces list --range 24h              # últimas 24 horas
veloz traces list --errors                 # somente com erro
veloz traces list --min-duration 500       # somente acima de 500ms
veloz traces list --limit 20               # limitar resultados
veloz traces list --service api            # de um serviço específico

  Traces (última 1h)

  HORÁRIO     OPERAÇÃO              DURAÇÃO   SPANS  ID
  14:02:11  ● POST /api/checkout    1.8s      23     4bf92f3577b34da6
  14:01:57    GET /api/produtos     142ms     9      7b9a2c1d4e5f6a80
  14:01:40    GET /api/produtos/42  86ms      7      c81d4e2f9a03b5d7
  13:58:40  ● POST /api/checkout    2.1s      21     a3ce929d0e0e4736

  2 trace(s) com erro de 4 no período.

As linhas marcadas com ● têm pelo menos um span com erro. Aceita 1h, 6h e 24h em --range. A retenção é de 7 dias.

`veloz traces show <traceId>`

Exibe a cascata de spans de um trace: cada etapa posicionada na linha do tempo, com a duração e, quando há falha, os atributos do primeiro span com erro.

veloz traces show 4bf92f3577b34da6
veloz traces show 4bf92f3577b34da6 --service api

Para ver os registros correlacionados, use o identificador na busca de logs:

veloz logs search '4bf92f3577b34da6'

Observabilidade

Alias: veloz obs. Veja Observabilidade.

`veloz observability status`

Estado dos três sinais (métricas, traces e dashboards) de um serviço, com o diagnóstico e a correção de cada falha. É o primeiro comando a rodar quando algo não aparece.

veloz obs status                   # serviço padrão
veloz obs status --service api     # serviço específico

  Observabilidade

  ✓ Métricas       1.204 série(s) · última coleta há 14s
  ✓ Traces         37 trace(s) na última hora
  ✓ Dashboards     3 de 20 publicado(s) · há 2min

Sinais não declarados no veloz.json aparecem como ○ não configurado. Quando a coleta falha, o motivo e a correção vêm nas linhas seguintes.

`veloz observability validate`

Valida os arquivos de dashboard declarados em observability.dashboards antes do deploy. Roda inteiramente local, sem chamar o servidor, e sai com código 1 quando algum arquivo falha.

veloz obs validate

  Validando dashboards em ./dashboards

  ✗ ./dashboards/api.json          JSON inválido na linha 42
  ✓ ./dashboards/visao-geral.json  12 KB  8 painéis

1 de 2 arquivo(s) com problema. Corrija antes do deploy.
  ./dashboards/api.json: JSON inválido na linha 42

`veloz observability dashboards`

Lista os dashboards já provisionados do projeto, com o link de cada um.

veloz obs dashboards

Os mesmos painéis aparecem no painel do Veloz, na aba Métricas do serviço, em "Seus painéis". As consultas de cada painel rodam contra as suas próprias métricas, então não é preciso entrar no Grafana para ler os números. Painéis que dependem de variáveis de template ($instance, ${namespace}) ou de outras fontes de dados são listados como não renderizados, com o nome de cada um, e continuam disponíveis pelo link do Grafana.

Builds

`veloz builds list`

Lista os builds recentes de um serviço com status, duração, trigger e commit.

veloz builds list                    # últimos 10 builds
veloz builds list --limit 20         # últimos 20 builds
veloz builds list --service api      # builds de um serviço específico

Cada build mostra: ID (parcial), status (na fila, compilando, ativo, falhou...), duração, trigger (push, config, redeploy, rollback), branch e mensagem do commit.

`veloz builds show <id>`

Exibe detalhes completos de um build: status, trigger, branch, commit (SHA, mensagem, autores), imagem gerada, motivo da falha e timestamps.

O ID do build é exibido após cada deploy. Você também pode copiar de veloz builds list.

veloz builds show clxxxxxxxxxxxxxxxxx        # por ID completo
veloz builds show clxxxxxxxxxxxxxxxxx --service api  # com serviço explícito

`veloz builds logs <id>`

Exibe os logs de build de um deploy. Mostra os passos do Dockerfile com formatação (steps, cache, duração).

veloz builds logs clxxxxxxxxxxxxxxxxx        # logs formatados
veloz builds logs clxxxxxxxxxxxxxxxxx --raw  # logs sem formatação
veloz builds logs clxxxxxxxxxxxxxxxxx --service api  # com serviço explícito

Use --raw para ver os logs brutos sem parsing de steps do BuildKit.

Bancos de Dados

`veloz db list`

Lista todos os bancos de dados do projeto com status, engine e tamanho.

veloz db list

`veloz db create`

Cria um banco de dados gerenciado (interativo ou com flags).

veloz db create                                          # interativo
veloz db create --name pg --engine postgresql --size essencial --storage 20Gi --pooler
veloz db create --name cache --engine redis --size basico

`veloz db credentials <nome>`

Exibe credenciais de conexão do banco (host, porta, user, senha, URL).

veloz db credentials pg

`veloz db tunnel <nome>`

Cria túnel local para acessar o banco com qualquer ferramenta externa.

veloz db tunnel pg                  # porta padrão do engine (5432)
veloz db tunnel pg --port 5433      # porta customizada
veloz db tunnel cache --port 6380   # Redis

`veloz db query <nome>`

Executa queries diretamente pela CLI.

veloz db query pg                                # modo interativo
veloz db query pg --query "SELECT count(*) FROM users"
veloz db query pg -q "SELECT * FROM orders LIMIT 10"
veloz db query cache -q "GET session:abc"        # Redis

`veloz db update <nome>`

Altera tamanho ou configuração de pooler do banco.

veloz db update pg --size turbo

`veloz db restart <nome>`

Reinicia o engine do banco.

`veloz db delete <nome>`

Exclui o banco de dados.

GitHub

`veloz github setup`

Configura o GitHub App para deploy automático via webhook.

veloz github setup                    # interativo
veloz github setup --project prj_xxx  # projeto específico

Abre o navegador para autorizar o Veloz GitHub App no repositório.

`veloz github status`

Verifica status da integração GitHub do projeto (conectado, repo, webhook).

veloz github status

Templates

`veloz template list`

Lista templates disponíveis para deploy one-click.

veloz template list

Templates disponíveis: n8n, NocoDB, Metabase, Gitea, Uptime Kuma, OpenClaw.

`veloz template deploy <slug>`

Deploy de um template no projeto.

veloz template deploy n8n
veloz template deploy metabase

Cria serviços, bancos e variáveis automaticamente.

Volumes

`veloz volumes list`

Lista volumes persistentes dos serviços.

veloz volumes list
veloz volumes list --service api

`veloz volumes create <nome>`

Cria um volume persistente para um serviço.

veloz volumes create data --service api --mount /data --size 10Gi

`veloz volumes expand <volume>`

Expande um volume existente (volumes só crescem).

veloz volumes expand data --size 20Gi

`veloz volumes delete <volume>`

Remove um volume.

`veloz volumes sync`

Sincroniza volumes do servidor com configuração local.

Pull

`veloz pull`

Sincroniza estado do servidor para o veloz.json local.

veloz pull                      # atualiza veloz.json com estado do servidor
veloz pull --project prj_xxx    # projeto específico
veloz pull --force              # sobrescreve sem perguntar

API Keys

`veloz apikey create`

Cria uma nova chave de API.

veloz apikey create
veloz apikey create --name "github-actions"
veloz apikey create --no-expire

A chave é exibida uma única vez — guarde em local seguro.

`veloz apikey list`

Lista todas as chaves de API.

`veloz apikey delete <keyId>`

Deleta uma chave de API.

Agentes IA

`veloz mcp add`

Registra a Veloz CLI como servidor MCP no seu agente IA. Detecta agentes instalados (Claude Code, Cursor, Claude Desktop, Windsurf, Codex CLI, Continue) e configura automaticamente.

veloz mcp add

Depois disso, o agente passa a ter acesso a todos os comandos como ferramentas. Veja MCP & Agentes IA.

`veloz skills add`

Gera arquivos SKILL.md por grupo de comandos, otimizados para que agentes IA descubram a CLI sem precisar carregar a doc completa. Cria os arquivos no diretório de skills do agente detectado.

veloz skills add

Útil quando seu agente suporta skills (Claude Code, por exemplo) e você quer que ele responda mais rápido sem consumir tokens lendo manuais grandes.

Próximos passos

Quickstart com veloz init, o caminho recomendado
CI/CD, automatize deploys com GitHub Actions
MCP & Agentes IA, conecte sua IDE de IA
Monorepo, deploy de múltiplos apps
Variáveis de Ambiente, gerenciar secrets

CLI Reference

Flags globais

--output <format>

--json

--mcp

--llms / --llms-full

--help, -h

--version

Autenticação

veloz login

veloz logout

veloz whoami

Setup inicial

veloz init

Deploy

veloz deploy

Detecção automática

Tipos de serviço

Projetos

veloz projects list

Serviços

veloz services list

veloz services delete <nome>

veloz use [serviço]

Link

veloz link

Variáveis de Ambiente

veloz env set <CHAVE=VALOR...>

veloz env list

veloz env delete <chave>

veloz env import [arquivo]

veloz env export [arquivo]

Domínios

veloz domains add <dominio>

veloz domains list

veloz domains verify <domainId>

veloz domains delete <domainId>

Configurações

veloz config show

veloz config set

veloz config edit

veloz config reset