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

# Programas (CLI)

> Comandos de programas, tiers, regras de comissão, termos e materiais.

Os grupos `programs`, `tiers`, `commission-rules`, `tier-commission-rules`, `terms` e `materials` gerenciam [programas de afiliados](/docs/conceitos/programas-e-regras) (moeda, modelo e janela de [atribuição](/docs/conceitos/atribuicao), hold de comissão e modo de aprovação) e seus sub-recursos pela CLI.

## `programs`

```bash theme={null}
# Criar
repass programs create --data '{"name":"Programa de Indicações","attributionModel":"last_click","approvalMode":"manual"}'

# Buscar
repass programs get prog_xxx

# Listar (paginado)
repass programs list --status active --json

# Atualizar (parcial)
repass programs update prog_xxx --data '{"holdDays":15}'
```

```json repass programs get prog_xxx --json theme={null}
{
  "id": "prog_01J9ZP6Q8X3K7M2N4R5T6V7W8Y",
  "name": "Programa de Indicações",
  "status": "active",
  "attributionModel": "last_click",
  "holdDays": 15,
  …
}
```

`programs list` é paginado. Veja [Paginação](/docs/cli/paginacao) para `--all` e cursores.

### Ações de estado

```bash theme={null}
repass programs pause prog_xxx      # active → paused
repass programs activate prog_xxx   # paused → active
repass programs archive prog_xxx    # arquiva (soft-delete)
```

<Warning>
  `programs archive` é `destructive`. Irreversível na prática, sem "desarquivar" no registry. Em terminal interativo, pede confirmação; fora de TTY exige `--yes`. Veja [Convenções](/docs/cli/convencoes#modelo-de-risco).

  ```bash theme={null}
  repass programs archive prog_xxx --yes
  ```
</Warning>

## `tiers`

Lista **ordenada** de faixas de um programa, geridas individualmente (criar, renomear, reposicionar, reordenar e arquivar). Todos os comandos recebem `program-id` como argumento posicional.

```bash theme={null}
# Lista os tiers ativos, por posição (resultado não paginado)
repass tiers list prog_xxx

# Criar (posição no fim se omitida)
repass tiers create prog_xxx --data '{"name":"Ouro"}'

# Renomear e/ou reposicionar
repass tiers update prog_xxx tier_xxx --data '{"name":"Platina"}'

# Reordenar (IDs dos tiers ativos na nova ordem)
repass tiers reorder prog_xxx --data '{"tierIds":["tier_ouro","tier_prata"]}'
```

<Warning>
  `tiers archive` é `destructive`. Soft-delete idempotente, mas sem "desarquivar" no registry. Rode `tiers list` antes para confirmar o id certo, e use `--yes` fora de TTY (veja [Convenções](/docs/cli/convencoes#modelo-de-risco)).

  ```bash theme={null}
  repass tiers archive prog_xxx tier_xxx --yes
  ```
</Warning>

## `commission-rules`

Regra **padrão** do programa, [versionada e imutável](/docs/conceitos/comissoes): cada alteração publica uma nova versão em vez de sobrescrever a anterior. Todos os comandos recebem `program-id`.

```bash theme={null}
# Publicar nova versão (percentage | fixed | tiered)
repass commission-rules create prog_xxx --data '{"type":"percentage","percentage":10,"recurrence":{"kind":"one_time"}}'

# Listar todas as versões
repass commission-rules list prog_xxx --json

# Versão vigente
repass commission-rules current prog_xxx

# Versão específica
repass commission-rules get prog_xxx cmrl_xxx
```

## `tier-commission-rules`

Cada tier tem seu próprio histórico [versionado e imutável](/docs/conceitos/comissoes) de regras, independente da regra padrão do programa. Enquanto o tier não publica uma regra própria, ele cai na regra padrão (veja [precedência](/docs/conceitos/programas-e-regras)). Todos os comandos recebem `program-id` e `tier-id`.

```bash theme={null}
# Publicar nova versão da regra do tier
repass tier-commission-rules publish prog_xxx tier_xxx --data '{"type":"percentage","percentage":25}'

# Listar todas as versões do tier
repass tier-commission-rules list prog_xxx tier_xxx --json

# Versão vigente do tier (404 se ainda não há regra própria)
repass tier-commission-rules current prog_xxx tier_xxx
```

## `terms`

Versões dos [termos](/docs/conceitos/termos) do programa. Todos os comandos recebem `program-id`.

```bash theme={null}
# Listar as versões publicadas
repass terms list prog_xxx --json

# Publicar via markdown ou link (corpo --data/--file)
repass terms publish prog_xxx --data '{"format":"markdown","content":"# Termos do Programa\n\nAo participar, você concorda...","requireReacceptance":true}'

# Publicar a partir de um PDF (--upload, não --data)
repass terms publish-file prog_xxx --upload ./termos-v2.pdf --require-reacceptance

# URL temporária (pré-assinada) do PDF de uma versão
repass terms file-url prog_xxx 2
```

## `materials`

Materiais (criativos) de um programa: uploads e listagem/edição. Todos os comandos recebem `program-id`.

```bash theme={null}
# Subir um material (--upload, não --data)
repass materials upload prog_xxx --upload ./banner.png --name "Banner 300x250" --format "300x250"

# Listar (paginado, filtro opcional por status)
repass materials list prog_xxx --status active --json

# Buscar
repass materials get prog_xxx mat_xxx

# Atualizar nome, formato ou status
repass materials update prog_xxx mat_xxx --data '{"status":"archived"}'
```

`materials list` é paginado. Veja [Paginação](/docs/cli/paginacao).

<Warning>
  `materials delete` é `destructive`. Exclusão permanente (hard-delete), sem recuperação. Rode `materials get` antes para confirmar qual arquivo, e use `--yes` fora de TTY (veja [Convenções](/docs/cli/convencoes#modelo-de-risco)).

  ```bash theme={null}
  repass materials delete prog_xxx mat_xxx --yes
  ```
</Warning>

<Note>
  Para o schema completo de cada corpo e os campos dos objetos retornados, consulte a página SDK equivalente ([Programs](/docs/sdk/recursos/programs)) e a [Referência da API](/docs/convencoes/ids-e-recursos). As regras de negócio estão em [Programas e regras](/docs/conceitos/programas-e-regras) e [Comissões](/docs/conceitos/comissoes).
</Note>