CLI

The SIPPulse AI CLI manages agents, models, channel deployments, threads and speech-to-text from your terminal. The npm package is @sippulseai/cli and the installed binary is spai. It requires Node.js 22.14 or later; Bun is not required.

This page covers the public install and authentication contract and the command families. To use SIPPulse AI from an MCP client instead, see Remote MCP.

Requirements and installation

This is the first release candidate. Install it explicitly with the next tag:

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

Or run it without a global installation:

npx @sippulseai/cli@next --help

Every command supports spai <command> --help. Commands and output may evolve before 1.0.

Authentication

Credentials come from an OAuth session created by spai auth login, or from the SIPPULSE_AI_API_KEY environment variable, or from the protected config file. Run spai whoami first to check which identity and project are active.

Never put an API key in a command argument, in a committed file, or in a prompt sent to an MCP server.

Browser and device flow

spai auth login            # browser OAuth
spai auth login --device   # device authorization flow
spai auth login --read-only
spai auth login --scope llm --scope tts

A normal login requests all API scopes. --read-only requests all applicable read scopes only, so the session cannot change anything. --scope requests a narrower session and can be repeated; inference commands need --scope llm|tts|embeddings|decisions. --scope cannot be combined with --read-only. --device uses the device authorization flow for environments without a browser. A session that predates a required scope must be authorized again; refresh never silently expands its grants. Model discovery needs spai:models:read.

API key for CI

For non-interactive use, supply an API key through the environment or the protected config input:

export SIPPULSE_AI_API_KEY="your_api_key"
spai whoami

Alternatively, store it interactively without echoing it to your shell history:

spai config set apiKey

The environment key takes precedence over stored credentials, and a project-bound API key always wins. Never pass the key as a command argument. Create and scope keys in API Keys.

Logout and session status

spai whoami
spai auth logout

spai auth logout reports whether the authorization server revoked the stored token before removing it locally. Revoking an OAuth authorization from the platform is immediate; see OAuth access.

Environments and projects

The default API is https://api.sippulse.ai. Use --url to select another environment and --project to select a project context.

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

Command families

Family	Commands
Identity	whoami
Agents	agents list|show|validate|create|update|delete|export|apply|edit
Models	models list|show
Secrets	secrets list|create|update|delete|clone
SIP deployments	deploy sip list|show|apply
WhatsApp deployments	deploy whatsapp list|show|create|update|activate|deactivate|delete
Telegram deployments	deploy telegram list|show|create|update|activate|deactivate|delete
Threads	threads list|show|create|run|stream|close|delete
Speech-to-text	stt models|transcribe|status
Language models (direct)	llm models|complete
Text-to-speech (direct)	tts models|voices|synthesize
Embeddings	embeddings create
Decisions	decisions models|ask
Analytics	analytics catalog|query
Config	config list|get|set|unset
Auth	auth login|logout
Agent skill	install-skill

threads run executes a real turn and is billed as a normal agent execution. threads stream is CLI-only. stt transcribe [FILE] supports --async and never runs hidden polling.

Direct model inference

spai llm models
spai llm complete "Summarize this call" --model MODEL
spai tts voices --model MODEL
spai tts synthesize "Hello" --model MODEL --voice VOICE --output hello.mp3
spai embeddings create "Some text" --model MODEL
spai decisions models
spai decisions ask '{"question": "..."}'

llm complete [prompt] is non-streaming and reads stdin when the prompt is omitted; it accepts --model, --system, --temperature, and --max-tokens. tts voices accepts --model; tts synthesize [text] requires --model, --voice, and --output FILE and writes the audio bytes there. embeddings create [text] takes --model and reads stdin when the text is omitted. decisions ask [request] takes a JSON argument or stdin.

A command whose inference scope was not granted fails before any request with the exact fix, for example This command needs spai:llm:execute. Run: spai auth login --scope llm. With an API key there is no local scope check.

Usage analytics

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 lists the datasets, measures, dimensions and limits for the session. analytics query [dataset] builds a declarative query with --measure, --dimension, --range (or --from with --to), --granularity, --tz, repeatable --filter 'dim op v1,v2', --compare previous_period, repeatable --order by:dir and --limit. --file query.json sends a whole query and cannot be combined with the building flags. --format table|json|csv selects the output (JSON by default in pipes) and --vega prints a Vega-Lite spec with the data inline. The commands need spai:analytics:read, included in the default login; a session without it fails before any request with Run: spai auth login. See Usage Analytics.

Manifests

Agents and deployments use strict YAML or JSON manifests. Keep deployment manifests separate from agent manifests.

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

Use agents export, edit a sanitized copy, then agents apply --file agent.yaml. Only complete ${ENV_VAR} references are expanded. SIPPulse AI vault references use and must remain references.

agents validate --file agent.yaml validates the model configuration without writing an agent, probing a provider or guaranteeing paid inference. It prints the server's actionable errors and warnings; valid: false exits nonzero.

For small changes, prefer curated flags over a manifest:

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

Secrets

Secrets are write-only. Pass the value through an environment variable or stdin, never as a literal argument:

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 returns metadata without values. Clone only with explicit source and destination projects. Project secret references use .

Output and exit codes

Use --json for machine-readable output and --fields id,name to project fields. Set the default mode with config set output --value json|text; the per-invocation flags override it.

Errors are JSON on stderr with stable exit codes:

Exit code	Meaning
2	Usage error
3	Not found
4	Authentication
5	Conflict or missing confirmation

Destructive commands (agents delete, deployment deletes, threads delete) require explicit confirmation. Scripts must pass --yes.

Installing the Agent Skill

spai install-skill

The default installs the bundled instructions for coding agents into the current project at .agents/skills/sippulse-ai-cli/ and .claude/skills/sippulse-ai-cli/. Use --target agents|claude|both to select targets and --global to install in your user scope instead of the project.

CLI and Remote MCP

The npm package contains the CLI and its skill, not the MCP server. The remote MCP endpoint is https://api.sippulse.ai/mcp and is only for MCP clients; it is not the REST API base URL. See Remote MCP for the OAuth consent flow and available tools.

Troubleshooting

Symptom	What it means and what to do
401	The session expired or was revoked. Run spai auth login again, or fix SIPPULSE_AI_API_KEY.
403 insufficient_scope	The authorization lacks the requested permission. Log in again including that scope, or use a key with the right RBAC.
Wrong environment	You are pointing at another API. Check --url and confirm https://api.sippulse.ai is the intended environment.
Revoked or expired session	Re-login with spai auth login. If an access was revoked in the platform, re-authorize it.
Destructive command blocked	It needs explicit confirmation. Confirm interactively, or pass --yes in a script.
Upgrade from an earlier release candidate	A session that stored an /mcp or /v1 URL fails with a URL error on every command. Repair it with spai auth logout, then spai config unset url, then spai auth login.

The API-resource audience for CLI and REST API access is moving from /v1 to the API root. When that change reaches an environment, existing CLI and API OAuth grants are forced to reauthenticate; grants created for the MCP endpoint (/mcp) are unaffected.

Release candidate scope

This is a release candidate still being prepared for promotion. Live write operations, paid inference, transcription and interactive OAuth require complete end-to-end validation before the release is promoted.