cucm-cli

A command-line tool for querying and managing Cisco Unified Communications Manager (CUCM) clusters via AXL, Risport, and Serviceability APIs.

Install

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/cloverhound/cucm-cli/main/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/cloverhound/cucm-cli/main/install.ps1 | iex

From source

git clone https://github.com/cloverhound/cucm-cli.git
cd cucm-cli
go build -o cucm .

Releases for macOS, Linux, and Windows (amd64 and arm64) are published on the Releases page.

Quick Start

# Authenticate — auto-discovers version and cluster topology
cucm auth login --host 10.0.0.1 --username admin --cluster prod --default

# List phones
cucm phones list

# Execute SQL
cucm query sql --sql "SELECT name, description FROM device WHERE name LIKE 'SEP%'"

# Real-time device status
cucm device status SEP001122334455

# Use a different cluster for one command
cucm phones list --cluster lab

API Coverage

Resource Group	Commands
auth	login, set-credentials, status, logout, list, switch
cluster	list, status, discover
phones	list, get, add, update, remove
users	list, get, add, update, remove
lines (directory numbers)	list, get, add, update, remove
query	sql, update
device	status (Risport real-time)
services	list, start, stop, restart
trans (translation patterns)	list, get, add, update, remove
route-patterns	list, get, add, update, remove
sip-routes	list, get, add, update, remove
route-groups	list, get, add, update, remove
route-lists	list, get, add, update, remove
partitions	list, get, add, update, remove
css (calling search spaces)	list, get, add, update, remove
device-pools	list, get, add, update, remove
trunks (SIP trunks)	list, get, add, update, remove
gateways	list, get, add, update, remove

Authentication

cucm auth login runs the full connection sequence:

1. TCP connectivity check to host:8443
2. CUCM version detection via UDS (/cucm-uds/version)
3. AXL credential validation
4. Cluster topology discovery via AST API

Three credential types are supported per cluster:

Type	Used For
axl	AXL, Risport, UDS, Serviceability (default)
application	CDR, JTAPI, or other app-user APIs
platform	OS admin / platform-level access

# Login (AXL credentials, runs full discovery)
cucm auth login --host 10.0.0.1 --username admin --cluster prod --default

# Add additional credential types
cucm auth set-credentials --type application --username app-user --cluster prod
cucm auth set-credentials --type platform    --username os-admin  --cluster prod

# Show credential status
cucm auth status [--cluster prod]

# Output:
# cluster=prod (default)  host=10.0.0.1  version=15.0  clusterName=PROD_UCM
#   axl        : admin     [set]
#   application: app-user  [set]
#   platform   : os-admin  [set]

# Logout one type or all
cucm auth logout --cluster prod --type application
cucm auth logout --cluster prod --type all

Output Formats

Format	Flag	Notes
Table	--output table	Default — auto-width ASCII table
JSON	--output json	Pretty-printed; pipe to jq for filtering
CSV	--output csv	Pipe to file for spreadsheet import
Raw	--output raw	Raw API response

cucm phones list --output json | jq '.[].name'
cucm phones list --output csv > phones.csv

Global Flags

Flag	Description
--cluster <name>	Override the default cluster for this command
--output json|table|csv|raw	Output format (default: table)
--debug	Print raw SOAP XML request/response to stderr
--max <n>	Limit results to N items, 0 = no limit (default)
--dry-run	Print what would be sent without making any changes

Dry Run

Preview write operations without applying them:

cucm --dry-run phones add --name SEP112233445566 --product "Cisco 8861"
cucm --dry-run phones remove SEP001122334455
cucm --dry-run query update --sql "UPDATE device SET description='x' WHERE name='SEP001122334455'"

Configuration

Cluster configuration is stored in ~/.cucm-cli/config.json:

{
  "defaultCluster": "prod",
  "clusters": {
    "prod": {
      "host": "10.0.0.1",
      "version": "15.0",
      "clusterName": "PROD_UCM",
      "nodes": ["cucm-pub.example.com", "cucm-sub1.example.com"],
      "serviceNodes": {
        "db":      ["cucm-pub.example.com", "cucm-sub1.example.com"],
        "tftp":    ["cucm-pub.example.com"],
        "collmgr": ["cucm-pub.example.com", "cucm-sub1.example.com"]
      },
      "credentials": {
        "axl":         { "username": "axl-admin" },
        "application": { "username": "app-user" },
        "platform":    { "username": "os-admin" }
      }
    },
    "lab": {
      "host": "192.168.1.100",
      "version": "12.5",
      "clusterName": "LAB_UCM",
      "nodes": ["lab-cucm.lab.local"],
      "serviceNodes": {},
      "credentials": {
        "axl": { "username": "admin" }
      }
    }
  }
}

Passwords are stored separately in ~/.cucm-cli/.credentials (JSON, permissions 0600) — never in the config file.

Claude Code Integration

See skill/SKILL.md for the Claude Code skill definition.

Development

See CLAUDE.md for the full development guide including project layout, build instructions, SOAP notes, and key file reference.

# Build
go build -o cucm .

# Run integration tests (requires real CUCM — see tests/QUICK_START.md)
go test -v -tags integration ./tests/ -timeout 300s

CUCM Version Support

• 12.5 — Fully supported (AST fallback, UDS version detection)
• 14.x — Fully supported
• 15.x — Fully supported

License

MIT — see LICENSE