> ## Documentation Index
> Fetch the complete documentation index at: https://userepass.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Convenções

> Anatomia de um comando, saída, corpo de requisição, modelo de risco, exit codes e erros.

Todo comando da CLI segue a mesma anatomia e as mesmas convenções, independente do recurso.

## Anatomia de um comando

```
repass <grupo> <comando> [args] [flags]
```

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

```bash theme={null}
repass affiliates approve aff_01J9Z3M2P0RD8K4VC1XN6YHTBE
repass programs list --status active --json
```

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

```text repass programs list theme={null}
id                            name                  status  currency  createdAt
-----------------------------  --------------------  ------  --------  --------------------
prog_01J9ZP6Q8X3K7M2N4R5T6V7W8Y  Programa de Indicações  active  BRL       2026-01-15T12:00:00Z
```

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

```bash theme={null}
repass programs list --json
```

```json theme={null}
[
  {
    "id": "prog_01J9ZP6Q8X3K7M2N4R5T6V7W8Y",
    "name": "Programa de Indicações",
    "status": "active",
    "currency": "BRL"
  }
]
```

## Corpo de requisição: `--data` e `--file`

Comandos de criação/atualização aceitam o corpo em JSON de duas formas **mutuamente exclusivas**:

```bash theme={null}
repass affiliates create prog_xxx --data '{"name":"Ana Silva","email":"ana@exemplo.com"}'
repass affiliates create prog_xxx --file ./novo-afiliado.json
```

Usar `--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`:

```bash theme={null}
repass materials upload prog_xxx --upload ./banner.png --name "Banner 300x250"
```

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

| Risco         | Exemplo                                                                    | Confirmação? |
| ------------- | -------------------------------------------------------------------------- | ------------ |
| `read`        | `affiliates get`, `payouts list`                                           | Não          |
| `write`       | `affiliates approve`, `commissions create-bonus`                           | Não          |
| `destructive` | `affiliates ban`, `webhooks delete`, `conversions void`                    | Sim          |
| `sensitive`   | `payouts preview`, `payouts run`, `settings set`, `webhooks rotate-secret` | Sim          |

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.

```bash theme={null}
repass affiliates ban aff_xxx --data '{"reason":"fraude confirmada"}' --yes
```

## 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:

```text theme={null}
Credencial inválida ou sessão expirada. Rode `repass login`.
Detalhe: Unauthorized
```

```text theme={null}
Recurso não encontrado.
Detalhe: Affiliate not found.
Request ID: req_01J9Z...
```

Quando a API emite um id de requisição, ele aparece na última linha (`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](/docs/convencoes/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

<CardGroup cols={2}>
  <Card title="Paginação" icon="layer-group" href="/docs/cli/paginacao">
    `--limit`, cursores e `--all` nos comandos de listagem.
  </Card>

  <Card title="Automação e CI" icon="robot" href="/docs/cli/automacao-ci">
    `--yes`, `--json` e exit codes em pipelines não interativos.
  </Card>
</CardGroup>