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

Flag global

`--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 variável de ambiente:

export VELOZ_OUTPUT=json

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.

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 específico (por chave ou nome)
veloz deploy --app apps/web # deploy de um app por path (monorepo)
veloz deploy -v           # logs detalhados do 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
veloz projetos listar   # alias pt-BR

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.

Aliases pt-BR: veloz dominios adicionar, veloz dominios listar, veloz dominios verificar, veloz dominios deletar

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 consultas MetricsQL personalizadas diretamente no VictoriaMetrics.

# Consulta instantânea (valor atual)
veloz metrics query "up"
veloz metrics query 'sum(rate(traefik_service_requests_total[5m]))'
 
# Consulta com intervalo (range query com sparklines)
veloz metrics query "rate(traefik_service_requests_total[5m])" --start 1h
veloz metrics query "container_memory_working_set_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 "container_cpu_usage_seconds_total"
 
# Listar valores de um label específico
veloz metrics labels --label pod
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 '{namespace="proj-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 consultas práticas.

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 query-help`

Referência de sintaxe SQL e comandos Redis suportados.

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

Próximos passos

CI/CD — Automatize deploys com GitHub Actions
Monorepo — Deploy de múltiplos apps
Variáveis de Ambiente — Gerenciar secrets

CLI Reference

Flag global

--output <format>

Autenticação

veloz login

veloz logout

veloz whoami

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

Logs

veloz logs show

veloz logs search <consulta>

veloz logs query-help

Métricas

veloz metrics show

veloz metrics range

veloz metrics query

veloz metrics list

veloz metrics labels

veloz metrics series

veloz metrics query-help