CLI da Arara

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.

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.

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

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.

Windows (PowerShell)

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.

Homebrew (macOS / Linux)

brew install ararahq/tap/arara

Go install

go install github.com/ararahq/cli/cmd/arara@latest

Download direto

github.com/ararahq/cli/releases: tar.gz/zip por sistema e arquitetura, com checksums.txt.

Confira a instalação:

arara --version
arara doctor

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

Autenticação

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:

echo "$ARARA_API_KEY" | arara login
# ou
arara login --key "$ARARA_API_KEY"

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

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.

Perfis e organizações

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

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:

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.

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

arara listen
arara listen --events message.status_updated,message.received

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

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.

arara listen --capture --forward-to http://localhost:3000/api/webhooks

`arara logs`

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:

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 ou arara api -X POST /v1/templates --input template.json (ver 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.

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:

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.

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

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.

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.

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.

CI/CD

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

SDKs

Ferramentas

Instalação

Windows (PowerShell)

Homebrew (macOS / Linux)

Go install

Download direto

Autenticação

Perfis e organizações

Comandos

`arara send`

`arara listen`

`arara logs`

`arara api`

Templates, campanhas, contatos, chaves e números

Outros comandos

Formatos de saída

Hooks

Plugins e comandos próprios

Servidor MCP da CLI

CI/CD

Variáveis de ambiente

Próximos passos

MCP Server

API Reference

​Instalação

Windows (PowerShell)

Homebrew (macOS / Linux)

Go install

Download direto

​Autenticação

​Perfis e organizações

​Comandos

​arara send

​arara listen

​arara logs

​arara api

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

​Outros comandos

​Formatos de saída

​Hooks

​Plugins e comandos próprios

​Servidor MCP da CLI

​CI/CD

​Variáveis de ambiente

​Próximos passos

MCP Server

API Reference

Instalação

Autenticação

Perfis e organizações

Comandos

`arara send`

`arara listen`

`arara logs`

`arara api`

Templates, campanhas, contatos, chaves e números

Outros comandos

Formatos de saída

Hooks

Plugins e comandos próprios

Servidor MCP da CLI

CI/CD

Variáveis de ambiente

Próximos passos