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

# CLI

> Gerencie cobranças e clientes direto no terminal com a CLI da Garu

## Visão Geral

A CLI da Garu permite criar cobranças, gerenciar clientes e diagnosticar sua integração sem sair do terminal. Ideal para automações, scripts e agentes de IA que preferem trabalhar com comandos.

<Note>
  **Pré-requisito:** Você precisa de uma chave de API. Veja como obter em
  [Autenticação](/api-reference/autenticacao).
</Note>

## Instalação

<CodeGroup>
  ```bash npm theme={null}
  npm install -g @garuhq/cli
  ```

  ```bash curl theme={null}
  curl -fsSL https://raw.githubusercontent.com/Garu-Pagamentos/garu-cli/main/install.sh | bash
  ```
</CodeGroup>

Verifique a instalação:

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

## Autenticação

Existem três formas de autenticar:

<Tabs>
  <Tab title="Login interativo">
    ```bash theme={null}
    garu login
    ```

    Abre o navegador para autenticação. O token é salvo em `~/.config/garu/credentials.json`.
  </Tab>

  <Tab title="Variável de ambiente">
    ```bash theme={null}
    export GARU_API_KEY=YOUR_API_KEY
    ```

    A CLI usa automaticamente a variável `GARU_API_KEY` se presente.
  </Tab>

  <Tab title="Flag inline">
    ```bash theme={null}
    garu charges list --api-key YOUR_API_KEY
    ```

    Útil para scripts e CI/CD. A flag tem prioridade sobre as outras formas.
  </Tab>
</Tabs>

Para encerrar a sessão:

```bash theme={null}
garu logout
```

## Referência de Comandos

### Autenticação

| Comando       | Descrição                 |
| ------------- | ------------------------- |
| `garu login`  | Autentica via navegador   |
| `garu logout` | Remove credenciais salvas |

### Cobranças

| Comando                    | Descrição                         |
| -------------------------- | --------------------------------- |
| `garu charges create`      | Cria uma nova cobrança            |
| `garu charges list`        | Lista cobranças                   |
| `garu charges get <id>`    | Consulta detalhes de uma cobrança |
| `garu charges refund <id>` | Reembolsa uma cobrança            |

### Clientes

| Comando                      | Descrição                       |
| ---------------------------- | ------------------------------- |
| `garu customers create`      | Cadastra um novo cliente        |
| `garu customers list`        | Lista clientes                  |
| `garu customers get <id>`    | Consulta detalhes de um cliente |
| `garu customers update <id>` | Atualiza dados de um cliente    |
| `garu customers delete <id>` | Remove um cliente               |

### Produtos

A partir da CLI 0.7.0 você cria e atualiza produtos sem sair do terminal — incluindo o [Pix Automático](/guias/pix-automatico).

| Comando                     | Descrição                     |
| --------------------------- | ----------------------------- |
| `garu products create`      | Cria um novo produto          |
| `garu products update <id>` | Atualiza um produto existente |

### Cobranças Agendadas

| Comando                         | Descrição                                  |
| ------------------------------- | ------------------------------------------ |
| `garu scheduled-charges create` | Agenda uma cobrança (avulsa ou recorrente) |

### Diagnóstico

| Comando       | Descrição                             |
| ------------- | ------------------------------------- |
| `garu doctor` | Verifica configuração e conectividade |

### Flags Globais

| Flag        | Descrição                                          |
| ----------- | -------------------------------------------------- |
| `--api-key` | Chave de API inline (prioridade sobre env e login) |
| `--json`    | Saída em JSON (ideal para scripts e agentes de IA) |

## Modos de Saída

A CLI detecta automaticamente se está rodando em um terminal interativo (TTY) ou em um script:

<Tabs>
  <Tab title="Interativo (TTY)">
    Saída formatada com cores e tabelas:

    ```bash theme={null}
    garu charges list
    ```

    ```
    ┌────────┬──────────────────┬──────────┬─────────┐
    │ ID     │ Cliente          │ Valor    │ Status  │
    ├────────┼──────────────────┼──────────┼─────────┤
    │ 12345  │ joao@email.com   │ R$ 49,90 │ paid    │
    │ 12346  │ maria@email.com  │ R$ 99,00 │ pending │
    └────────┴──────────────────┴──────────┴─────────┘
    ```
  </Tab>

  <Tab title="JSON (--json)">
    Saída em JSON para scripts e automações:

    ```bash theme={null}
    garu charges list --json
    ```

    ```json theme={null}
    [
      {
        "id": 12345,
        "customer": "joao@email.com",
        "amount": 4990,
        "status": "paid"
      }
    ]
    ```
  </Tab>
</Tabs>

<Tip>
  Use `--json` quando estiver integrando a CLI com outros scripts ou quando um
  agente de IA estiver usando a CLI.
</Tip>

## Diagnóstico com `garu doctor`

O comando `garu doctor` verifica se tudo está configurado corretamente:

```bash theme={null}
garu doctor
```

```
✔ Versão da CLI: 1.0.0
✔ Node.js: v20.11.0
✔ Credenciais: configuradas
✔ Conectividade: API acessível
✔ Chave de API: válida (sk_test_***abc)
```

**O que ele verifica:**

* Versão da CLI e do Node.js
* Se as credenciais estão configuradas
* Se a API está acessível
* Se a chave de API é válida

## Exemplos de Uso

### Criar uma cobrança PIX

```bash theme={null}
garu charges create \
  --amount 4990 \
  --method pix \
  --customer-email joao@email.com
```

### Listar cobranças pagas

```bash theme={null}
garu charges list --status paid
```

### Cadastrar um cliente

```bash theme={null}
garu customers create \
  --name "Maria Silva" \
  --email maria@email.com \
  --document 12345678900
```

