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

# CLI da Arara

> Envie mensagem, escute eventos, consulte templates e campanhas e chame qualquer endpoint da API pelo terminal. Binário único em Go, sem dependência de Node ou Python.

O `arara` é a CLI da Arara. Binário único em Go para macOS, Linux e Windows (amd64/arm64), sem Node e sem Python.

Serve para ver a API funcionando antes de escrever código e para a operação do dia a dia: conferir status de mensagem, acompanhar eventos, depurar webhook.

<Note>
  O `arara mcp` da CLI é um servidor MCP local e enxuto, separado do pacote `@ararahq/mcp`. Para conectar Claude, Cursor ou outro agente, use o [MCP Server](/mcp-server).
</Note>

```bash theme={null}
# Autenticar (abre o navegador)
arara login

# Enviar um template
arara send --to +5511999999999 --template confirmacao_pedido --vars "João,ARA-12345"

# Ver o payload e o custo estimado sem enviar
arara send --to +5511999999999 --template confirmacao_pedido --vars "João,ARA-12345" --dry-run

# Acompanhar eventos em tempo real
arara listen
```

## Instalação

**macOS / Linux**: detecta sistema e arquitetura, baixa o binário do GitHub Releases, confere o SHA-256 e instala em `/usr/local/bin` (ou `~/.local/bin` quando não há permissão de escrita):

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/ararahq/cli/main/install.sh | sh
```

Para fixar versão ou diretório, use `ARARA_VERSION` (ex.: `v0.2.0`) e `ARARA_INSTALL_DIR`.

<CardGroup cols={2}>
  <Card title="Windows (PowerShell)" icon="windows">
    ```powershell theme={null}
    iwr -useb https://raw.githubusercontent.com/ararahq/cli/main/install.ps1 | iex
    ```

    Instala em `%LOCALAPPDATA%\arara\bin` e adiciona ao PATH do usuário. Não precisa de admin.
  </Card>

  <Card title="Homebrew (macOS / Linux)" icon="apple">
    ```bash theme={null}
    brew install ararahq/tap/arara
    ```
  </Card>

  <Card title="Go install" icon="golang">
    ```bash theme={null}
    go install github.com/ararahq/cli/cmd/arara@latest
    ```
  </Card>

  <Card title="Download direto" icon="github">
    [github.com/ararahq/cli/releases](https://github.com/ararahq/cli/releases): tar.gz/zip por sistema e arquitetura, com `checksums.txt`.
  </Card>
</CardGroup>

Confira a instalação:

```bash theme={null}
arara --version
arara doctor
```

`arara doctor` verifica versão, autenticação e conectividade com a API.

## Autenticação

```bash theme={null}
arara login
```

Por padrão o login usa o OAuth Device Flow: a CLI mostra um código e um link, você aprova no navegador com a sua conta da Arara e a CLI guarda as credenciais. Elas ficam no keyring do sistema (Keychain no macOS, Secret Service no Linux, Credential Manager no Windows), com fallback para `~/.arara/config.yaml` (permissão 600).

Para automação (CI, servidor), autentique com uma chave de API. Prefira passar a chave por stdin, que não fica no histórico do shell nem na lista de processos:

```bash theme={null}
echo "$ARARA_API_KEY" | arara login
# ou
arara login --key "$ARARA_API_KEY"
```

Chaves são geradas no [Dashboard](https://app.ararahq.com), em **API Keys**, ou com `arara keys create --name "<onde a chave será usada>"`. Toda chave é de produção (`ara_live_...`).

<Warning>
  A Arara não tem modo de teste. Todo `arara send` entrega de verdade e debita do saldo da carteira. Use `--dry-run` para ver payload e custo estimado antes de enviar.
</Warning>

### Perfis e organizações

Para operar mais de uma conta, use perfis. A flag global `-p/--profile` escolhe o perfil de cada comando:

```bash theme={null}
arara profile add cliente-x
arara login --profile cliente-x
arara profile switch cliente-x
arara profile list
arara profile remove cliente-x
```

Se o seu usuário participa de várias organizações:

```bash theme={null}
arara org list
arara org use <slug>
```

`arara whoami` mostra o perfil ativo e `arara logout` remove as credenciais do perfil atual.

## Comandos

### `arara send`

Envia uma mensagem. Sem flags, abre um assistente interativo no terminal.

```bash theme={null}
arara send \
  --to +5511999999999 \
  --template confirmacao_pedido \
  --vars "João,ARA-12345"
