# Referencia CLI

O Runner oferece uma CLI completa para todo o ciclo de vida de uma app: configurar, operar, recuperar. Esta pagina lista os comandos por fase. Para detalhes, sintaxe e exemplos, abra a pagina de cada um.

# Configurar

Setup inicial de ambiente e registro de apps.

# Deploy

# Operar

Monitoramento, controle de fluxo e manutencao de apps em execucao.

# Secrets e Keys

CRUD de secrets, ckeys e master key do servidor.

# Recuperar e Depurar

# Instancias e Versoes

# PR Deploys e Staging

# Network e Portas

# Self-update e Configuracao

# Flags Globais

Disponiveis em todos os comandos.

# Output JSON: envelope canonico v2.0 (v2.34.0)

-o json envolve toda resposta em um envelope estavel:

{
  "success": true,
  "timestamp": "2026-06-06T14:23:45.123Z",
  "schema_version": "2.0",
  "client": { "name": "runner", "version": "2.34.1" },
  "command": "list",
  "data": { /* shape por comando */ }
}

Em erro, success: false, data omitido, bloco error: { code, message, details }.

# Streaming JSONL (deploy/fetch)

Comandos longos (deploy, fetch, validate, reconcile) em -o json emitem uma linha JSON por evento (JSONL), tagueada por event_type:

# Migrando do `--json` por subcomando

O flag --json em subcommands (runner fetch --json, runner stage list --json) continua aceito mas emite warning. Migrar pra flag global:

# Antes
runner fetch --deploy --json

# Depois (v2.34.0+)
runner -o json fetch --deploy
runner --json fetch --deploy        # atalho equivalente

A flag por subcommand sai na v3.0.0.

# Filtros por Labels

O comando list suporta filtragem por labels CCS:

runner list --project=meu-app
runner list --instance=production
runner list --project=frontend-* --json

Labels CCS usadas:

• ccs.systems/project
• ccs.systems/instance
• ccs.systems/version

# Exemplos Rapidos

# Primeiro uso
runner init
runner add --repo usuario/meu-app --ckey "minha-chave-secreta"

# Deploy
runner fetch --deploy
runner deploy meu-app

# Deploy de todas as apps (recovery)
runner deploy --all

# Rollback
runner rollback meu-app

# Canary manual
runner deploy meu-app --version v1.1.0
runner weight meu-app production v1.1.0 10
runner promote meu-app -i production v1.1.0

# Sinais de CI/CD
runner signal send meu-app --status fail --message "testes falharam"
runner signal clear meu-app

# Secrets
runner secrets show meu-app
runner secrets pull meu-app
runner secrets diff app-a app-b

# Diagnostico
runner doctor
runner debug last-error meu-app
runner inspect-args meu-app

# Self-update
runner self-update
runner self-update --rc

# Output JSON canonico v2.0
runner list -o json | jq '.data.items[] | select(.status == "unhealthy")'
runner deploy meuapp -o json | tee /var/log/runner/meuapp-deploy.jsonl