CLI

A CLI da SIPPulse AI gerencia agentes, modelos, implantações de canal, threads e fala para texto pelo seu terminal. O pacote npm é @sippulseai/cli e o binário instalado é spai. Requer Node.js 22.14 ou superior; Bun não é necessário.

Esta página cobre o contrato público de instalação e autenticação e as famílias de comandos. Para usar a SIPPulse AI de dentro de um cliente MCP, veja MCP remoto.

Requisitos e instalação

Este é o primeiro release candidate. Instale explicitamente com a tag next:

npm install -g @sippulseai/cli@next
spai --version
spai --help

Ou execute sem instalação global:

npx @sippulseai/cli@next --help

Todo comando aceita spai <comando> --help. Comandos e saída podem mudar antes da versão 1.0.

Autenticação

As credenciais vêm de uma sessão OAuth criada por spai auth login, ou da variável de ambiente SIPPULSE_AI_API_KEY, ou do arquivo de configuração protegido. Rode spai whoami primeiro para conferir qual identidade e projeto estão ativos.

Nunca coloque uma chave API em um argumento de comando, em um arquivo commitado ou em um prompt enviado a um servidor MCP.

Navegador e fluxo de dispositivo

spai auth login            # OAuth pelo navegador
spai auth login --device   # fluxo de autorização por dispositivo
spai auth login --read-only
spai auth login --scope llm --scope tts

Um login normal pede todos os escopos da API. --read-only pede apenas todos os escopos de leitura aplicáveis, então a sessão não altera nada. --scope pede uma sessão mais restrita e pode ser repetido; comandos de inferência exigem --scope llm|tts|embeddings|decisions. --scope não pode ser combinado com --read-only. --device usa o fluxo de autorização por dispositivo para ambientes sem navegador. Uma sessão anterior a um escopo necessário precisa ser autorizada de novo; a renovação nunca amplia os escopos silenciosamente. A descoberta de modelos exige spai:models:read.

Chave API para CI

Para uso não interativo, forneça uma chave API pelo ambiente ou pela entrada de configuração protegida:

export SIPPULSE_AI_API_KEY="sua_chave_api"
spai whoami

Como alternativa, armazene-a de forma interativa, sem expô-la ao histórico do shell:

spai config set apiKey

A chave do ambiente tem precedência sobre as credenciais armazenadas, e uma chave API vinculada a um projeto sempre vence. Nunca passe a chave como argumento de comando. Crie e escope chaves em Chaves API.

Logout e status da sessão

spai whoami
spai auth logout

spai auth logout informa se o servidor de autorização revogou o token armazenado antes de removê-lo localmente. Revogar uma autorização OAuth na plataforma é imediato; veja Acessos OAuth.

Ambientes e projetos

A API padrão é https://api.sippulse.ai. Use --url para selecionar outro ambiente e --project para selecionar um contexto de projeto.

spai whoami --json
spai agents list --limit 10
spai models list --limit 10
spai deploy sip list
spai threads list
spai stt models

Famílias de comandos

Família	Comandos
Identidade	whoami
Agentes	agents list|show|validate|create|update|delete|export|apply|edit
Modelos	models list|show
Secrets	secrets list|create|update|delete|clone
Implantações SIP	deploy sip list|show|apply
Implantações WhatsApp	deploy whatsapp list|show|create|update|activate|deactivate|delete
Implantações Telegram	deploy telegram list|show|create|update|activate|deactivate|delete
Threads	threads list|show|create|run|stream|close|delete
Fala para texto	stt models|transcribe|status
Modelos de linguagem (direto)	llm models|complete
Síntese de voz (direto)	tts models|voices|synthesize
Embeddings	embeddings create
Decisões	decisions models|ask
Análises	analytics catalog|query
Configuração	config list|get|set|unset
Autenticação	auth login|logout
Agent skill	install-skill

threads run executa um turno real e é cobrado como uma execução normal do agente. threads stream existe apenas na CLI. stt transcribe [FILE] aceita --async e nunca faz polling oculto.

Inferência direta de modelos

spai llm models
spai llm complete "Resuma esta chamada" --model MODEL
spai tts voices --model MODEL
spai tts synthesize "Olá" --model MODEL --voice VOICE --output ola.mp3
spai embeddings create "Um texto" --model MODEL
spai decisions models
spai decisions ask '{"question": "..."}'

llm complete [prompt] não usa streaming e lê stdin quando o prompt é omitido; aceita --model, --system, --temperature e --max-tokens. tts voices aceita --model; tts synthesize [text] exige --model, --voice e --output FILE e grava os bytes de áudio nesse arquivo. embeddings create [text] aceita --model e lê stdin quando o texto é omitido. decisions ask [request] aceita um argumento JSON ou stdin.

Um comando cujo escopo de inferência não foi concedido falha antes de qualquer requisição com a correção exata, por exemplo This command needs spai:llm:execute. Run: spai auth login --scope llm. Com uma chave API não há verificação local de escopo.

