CLI KambaSMS

1. Instala a CLI

Requer Node.js 20 ou superior. Instala diretamente pelo npm; não precisas de descarregar um ficheiro manualmente.

npm install --global @kambasms/cli
kamba --version
kamba --help

npm install --global ./kambasms-cli-0.1.0.tgz

2. Configura a tua chave API live

Cria uma chave API live na conta. Envios de produção exigem Sender ID aprovado e créditos SMS disponíveis. Substitui o marcador abaixo pela tua chave. A CLI não lê ficheiros .env automaticamente nem guarda a chave.

PowerShell

$env:KAMBA_API_KEY = 'SUA_CHAVE_API'

Bash / zsh

export KAMBA_API_KEY='YOUR_API_KEY'

kamba doctor --live
kamba balance --live

Doctor verifica apenas a configuração local e o formato da chave; balance faz um pedido autenticado à API. Não coloques a chave em commits nem logs partilhados.

3. Revê e envia o teu SMS

Substitui +2449XXXXXXXX por um número que controlas. Revê primeiro o pedido com --dry-run, que não envia nada. Usa uma chave de idempotência única para cada nova operação.

kamba sms send --live --to +2449XXXXXXXX --text "O seu pedido foi recebido." --idempotency-key pedido-cli-001 --dry-run

O comando seguinte envia um SMS real e consome créditos da conta. --yes confirma explicitamente o envio pago. Unicode pode consumir vários créditos; a CLI não estima o custo.

kamba sms send --live --yes --to +2449XXXXXXXX --text "O seu pedido foi recebido." --idempotency-key pedido-cli-001
kamba history --live

Um pedido aceite não comprova entrega. Substitui ID pelo identificador devolvido para procurar nas últimas 100 mensagens. A ausência do histórico recente não prova que não houve envio.

kamba message ID --live --json

Opcional: usar a Sandbox

Para simular sem SMS reais, define KAMBA_TEST_KEY com uma chave Sandbox e omite --live e --yes. A CLI mantém Sandbox como padrão; produção exige sempre --live.

Automação e diagnóstico

--json escreve resultados em stdout e erros em stderr. Códigos de saída: 0 concluído, 1 erro, 2 HTTP 202 pendente/incerto. Sem retries nem redirecionamentos automáticos. Timeout padrão de 15 segundos; --timeout aceita 1000–60000 milissegundos. Histórico e dry-run podem conter dados pessoais: protege os logs de CI.

Pedido aceite não é comprovativo de entrega. O saldo de teste não é o saldo de produção. Esta primeira versão suporta SMS individual; OTP, Verify, envio em massa e encaminhamento de webhooks não estão incluídos.