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

# CLI

> Ferramenta oficial de linha de comando da Avantti Finance para desenvolvimento, automações e operações financeiras em tempo real.

A Avantti CLI permite interagir com toda a infraestrutura da Avantti diretamente do terminal. Crie cobranças, escute webhooks, gerencie contas, automatize fluxos financeiros e integre sistemas com velocidade e previsibilidade.

## Visão geral

A CLI foi construída para desenvolvedores que precisam:

* Automatizar operações financeiras
* Integrar sistemas rapidamente
* Escutar eventos em tempo real
* Executar rotinas em CI/CD
* Trabalhar localmente sem complexidade
* Ter output estruturado para scripts

## Filosofia

A Avantti CLI foi criada para ser:

* Explícita
* Scriptável
* Unix-friendly
* Rápida
* Previsível
* Compatível com automações
* AI-ready

## Instalação

<CodeGroup>
  ```bash Go (recomendado) theme={null}
  go install github.com/avanttifinance/avantti-cli@latest
  ```

  ```bash Homebrew theme={null}
  brew install avantti/tap/avantti-cli
  ```
</CodeGroup>

Verifique a instalação:

```bash theme={null}
avantti --version
```

## Primeiros passos

<Steps>
  <Step title="Login">
    ```bash theme={null}
    avantti login
    ```

    O navegador será aberto para autenticação segura.
  </Step>

  <Step title="Configurar ambiente">
    ```bash theme={null}
    avantti env use sandbox
    ```
  </Step>

  <Step title="Escutar webhooks">
    ```bash theme={null}
    avantti listen --forward-to http://localhost:3000/webhooks
    ```
  </Step>

  <Step title="Criar pagamento PIX">
    ```bash theme={null}
    avantti payments create pix \
      --amount 5000 \
      --customer "João Silva"
    ```
  </Step>
</Steps>

## Estrutura da CLI

| Comando         | Descrição                   |
| --------------- | --------------------------- |
| `auth`          | Autenticação e sessões      |
| `payments`      | Gerenciamento de pagamentos |
| `customers`     | Clientes                    |
| `subscriptions` | Assinaturas                 |
| `listen`        | Escutar webhooks            |
| `logs`          | Logs e debugging            |
| `config`        | Configuração da CLI         |
| `env`           | Ambientes                   |
| `webhooks`      | Gerenciamento de webhooks   |

## Referência de comandos

### Autenticação

<CodeGroup>
  ```bash Login theme={null}
  avantti login
  ```

  ```bash Logout theme={null}
  avantti logout
  ```

  ```bash Ver sessão atual theme={null}
  avantti whoami
  ```
</CodeGroup>

### Ambientes

<CodeGroup>
  ```bash Sandbox theme={null}
  avantti env use sandbox
  ```

  ```bash Produção theme={null}
  avantti env use production
  ```

  ```bash Ver ambiente atual theme={null}
  avantti env current
  ```
</CodeGroup>

### Pagamentos

<CodeGroup>
  ```bash Criar cobrança PIX theme={null}
  avantti payments create pix \
    --amount 5000 \
    --customer "João Silva"
  ```

  ```bash Criar cobrança cartão theme={null}
  avantti payments create card \
    --amount 10000
  ```

  ```bash Listar pagamentos theme={null}
  avantti payments list
  ```

  ```bash Buscar pagamento theme={null}
  avantti payments get pay_123456
  ```

  ```bash Cancelar pagamento theme={null}
  avantti payments cancel pay_123456
  ```
</CodeGroup>

### Clientes

<CodeGroup>
  ```bash Criar cliente theme={null}
  avantti customers create \
    --name "João Silva" \
    --email "joao@email.com"
  ```

  ```bash Listar clientes theme={null}
  avantti customers list
  ```

  ```bash Buscar cliente theme={null}
  avantti customers get cus_123456
  ```
</CodeGroup>

### Assinaturas

<CodeGroup>
  ```bash Criar assinatura theme={null}
  avantti subscriptions create \
    --customer cus_123456 \
    --plan premium
  ```

  ```bash Cancelar assinatura theme={null}
  avantti subscriptions cancel sub_123456
  ```

  ```bash Listar assinaturas theme={null}
  avantti subscriptions list
  ```
</CodeGroup>

### Webhooks

<CodeGroup>
  ```bash Escutar eventos localmente theme={null}
  avantti listen \
    --forward-to http://localhost:3000/webhooks
  ```

  ```bash Eventos específicos theme={null}
  avantti listen \
    --events payment.approved,payment.failed
  ```

  ```bash Reenviar evento theme={null}
  avantti webhooks resend evt_123456
  ```
</CodeGroup>

### Logs

<CodeGroup>
  ```bash Tempo real theme={null}
  avantti logs tail
  ```

  ```bash Logs de pagamentos theme={null}
  avantti logs payments
  ```

  ```bash Logs filtrados theme={null}
  avantti logs tail --level error
  ```
</CodeGroup>

### Configuração