```

| Flag | Descrição |
| - | - |
| `--to` | Telefone do destinatário (ex.: `+5511999999999`). |
| `--template` | Nome do template aprovado. |
| `--vars` | Variáveis do template separadas por vírgula. |
| `--body` | Texto livre. Só funciona com a [janela de 24h](/concepts/24h-window) aberta. Não combina com `--template`. |
| `--scheduled-at` | Agenda o envio (ISO 8601, ex.: `2026-10-01T09:00:00-03:00`). |
| `--dry-run` | Mostra payload e custo estimado sem enviar (estimativa só para template). |
| `--watch` | Espera a mensagem chegar a um status final (entregue, lida, falhou) e sai. |
| `--watch-timeout` | Tempo máximo do `--watch`. |

### `arara listen`

Escuta os eventos da conta em tempo real (SSE):

```bash theme={null}
arara listen
arara listen --events message.status_updated,message.received
```

Para desenvolver um receptor de webhook local, encaminhe cada evento via POST:

```bash theme={null}
arara listen --forward-to http://localhost:3000/api/webhooks
```

Com `--capture`, a CLI registra um listener temporário no backend e o evento chega assinado no seu handler local (header `X-Arara-Signature`), sem expor o localhost com túnel. Se o ambiente não suportar captura, a CLI volta ao modo passivo e avisa.

```bash theme={null}
arara listen --capture --forward-to http://localhost:3000/api/webhooks
```

### `arara logs`

```bash theme={null}
arara logs                 # mensagens recentes
arara logs --limit 50
arara logs --follow        # eventos ao vivo em NDJSON, bom para pipe
arara logs --tail          # eventos ao vivo em visualizador no terminal
```

### `arara api`

Chamada autenticada a qualquer endpoint, útil quando ainda não existe subcomando:

```bash theme={null}
arara api /v1/templates --jq '.data[].name'
arara api -X POST /v1/contacts/batch --input contatos.json
echo '{"phones":["+5511999999999"]}' | arara api -X POST /v1/conversations/window-status --input -
```

| Flag | Descrição |
| - | - |
| `-X, --method` | Método HTTP (padrão `GET`). |
| `--body` | Corpo JSON inline. |
| `--input` | Lê o corpo de um arquivo, ou de stdin com `-`. |
| `-H, --header` | Header extra (`Nome:Valor`), pode repetir. |
| `--silent` | Não imprime o corpo da resposta (o código de saída continua valendo). |

### Templates, campanhas, contatos, chaves e números

| Comando | Função |
| - | - |
| `arara templates list` | Lista os templates. |
| `arara templates status <template-id>` | Status de aprovação de um template. |
| `arara templates delete <template-id>` | Remove um template. |
| `arara campaigns list` | Lista campanhas. |
| `arara campaigns create --name --template --contacts` | Cria campanha. `--contacts` aceita JSON inline ou `@arquivo.json`. |
| `arara campaigns status <campaign-id>` | Status e progresso de uma campanha. |
| `arara campaigns estimate --template --count` | Estima o custo antes de disparar. |
| `arara contacts list [-q busca] [--page] [--size]` | Lista contatos, paginado. |
| `arara contacts search -q <termo>` | Busca por nome ou telefone. |
| `arara contacts import --file contatos.json` | Importa contatos de um arquivo JSON. |
| `arara contacts stats` | Estatísticas da base de contatos. |
| `arara keys list` | Lista as chaves de API. |
| `arara keys create --name <nome>` | Cria uma chave. |
| `arara keys revoke <key-id>` | Revoga uma chave. |
| `arara numbers` | Lista os números da organização. |

A criação de template não tem subcomando. Use o [Dashboard](https://app.ararahq.com) ou `arara api -X POST /v1/templates --input template.json` (ver [Templates](/concepts/templates)).

### Outros comandos

| Comando | Função |
| - | - |
| `arara status` | Painel ao vivo no terminal com métricas, mensagens e saldo (atualiza a cada 30s). Aliases: `dash`, `dashboard`. |
| `arara doctor` | Diagnóstico de versão, autenticação e conectividade. |
| `arara init` | Cria `.arara/` no projeto: `settings.json`, um comando de exemplo, um hook de exemplo e a entrada `credentials*` no `.gitignore`. |
| `arara upgrade` | Verifica se há versão nova. Com `--install`, baixa, confere o SHA-256 e troca o binário. |
| `arara telemetry on/off/status` | Telemetria anônima de uso da CLI. Desligada por padrão. |
| `arara config list/get/set` | Configuração em `~/.arara/config.yaml` (`profile`, `api-url`, `output`). |
| `arara settings list/get/set` | Preferências da CLI (tema, hooks, plugins), em camadas usuário e projeto. |
| `arara completion <shell>` | Gera autocomplete (bash, zsh, fish, powershell). `arara completion install` instala. |
| `arara commands list/show/which` | Lista e inspeciona comandos definidos pelo usuário. |
| `arara mcp` | Roda a CLI como servidor MCP local (ver abaixo). |
| `arara docs` | Abre esta documentação no navegador. |

Use `arara <comando> --help` para ver todas as flags.

## Formatos de saída

Flags globais, valem para qualquer comando:

| Flag | Descrição |
| - | - |
| `-o, --output` | `text` (padrão), `json`, `table` ou `stream-json` (NDJSON). |
| `--jq <expr>` | Filtra a saída JSON com uma expressão jq embutida (não precisa do `jq` instalado). |
| `--no-color` / `--theme mono` | Saída sem cores. `NO_COLOR=1` e `ARARA_THEME=mono` têm o mesmo efeito. |
| `-v, --verbose` | Mostra detalhes das requisições, com segredos mascarados. |

```bash theme={null}
arara logs -o json
arara send --to +5511999999999 --template confirmacao_pedido --vars "João" --watch -o stream-json
```

## Hooks

Scripts executados em eventos do ciclo de vida, configurados via `arara settings`:

```bash theme={null}
arara settings set hooks.preSend "~/hooks/log-send.sh"
arara settings set hooks.preSend "./scripts/checa-template.sh" --project
```

| Evento | Chave | Comportamento |
| - | - | - |
| `pre-send` | `hooks.preSend` | Saída diferente de zero cancela o envio. |
| `post-deliver` | `hooks.postDeliver` | Só registra; não interrompe. |
| `pre-campaign` | `hooks.preCampaign` | Saída diferente de zero cancela a campanha. |
| `post-campaign` | `hooks.postCampaign` | Só registra; não interrompe. |
| `on-error` | `hooks.onError` | Só registra; não interrompe. |

O script recebe o payload do evento em JSON pelo stdin e as variáveis `ARARA_EVENT`, `ARARA_PROFILE` e `ARARA_MODE`. O tempo limite padrão é 30s, ajustável em `hookTimeoutSeconds`.

```bash theme={null}
#!/usr/bin/env bash
echo "[$(date)] arara $ARARA_EVENT (profile=$ARARA_PROFILE)" >> ~/.arara/audit.log
cat > /dev/null
exit 0
```

## Plugins e comandos próprios

* **Plugins**: qualquer executável `arara-<nome>` no `PATH` (ou em `plugins.searchPaths`) vira `arara <nome>`.
* **Comandos em Markdown**: arquivos `.md` em `./.arara/commands/` (projeto) ou `~/.arara/commands/` (usuário) viram subcomandos. Comandos nativos sempre têm prioridade, então um projeto não consegue sobrescrever `arara send`.

<Warning>
  O corpo de um comando em Markdown é shell executado com as permissões do seu usuário. Trate `.arara/commands/` de um projeto como trataria o `Makefile` dele.
</Warning>

## Servidor MCP da CLI

`arara mcp` expõe um conjunto enxuto de ferramentas para clientes MCP, reaproveitando a autenticação da CLI. Por padrão só ferramentas de leitura (templates, status de mensagem, contatos, métricas, saldo, números, estimativa de campanha). As de escrita (envio, campanha, importação de contatos) só aparecem com `--allow-write-tools`.

```bash theme={null}
arara mcp --dry-run                      # lista as ferramentas sem subir o servidor
arara mcp --dry-run --allow-write-tools
```

Este servidor é diferente do `@ararahq/mcp`, que tem login OAuth próprio e ferramentas pensadas para operação em linguagem natural. Para agentes de IA, use o [MCP Server](/mcp-server).

## CI/CD

```yaml theme={null}
- name: Instalar a CLI
  run: curl -fsSL https://raw.githubusercontent.com/ararahq/cli/main/install.sh | sh
- name: Autenticar
  run: echo "$ARARA_API_KEY" | arara login
  env:
    ARARA_API_KEY: ${{ secrets.ARARA_API_KEY }}
- name: Avisar deploy
  run: arara send --to +5511999999999 --template aviso_deploy --vars "${{ github.sha }}"
```

Em CI, autentique com chave de API. O login OAuth depende de aprovação no navegador.

## Variáveis de ambiente

| Variável | Descrição |
| - | - |
| `ARARA_THEME` | `auto` (padrão) ou `mono`. |
| `NO_COLOR` | Desliga cores. |
| `ARARA_OAUTH_CLIENT_ID` | Client ID OAuth customizado, quando o seu ambiente exigir. |
| `ARARA_VERSION` | Só no `install.sh`: versão a instalar. |
| `ARARA_INSTALL_DIR` | Só no `install.sh`: diretório de instalação. |

A URL da API é configurada por perfil (`arara config set api-url <url>`). O padrão é a produção da Arara.

## Próximos passos

<CardGroup cols={2}>
  <Card title="MCP Server" icon="server" href="/mcp-server">
    Conecte Claude, Cursor ou outro cliente MCP à sua conta.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    A API REST por baixo dos comandos.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.