## Produtos pela CLI

Com `garu products create` e `garu products update <id>` você cria e ajusta produtos direto no terminal — perfeito para versionar seu catálogo em scripts ou deixar um agente de IA cuidar disso.

### Flags disponíveis

As mesmas flags valem para `create` e `update`:

| Flag                       | Descrição                                                          |
| -------------------------- | ------------------------------------------------------------------ |
| `--name`                   | Nome do produto (exibido ao cliente)                               |
| `--value`                  | Preço **em centavos** (ex: `4990` = R\$ 49,90)                     |
| `--description`            | Descrição do produto                                               |
| `--image`                  | URL da imagem do produto                                           |
| `--tags`                   | Tags para categorização (separadas por vírgula)                    |
| `--pix`                    | Habilita pagamento via PIX                                         |
| `--boleto`                 | Habilita boleto bancário                                           |
| `--credit-card`            | Habilita cartão de crédito                                         |
| `--pix-automatic`          | Liga o [Pix Automático](/guias/pix-automatico) (débito recorrente) |
| `--no-pix-automatic`       | Desliga o Pix Automático (padrão)                                  |
| `--installments`           | Parcelas máximas no cartão (1–12)                                  |
| `--subscription`           | Marca o produto como assinatura                                    |
| `--subscription-type`      | Tipo da assinatura (`monthly`, `yearly`, etc.)                     |
| `--unit-label`             | Rótulo da unidade (ex: "licença", "assento")                       |
| `--return-url`             | URL de redirecionamento após o pagamento                           |
| `--return-url-button-text` | Texto do botão exibido na tela de sucesso                          |

<Note>
  Na CLI, `--value` é informado **em centavos** (igual a `garu charges create --amount`). No dashboard e na API REST o preço é em Reais — não misture as unidades.
</Note>

### Criar um produto simples

```bash theme={null}
garu products create \
  --name "E-book de Marketing" \
  --value 4700 \
  --pix --credit-card --boleto \
  --installments 3
```

### Ligar e desligar o Pix Automático

O par `--pix-automatic` / `--no-pix-automatic` controla o débito recorrente do Pix. Ele vem **desligado** por padrão e só faz sentido em produtos de assinatura.

<CodeGroup>
  ```bash Criar com Pix Automático theme={null}
  garu products create \
    --name "Plano Mensal" \
    --value 4990 \
    --pix --credit-card --pix-automatic \
    --subscription --subscription-type monthly
  ```

  ```bash Ligar em um produto existente theme={null}
  garu products update 456 --pix-automatic
  ```

  ```bash Desligar theme={null}
  garu products update 456 --no-pix-automatic
  ```
</CodeGroup>

<Card title="O que é o Pix Automático" icon="repeat" href="/guias/pix-automatico" horizontal>
  Entenda como o cliente autoriza uma vez no banco e os próximos ciclos caem sozinhos.
</Card>

## Cobranças agendadas com Pix Automático

`garu scheduled-charges create` agenda uma cobrança para um cliente já cadastrado. A partir da CLI 0.7.0, o `--methods` aceita o valor **`pix_automatic`** para débito recorrente.

<Warning>
  `--methods pix_automatic` **exige** `--type recurring` **e** um `--product-id`, e o produto precisa ter sido criado com `--pix-automatic`. Sem isso, a cobrança volta `400`.
</Warning>

### Receita completa: produto + cobrança recorrente

Crie o produto com Pix Automático ligado e depois agende a série recorrente apontando para ele:

<Steps>
  <Step title="Crie o produto com --pix-automatic">
    ```bash theme={null}
    garu products create \
      --name "Plano Mensal" \
      --value 4990 \
      --pix --credit-card --pix-automatic \
      --subscription --subscription-type monthly
    ```

    Guarde o `id` retornado — você vai usá-lo no `--product-id` do próximo passo.
  </Step>

  <Step title="Agende a cobrança recorrente com --methods pix_automatic">
    ```bash theme={null}
    garu scheduled-charges create --customer-id 42 --product-id 456 \
      --amount 49.90 --type recurring --due-date 2026-06-15 \
      --methods pix_automatic --recurrence-interval monthly
    ```

    O cliente autoriza a recorrência uma vez no app do banco e os ciclos seguintes são debitados sozinhos.
  </Step>
</Steps>

<Note>
  Aqui `--amount` (em `scheduled-charges`) é informado em Reais (`49.90`), enquanto `--value` (em `products`) é em centavos (`4990`). São o mesmo preço, em unidades diferentes.
</Note>

<CardGroup cols={2}>
  <Card title="Pix Automático (visão geral)" icon="circle-info" href="/guias/pix-automatico">
    Como o cliente autoriza, os próximos ciclos e o modelo de falha.
  </Card>

  <Card title="Como integrar Pix Automático" icon="screwdriver-wrench" href="/guias/integrar-pix-automatico">
    Receita de ponta a ponta via API, SDK e MCP.
  </Card>
</CardGroup>

## Recursos

<CardGroup cols={2}>
  <Card title="Repositório GitHub" icon="github" href="https://github.com/Garu-Pagamentos/garu-cli">
    Código-fonte e documentação técnica
  </Card>

  <Card title="Pacote npm" icon="npm" href="https://www.npmjs.com/package/@garuhq/cli">
    @garuhq/cli no npm
  </Card>
</CardGroup>

## Próximos Passos

<CardGroup cols={2}>
  <Card title="MCP Server" icon="plug" href="/guias/mcp-server">
    Conecte agentes de IA à API Garu
  </Card>

  <Card title="Node SDK" icon="js" href="/guias/node-sdk">
    Use a SDK para integrar no seu código
  </Card>
</CardGroup>