Anatomia de um comando
<grupo>: o recurso, no plural (affiliates,payouts,webhooks…).<comando>: a ação dentro do grupo (list,get,approve,run…).[args]: argumentos posicionais, geralmente um id (repass affiliates approve aff_xxx).[flags]: flags nomeadas específicas do comando, mais as globais (--json,--yes,--profile,--api-key,--base-url).
Saída: humana vs. --json
Sem --json, a CLI imprime um formato legível para leitura visual:
- Lista → tabela de texto, até 6 colunas, valores de objeto truncados.
- Objeto único → pares
chave: valor, um por linha. - Vazio →
Nenhum resultado.
repass programs list
--json, a CLI imprime o resultado cru via JSON.stringify, sem truncar nada. Use sempre --json quando o objetivo é parsear a saída em outro programa, a tabela humana não é um formato estável para isso.
Corpo de requisição: --data e --file
Comandos de criação/atualização aceitam o corpo em JSON de duas formas mutuamente exclusivas:
--data e --file juntos lança um erro explícito. JSON inválido (inline ou de arquivo) também lança um erro específico em vez de estourar cru. Confira repass <grupo> <comando> --help para o formato exato de cada corpo.
Uploads de arquivo binário (materiais, comprovantes, notas fiscais) usam uma flag própria, --upload, separada de --data/--file:
Modelo de risco
Todo comando tem um nível de risco (read, write, destructive ou sensitive) que determina se ele pede confirmação antes de rodar.
Comandos
destructive/sensitive param antes de chamar a API:
- Em terminal interativo (TTY), pedem confirmação explícita:
Confirma <grupo> <comando>? Esta ação é destrutiva/sensível e não pode ser desfeita facilmente. - Fora de TTY (scripts, CI), a confirmação é substituída pela flag
--yes. Sem ela, o comando falha com um erro orientando usá-la.
Exit codes
A CLI segue a convenção Unix:0 para sucesso, 1 para qualquer falha (erro da API, validação, confirmação cancelada, credencial ausente). Use o exit code para controlar fluxo em scripts. Não parseie a mensagem de erro para decidir se algo funcionou.
Formato de erros
Uma falha imprime uma mensagem amigável em PT-BR em stderr, seguida do detalhe original quando o erro veio da API:Request ID:). Inclua-o ao contatar o suporte.
Dinheiro e percentuais
Assim como o resto da plataforma, valores monetários chegam sempre em centavos (campos*Cents, ex. amountCents) e percentuais de comissão em número decimal, nunca formatados como string com %. Veja IDs e recursos para o detalhe completo das convenções de dados que valem tanto para a API quanto para a CLI.
Próximos passos
Paginação
--limit, cursores e --all nos comandos de listagem.Automação e CI
--yes, --json e exit codes em pipelines não interativos.