<CodeGroup>
  ```bash Ver configuração theme={null}
  avantti config list
  ```

  ```bash Definir chave padrão theme={null}
  avantti config set api_key sk_test_xxxxxx
  ```

  ```bash Definir output JSON theme={null}
  avantti config set output json
  ```
</CodeGroup>

## Output

### Output padrão

```bash theme={null}
avantti payments list
```

### Output JSON

```bash theme={null}
avantti payments list --output json
```

```json Exemplo theme={null}
{
  "success": true,
  "data": [
    {
      "id": "pay_123456",
      "status": "approved",
      "amount": 5000
    }
  ]
}
```

## Flags globais

| Flag        | Alias | Descrição            |
| ----------- | ----- | -------------------- |
| `--help`    | `-h`  | Ajuda                |
| `--version` | `-v`  | Versão               |
| `--output`  | `-o`  | text, json ou table  |
| `--sandbox` | `-s`  | Usa ambiente sandbox |
| `--verbose` |       | Logs detalhados      |

## Automação

A CLI foi construída para funcionar perfeitamente em automações.

<CodeGroup>
  ```bash Exemplo Bash theme={null}
  PAYMENT_ID=$(avantti payments create pix \
    --amount 5000 \
    --output json | jq -r '.data.id')

  echo $PAYMENT_ID
  ```

  ```yaml Exemplo CI/CD theme={null}
  name: Avantti Payments

  on:
    push:

  jobs:
    payment-test:
      runs-on: ubuntu-latest

      steps:
        - uses: actions/checkout@v4

        - name: Install Avantti CLI
          run: |
            brew install avantti/tap/avantti-cli

        - name: Authenticate
          run: |
            avantti auth token ${{ secrets.AVANTTI_TOKEN }}

        - name: Run tests
          run: |
            avantti payments list
  ```
</CodeGroup>

## Segurança

A Avantti CLI utiliza:

* Tokens seguros
* Sessões criptografadas
* HTTPS obrigatório
* Rotação de credenciais
* Ambientes isolados

## Troubleshooting

<AccordionGroup>
  <Accordion title="Resetar configuração" icon="arrow-rotate-left">
    ```bash theme={null}
    avantti config reset
    ```
  </Accordion>

  <Accordion title="Limpar sessão" icon="key">
    ```bash theme={null}
    avantti logout
    ```
  </Accordion>

  <Accordion title="Ver logs detalhados" icon="terminal">
    ```bash theme={null}
    avantti logs tail --verbose
    ```
  </Accordion>
</AccordionGroup>

## Atualização

<CodeGroup>
  ```bash Homebrew theme={null}
  brew upgrade avantti-cli
  ```

  ```bash Go theme={null}
  go install github.com/avanttifinance/avantti-cli@latest
  ```
</CodeGroup>

## Referência completa

| Comando                        | Descrição          |
| ------------------------------ | ------------------ |
| `avantti login`                | Login              |
| `avantti logout`               | Logout             |
| `avantti whoami`               | Usuário atual      |
| `avantti env use`              | Alterar ambiente   |
| `avantti payments create`      | Criar pagamento    |
| `avantti payments list`        | Listar pagamentos  |
| `avantti customers create`     | Criar cliente      |
| `avantti subscriptions create` | Criar assinatura   |
| `avantti listen`               | Escutar webhooks   |
| `avantti logs tail`            | Logs em tempo real |
| `avantti config list`          | Ver configuração   |

## Boas práticas

<Tip>
  Use `sandbox` durante o desenvolvimento, nunca exponha chaves de produção, prefira output JSON em automações, utilize variáveis de ambiente e faça rotação periódica de credenciais.
</Tip>

## Recursos relacionados e suporte

<CardGroup cols={2}>
  <Card title="Referência da API" color="#ff7e00" icon="code" href="/api-reference">
    Explore todos os endpoints da API Avantti Finance
  </Card>

  <Card title="Webhooks" color="#ff7e00" icon="webhook" href="/webhook">
    Configure e gerencie eventos em tempo real
  </Card>

  <Card title="SDKs" color="#ff7e00" icon="house-wifi" href="/Sdk">
    SDKs oficiais para Node.js, PHP, Python, Go e Java
  </Card>

  <Card title="Status Page" color="#ff7e00" icon="signal">
    Acompanhe o status da plataforma em tempo real
  </Card>

  <Card title="Changelog" color="#ff7e00" icon="clock-rotate-left">
    Veja as últimas atualizações da CLI e da API
  </Card>

  <Card title="Suporte por e-mail" color="#ff7e00" icon="envelope" href="mailto:suporte@avanttifinance.com">
    [suporte@avanttifinance.com](mailto:suporte@avanttifinance.com)
  </Card>

  <Card title="Discord da comunidade" color="#ff7e00" icon="discord">
    Tire dúvidas com outros desenvolvedores
  </Card>

  <Card title="GitHub Issues" color="#ff7e00" icon="github">
    Reporte bugs e acompanhe o desenvolvimento
  </Card>
</CardGroup>

<Info>
  A Avantti CLI foi construída para acelerar integrações financeiras modernas com foco em velocidade, automação e experiência de desenvolvimento.
</Info>