@sippulse/niva

Command-line tool for managing and debugging NIVA — a low-code platform for building intelligent IVR systems with AI integration.

What do you want to do?

| Goal | Commands | Example | |------|----------|---------| | Debug a failed call | calls trace, calls transcript, calls show | niva calls history --status failed | | Monitor system health | fs status, fs capacity, fs sofia | niva fs status | | Design IVR plans | plans create, plans validate, plans publish | niva plans list | | Analyze speech data | dashboard sentiment, calls search-text | niva calls search-text "billing issue" | | Test a plan via chat | chat test, ws chat | niva chat test <planId> | | Integrate with Claude Code | install-skill | niva install-skill |

Quick Start

npm i -g @sippulse/niva

niva config set url https://niva.yourcompany.com
niva config set api-key niva_xxx

niva fs status

Requirements: Node.js >= 22 (for native WebSocket support)

Alternative install methods:

npx @sippulse/niva calls list          # one-shot (no install)
bunx @sippulse/niva dashboard metrics   # bun alternative
npm i -D @sippulse/niva                 # project-local

Command Reference

Call Management

niva calls list                          List active calls
niva calls show <callRecordId>           Show call detail (CDR)
niva calls history [options]             Search call records with filters
niva calls hangup <uuid>                 Hang up an active call
niva calls trace <callRecordId>          Node-by-node execution trace
niva calls transcript <callRecordId>     Transcription + speech analytics
niva calls search-text <query>           Semantic search across transcriptions
niva calls inspect <uuid>                Inspect active call (node, vars, path)
niva calls follow <uuid>                 Stream live transcription (Ctrl+C to stop)

calls history filters:

| Flag | Description | |------|-------------| | --from <date> | Start date (YYYY-MM-DD) | | --to <date> | End date | | --status <s> | answered, missed, failed, busy | | --plan <id> | Filter by visual plan ID | | --caller <search> | Search caller ID | | --has-recording | Only calls with recording | | --has-transcription | Only calls with transcription | | --min-duration <s> | Minimum duration (seconds) | | --max-duration <s> | Maximum duration (seconds) | | --page <n> | Page number (default: 1) | | --limit <n> | Items per page (default: 20) |

IVR Plan Design

niva plans list [--search <term>]        List visual plans
niva plans show <planId>                 Show plan details and settings
niva plans create <name> [options]       Create a new plan
niva plans edit <planId> [options]       Update plan draft (execution plan)
niva plans configure <planId> [options]  Configure settings, metadata, DIDs
niva plans validate [planId]             Validate a plan (--file for local)
niva plans test <planId> --extension <e> Start a test call
niva plans publish <planId> [--notes]    Publish the current draft
niva plans versions <planId>             List version history
niva plans export <planId>               Export plan as JSON to stdout
niva plans delete <planId>               Delete a plan

plans configure options:

| Flag | Description | |------|-------------| | --name <name> | Plan name | | --description <text> | Plan description | | --recording / --no-recording | Toggle call recording | | --transcription / --no-transcription | Toggle transcription | | --transcription-language <code> | Transcription language (e.g. pt-BR) | | --anonymize / --no-anonymize | Toggle PII anonymization | | --speech-analytics / --no-speech-analytics | Toggle speech analytics | | --topics <list> | Topic detection topics (comma-separated) | | --assign-did <id> | Assign phone number to plan | | --unassign-did <id> | Unassign phone number | | --list-dids | Show assigned and available numbers |

System Monitoring

niva fs status                           Health check (DB, Redis, FreeSWITCH)
niva fs capacity                         Channel usage, license, AI usage
niva fs sofia                            SIP profile status
niva fs registrations                    Connected SIP endpoints
niva fs channels                         Active FreeSWITCH channels
niva fs dump <uuid>                      Dump channel variables for a call
niva fs show <entity>                    FreeSWITCH show command

fs show entities: channels, calls, registrations, codecs, modules, aliases

Speech Analytics & Dashboard