Análises de uso

spai analytics catalog --dataset usage
spai analytics query usage --measure price_local --dimension model --range last_56d --granularity week
spai analytics query --file query.json --format csv

analytics catalog lista os conjuntos, medidas, dimensões e limites da sessão. analytics query [dataset] monta uma consulta declarativa com --measure, --dimension, --range (ou --from com --to), --granularity, --tz, --filter 'dim op v1,v2' repetível, --compare previous_period, --order by:dir repetível e --limit. --file query.json envia uma consulta inteira e não pode ser combinado com as flags de construção. --format table|json|csv escolhe a saída (JSON por padrão em pipes) e --vega imprime uma spec Vega-Lite com os dados embutidos. Os comandos exigem spai:analytics:read, incluído no login padrão; uma sessão sem ele falha antes de qualquer requisição com Run: spai auth login. Veja Análises de Uso.

Manifestos

Agentes e implantações usam manifestos YAML ou JSON estritos. Mantenha os manifestos de implantação separados dos manifestos de agente.

version: 1
kind: Agent
metadata:
  name: support
spec: {}

Use agents export, edite uma cópia sanitizada e depois agents apply --file agent.yaml. Apenas referências ${ENV_VAR} completas são expandidas. Referências ao cofre da SIPPulse AI usam e devem permanecer como referências.

agents validate --file agent.yaml valida a configuração de modelo sem gravar um agente, sem sondar um provedor e sem garantir inferência paga. Ele imprime os errors e warnings acionáveis do servidor; valid: false sai com código diferente de zero.

Para mudanças pequenas, prefira flags curadas a um manifesto:

spai agents create --name NAME --llm-model MODEL --tts-model MODEL \
  --tts-voice VOICE --language LANG
spai agents update ID --description TEXT

Secrets

Secrets são somente escrita. Passe o valor por uma variável de ambiente ou por stdin, nunca como argumento literal:

spai secrets create --name NAME --env ENV_VAR
spai secrets create --name NAME --stdin
spai secrets list
spai secrets update ID --env ENV_VAR
spai secrets clone ID --from-project SRC --to-project DST

secrets list retorna metadados sem valores. Clone apenas com projeto de origem e destino explícitos. Referências a secrets do projeto usam .

Saída e códigos de saída

Use --json para saída legível por máquina e --fields id,name para projetar campos. Defina o modo padrão com config set output --value json|text; as flags de uma invocação têm precedência.

Erros são JSON no stderr com códigos de saída estáveis:

Código	Significado
2	Erro de uso
3	Não encontrado
4	Autenticação
5	Conflito ou confirmação ausente

Comandos destrutivos (agents delete, exclusões de implantação, threads delete) exigem confirmação explícita. Scripts devem passar --yes.

Instalando o Agent Skill

spai install-skill

A instalação padrão grava as instruções empacotadas para agentes de código no projeto atual em .agents/skills/sippulse-ai-cli/ e .claude/skills/sippulse-ai-cli/. Use --target agents|claude|both para selecionar os alvos e --global para instalar no escopo do usuário em vez do projeto.

CLI e MCP remoto

O pacote npm contém a CLI e sua skill, não o servidor MCP. O endpoint do MCP remoto é https://api.sippulse.ai/mcp e serve apenas clientes MCP; ele não é a URL base da API REST. Veja MCP remoto para o fluxo de consentimento OAuth e as ferramentas disponíveis.

Solução de problemas

Sintoma	O que significa e o que fazer
401	A sessão expirou ou foi revogada. Rode spai auth login de novo, ou corrija SIPPULSE_AI_API_KEY.
403 insufficient_scope	A autorização não tem a permissão pedida. Faça login de novo incluindo esse escopo, ou use uma chave com o RBAC correto.
Ambiente errado	Você está apontando para outra API. Confira --url e confirme que https://api.sippulse.ai é o ambiente desejado.
Sessão revogada ou expirada	Faça login de novo com spai auth login. Se um acesso foi revogado na plataforma, autorize de novo.
Comando destrutivo bloqueado	Ele precisa de confirmação explícita. Confirme interativamente ou passe --yes em um script.
Upgrade de um release candidate anterior	Uma sessão que armazenou uma URL /mcp ou /v1 falha com erro de URL em todo comando. Repare com spai auth logout, depois spai config unset url, depois spai auth login.

A audience do API resource de acesso da CLI e da API REST está migrando de /v1 para a raiz da API. Quando essa mudança chegar a um ambiente, as concessões OAuth existentes da CLI e da API são forçadas a reautenticar; concessões criadas para o endpoint MCP (/mcp) não são afetadas.

Escopo do release candidate

Este é um release candidate ainda em preparação para promoção. Operações de escrita ao vivo, inferência paga, transcrição e OAuth interativo exigem validação completa de ponta a ponta antes da promoção do release.