niva dashboard metrics [--from] [--to]   Call metrics (total, answered, missed)
niva dashboard sentiment [options]       Sentiment distribution
niva dashboard topics [--limit <n>]      Top discussed topics
niva dashboard intents [--limit <n>]     Detected intents
niva dashboard trend [--granularity]     Sentiment trend over time
niva dashboard hourly                    Call volume by hour of day
niva dashboard top-plans [--limit <n>]   Top IVR plans by volume

Chat Testing

niva chat test <planId>                  Interactive test chat (isolated)
niva chat stop <sessionId>              Stop a test chat session
niva ws chat <planId>                    Chat with published plan (production)
niva ws session <planId>                 Create session (returns wsUrl)

chat test runs the plan in isolation (no production traffic). ws chat hits the live endpoint.

Outbound Calls

niva originate start --plan <id> --destination <target> [options]

| Flag | Description | |------|-------------| | --plan <id> | Visual plan ID (required) | | --destination <target> | Phone number or SIP URI (required) | | --caller-id <number> | Caller ID to display | | --caller-id-name <name> | Caller ID name | | --timeout <seconds> | Ring timeout | | --var <key=value> | Set call variable (repeatable) |

TTS Resources

niva tts voices [--language <code>] [--model <m>]   List voices
niva tts models                                      List TTS models
niva tts languages                                   List languages

Other

niva ai agents                           List AI agents
niva audio-files list                    List audio files
niva schedules list                      List routing schedules
niva channels list [--type <type>]       List channels (SIP, Telegram, etc.)
niva storage usage                       Storage usage breakdown
niva nodes list                          List IVR node types
niva nodes show <type>                   Node type details
niva nodes schema <type>                 JSON Schema for node config

Configuration

niva config set <key> <value>            Set config (url, api-key)
niva config get [key]                    Get config value
niva config show                         Show full config

Config stored at ~/.niva/config.json (mode 0600 on POSIX).

Global Options

| Option | Description | |--------|-------------| | --url <url> | Server URL (overrides config/env) | | --api-key <key> | API key (overrides config/env) | | --json | JSON output | | --output <format> | json, table, or plain | | --fields <list> | Comma-separated fields (JSON mode) | | --yes | Skip confirmation prompts | | --no-color | Disable colors |

Output Formats

niva calls history --json                          # JSON output
niva calls history --output table                  # Table output (default in TTY)
niva calls history --json --fields id,status       # Select specific fields
niva calls history --json | jq '.items[].status'   # Pipe-friendly

Auto-detection: table when connected to a terminal, JSON when piped.

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | NIVA_URL | Server URL | http://localhost:3000 | | NIVA_API_KEY | API key for authentication | — | | NIVA_INSECURE | Skip TLS verification (true) | — |

Priority: CLI flags > environment variables > config file > defaults

CI/CD Usage

# GitHub Actions
- name: Deploy IVR plan
  env:
    NIVA_URL: ${{ secrets.NIVA_URL }}
    NIVA_API_KEY: ${{ secrets.NIVA_API_KEY }}
  run: |
    npx @sippulse/niva plans validate my-plan-id
    npx @sippulse/niva plans publish my-plan-id --notes "deploy ${{ github.sha }}"

# Bitbucket Pipelines
- step:
    script:
      - npx @sippulse/niva fs status
      - npx @sippulse/niva plans publish $PLAN_ID --notes "build $BITBUCKET_BUILD_NUMBER"

Claude Code Integration

Install the NIVA CLI skill for Claude Code to enable AI-assisted IVR management:

niva install-skill            # Install to current project (.claude/skills/)
niva install-skill --global   # Install globally (~/.claude/skills/)

Once installed, Claude Code can use the NIVA CLI to debug calls, create plans, monitor health, and more.

Compatibility

| CLI version | Server version | |-------------|---------------| | 0.1.x | 2.0.x+ |

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | General error | | 2 | Usage error (bad arguments) | | 3 | Not found | | 4 | Permission denied |

License

Apache-2.0