cucm-cli

name	cucm-cli
description	CUCM CLI: query and manage Cisco Unified Communications Manager clusters via AXL, Risport, Serviceability, AST, PAWS, and DIME APIs. Supports phones, users, directory numbers, dial-plan objects, routing, infrastructure, real-time device status, OS-level platform admin, live system health monitoring, and log file downloads across multiple named clusters.
argument-hint	[command or resource]
allowed-tools	Bash, Read, Grep, Glob
user-invocable	true

Setup

The cucm binary must be built and available in PATH:

go build -o cucm .
# or install from a release:
curl -fsSL https://raw.githubusercontent.com/cloverhound/cucm-cli/main/install.sh | bash

Authentication

# Login — runs auto-discovery (version, cluster topology)
cucm auth login --host 10.0.0.1 --username admin --cluster prod --default

# Add additional credential types to an existing cluster
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 for a cluster
cucm auth status [--cluster prod]

# Switch the default cluster
cucm auth switch prod

# List all configured clusters
cucm auth list

# Logout — removes credentials from secure storage
cucm auth logout [--cluster prod] [--type axl|application|platform|all]

Passwords are stored in the OS keystore (macOS Keychain, Windows Credential Manager, Linux Secret Service). The cluster config (hostnames, usernames, default cluster) is stored in ~/.cucm-cli/config.json — no passwords on disk. Three credential types are supported:

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

Command Discovery

Run cucm --help to list all available commands. Run cucm <command> --help or cucm <command> <subcommand> --help for exact flags — always use --help rather than guessing flag names.

Commands are grouped by resource type:

Group	Commands
Core endpoints	phones, users, lines
Dial plan	trans, route-patterns, sip-routes, called-party-transforms, calling-party-transforms, route-filters, aar-groups, time-periods, time-schedules, tod-access
Routing	route-groups, route-lists, partitions, css
Infrastructure	device-pools, trunks, gateways, locations, regions, physical-locations, srst, dhcp-servers, dhcp-subnets, date-time-groups, phone-ntp
Media resources	conf-bridges, transcoders, mtp, media-resource-groups, media-resource-lists, moh
Call features	hunt-groups, hunt-lists, hunt-pilots, call-park, directed-call-park, pickup-groups, meet-me, cti-route-points
Templates & profiles	phone-button-templates, softkey-templates, device-profiles, default-device-profiles, common-phone-config, common-device-config, phone-security-profiles, universal-device-templates, universal-line-templates
SIP	sip-profiles, sip-security-profiles, sip-realms, sip-dial-rules, sip-norm-scripts
H.323 / legacy	h323-gateways, h323-phones, h323-trunks, gatekeepers
LDAP	ldap (nested: directories, filters, auth, system, sync)
Mobility	remote-destinations, remote-dest-profiles, device-mobility, mobility-profiles
Voicemail	voicemail-pilots, voicemail-ports, voicemail-profiles, message-waiting, voh-servers
Users & access	app-users, user-groups, credential-policies, feature-control-policies
VPN & security	vpn (nested: gateways, groups, profiles)
Admin & services	uc-services, service-profiles, application-servers, recording-profiles, ip-phone-services, snmp, service-params
Presence & UC features	presence-groups, presence-redundancy, conference-now, feature-group-templates, mlpp, fac, cmc
Wireless	wifi-hotspots, wapc, wlan-profiles, wlan-profile-groups
IME / federation	ime (nested: clients, servers, firewalls, enrolled-patterns, exclusion-numbers, route-filter-elements)
CCD / SAF	ccd (nested: advertising-services, hosted-dns, requesting-services, saf-forwarders, lbm-groups)
Read-only / reporting	cluster version, process-node-services, enterprise-phone-config, route-plan, licensed-users, secure-config
Device actions	phones reset/restart/apply/lock/wipe/login/logout/dnd, lines apply/reset, device-pools apply/reset, trunks apply/reset, gateways apply/reset, route-lists apply/reset, users authenticate
Cluster & config	cluster, config, services, device status
SQL	query sql
AST (system health)	ast disk, ast calls, ast gateways, ast trunks, ast cti, ast tftp, ast sdl, ast ris, ast heartbeat, ast alerts, ast perfmon
PAWS (OS admin)	paws cluster status, paws cluster replication, paws drs status, paws drs backup
DIME (log files)	dime get-file

Global Flags

All commands support:

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 (server-side, 0 = no limit)
--dry-run	Print what would be sent without making any changes

Common Patterns

# Most resources follow list / get / add / update / remove
cucm phones list --name "SEP%"
cucm phones get SEP001122334455
cucm phones add --name SEP112233445566 --product "Cisco 8861" --description "Lab"
cucm phones update SEP001122334455 --description "Updated"
cucm phones remove SEP001122334455

# Pattern+partition resources (route patterns, translation patterns, meet-me, etc.)
cucm trans get "9." --partition PSTN_PT
cucm meet-me get 8000 --partition MM_PT

# Phone actions
cucm phones reset SEP001122334455
cucm phones restart SEP001122334455
cucm phones login SEP001122334455 --userid jsmith --pin 12345

# Output and filtering
cucm phones list --output json --max 50
cucm phones list --output csv > phones.csv
cucm phones list --output json | jq '.[] | select(.devicePoolName == "Site1_DP")'

# Dry run before writing
cucm --dry-run phones add --name SEP112233445566 --product "Cisco 8861"

# Debug SOAP
cucm --debug phones list --name "SEP%"

# Multi-cluster
cucm phones list --cluster lab
cucm auth switch prod

SQL Schema Discovery

The CUCM database uses Informix. Use system catalog tables to discover schema before writing queries. Always verify table and column names — never guess.

# List tables matching a keyword
cucm query sql --sql "SELECT tabname FROM systables WHERE tabname LIKE '%device%' AND tabtype='T'"

# List columns for a table
cucm query sql --sql "SELECT colname FROM syscolumns WHERE tabid=(SELECT tabid FROM systables WHERE tabname='device') ORDER BY colno"

Informix syntax notes: LIKE uses % wildcard; string literals use single quotes; limit rows with FIRST N (e.g. SELECT FIRST 10 name FROM device); no LIMIT clause.

Key Tables Reference

Table	Description	Key Columns
device	Phones, trunks, gateways, route lists, CTI route points	name, description, tkclass, tkmodel, fkdevicepool, fkcallingsearchspace, fkenduser, isactive
numplan	Directory numbers, route/translation patterns, hunt pilots	dnorpattern, fkroutepartition, tkpatternusage, description, cfbdestination, cfnadestination, calledpartytransformationmask
devicenumplanmap	Line-to-device associations	fkdevice, fknumplan, numplanindex, label, e164mask
enduser	End users	userid, firstname, lastname, mailid, department, title, telephonenumber, directoryuri
routepartition	Route partitions	name, description
callingsearchspace	Calling search spaces	name, description, clause
callingsearchspacemember	CSS → partition membership	fkcallingsearchspace, fkroutepartition, sortorder
devicepool	Device pools	name, fkregion, fkcallmanagergroup, fkdatetimesetting
routegroup	Route groups	name, description, tkdistributealgorithm
routelist	Route list → route group mappings	fkdevice, fkroutegroup, selectionorder
routegroupdevicemap	Route group member devices	fkroutegroup, fkdevice, deviceselectionorder
sipdevice	SIP trunk SIP-layer config	fkdevice, prefixdn, calleriddn, sigdigits
siptrunkdestination	SIP trunk destination addresses	fksipdevice, address, addressipv6, port, sortorder
numplanuri	SIP URI aliases for directory numbers	fknumplan, uri, fkroutepartition, isprimary
processnode	CUCM cluster nodes	name, description, isactive, nodeid
enduserdevicemap	User → controlled-device associations	fkenduser, fkdevice, tkuserassociation
endusernumplanmap	User → directory number associations	fkenduser, fknumplan, tkdnusage, sortorder

Type Code Lookups

device.tkclass — Device class:

Value	Class
1	Phone
2	Gateway
7	Route List
10	CTI Route Point
18	Trunk
20	Remote Destination Profile
254	Device Profile

numplan.tkpatternusage — Pattern usage:

Value	Usage
2	Device (directory number)
3	Translation Pattern
5	Route Pattern
7	Hunt Pilot
9	Domain Routing (SIP route pattern)
22	URI Routing

routegroup.tkdistributealgorithm — Distribution algorithm:

Value	Algorithm
1	Top Down
2	Circular
3	Longest Idle Time
4	Broadcast

Association Queries

Always use cucm query sql for cross-entity data. Built-in commands return a single entity's fields. For relationships between entities (lines on a phone, phones a user controls, partitions in a CSS), write a SQL JOIN.

device (tkclass=1)     ←—— devicenumplanmap ——→ numplan (tkpatternusage=2)
       ↑                                              ↑
enduserdevicemap              endusernumplanmap ———→ enduser

device (tkclass=7)     ←—— routelist ——→ routegroup ←—— routegroupdevicemap ——→ device (trunk/gw)
device (tkclass=18) ——→ sipdevice ——→ siptrunkdestination

callingsearchspace ←—— callingsearchspacemember ——→ routepartition

Phone → Lines

cucm query sql --sql "SELECT d.name AS phone, n.dnorpattern AS extension, p.name AS partition, m.numplanindex AS line_pos, m.label, m.e164mask FROM device d INNER JOIN devicenumplanmap m ON m.fkdevice=d.pkid INNER JOIN numplan n ON m.fknumplan=n.pkid LEFT JOIN routepartition p ON n.fkroutepartition=p.pkid WHERE d.tkclass=1 ORDER BY d.name, m.numplanindex"

# Lines on a specific phone
cucm query sql --sql "SELECT n.dnorpattern AS extension, p.name AS partition, m.numplanindex AS line_pos FROM device d INNER JOIN devicenumplanmap m ON m.fkdevice=d.pkid INNER JOIN numplan n ON m.fknumplan=n.pkid LEFT JOIN routepartition p ON n.fkroutepartition=p.pkid WHERE d.name='SEP001122334455' ORDER BY m.numplanindex"

Line → Phones

cucm query sql --sql "SELECT d.name AS phone, d.description, m.numplanindex AS line_pos FROM numplan n INNER JOIN devicenumplanmap m ON m.fknumplan=n.pkid INNER JOIN device d ON m.fkdevice=d.pkid WHERE n.dnorpattern='1001' ORDER BY d.name"

User → Phones (controlled devices)

cucm query sql --sql "SELECT u.userid, d.name AS phone, d.description FROM enduser u INNER JOIN enduserdevicemap edm ON edm.fkenduser=u.pkid INNER JOIN device d ON edm.fkdevice=d.pkid WHERE d.tkclass=1 ORDER BY u.userid"

# For a specific user
cucm query sql --sql "SELECT d.name AS phone, d.description FROM enduser u INNER JOIN enduserdevicemap edm ON edm.fkenduser=u.pkid INNER JOIN device d ON edm.fkdevice=d.pkid WHERE u.userid='jsmith'"

User → Lines

cucm query sql --sql "SELECT u.userid, n.dnorpattern AS extension, p.name AS partition FROM enduser u INNER JOIN endusernumplanmap em ON em.fkenduser=u.pkid INNER JOIN numplan n ON em.fknumplan=n.pkid LEFT JOIN routepartition p ON n.fkroutepartition=p.pkid WHERE u.userid='jsmith' ORDER BY em.sortorder"

Phone → Device Pool, CSS, Node

cucm query sql --sql "SELECT d.name AS phone, dp.name AS devicepool, css.name AS css, pn.name AS registered_node FROM device d LEFT JOIN devicepool dp ON d.fkdevicepool=dp.pkid LEFT JOIN callingsearchspace css ON d.fkcallingsearchspace=css.pkid LEFT JOIN processnode pn ON d.fkprocessnode=pn.pkid WHERE d.tkclass=1 ORDER BY d.name"

CSS → Partitions

cucm query sql --sql "SELECT css.name AS css, rp.name AS partition, cm.sortorder FROM callingsearchspace css INNER JOIN callingsearchspacemember cm ON cm.fkcallingsearchspace=css.pkid INNER JOIN routepartition rp ON cm.fkroutepartition=rp.pkid ORDER BY css.name, cm.sortorder"

Route List → Route Groups → Devices

cucm query sql --sql "SELECT rl_dev.name AS route_list, rg.name AS route_group, rl.selectionorder AS rg_order, d.name AS member_device, m.deviceselectionorder AS dev_order FROM device rl_dev INNER JOIN routelist rl ON rl.fkdevice=rl_dev.pkid INNER JOIN routegroup rg ON rl.fkroutegroup=rg.pkid INNER JOIN routegroupdevicemap m ON m.fkroutegroup=rg.pkid INNER JOIN device d ON m.fkdevice=d.pkid WHERE rl_dev.tkclass=7 ORDER BY rl_dev.name, rl.selectionorder, m.deviceselectionorder"

SIP Trunk → Destinations

cucm query sql --sql "SELECT d.name AS trunk, dst.address AS destination, dst.port FROM device d INNER JOIN sipdevice sd ON sd.fkdevice=d.pkid INNER JOIN siptrunkdestination dst ON dst.fksipdevice=sd.pkid WHERE d.tkclass=18 ORDER BY d.name, dst.sortorder"

AST — Application Server Task API (Unpublished)

AST (/ast/Astisapi.dll) is an undocumented, internal Cisco API that exposes real-time system health counters and perfmon data directly from the CallManager service. It uses AXL credentials (same as the default login) and is queried only on the publisher node.

Key facts: AST is not documented in Cisco DevNet. It is a REST/HTTP GET interface that returns plain XML — not SOAP. Responses are live-polled at the collecting rate (typically 30 seconds). All cucm ast commands target the publisher; there is no --node flag.

Command Reference

Command	What it shows
cucm ast disk	Disk partition usage — name, %used, total MB, used MB for each partition (Common, Boot, Swap, Active, Inactive, SharedMemory)
cucm ast calls	Call activity per CM node — attempted, completed, in-progress, partition failures
cucm ast gateways	Gateway port/channel activity per node — FXO, FXS, T1CAS, PRI, H323 with ports-in-service and calls-completed
cucm ast trunks	Trunk call activity per node — H323-Trunk and SIP-Trunk with calls-completed and calls-in-progress
cucm ast cti	CTI manager counters per node — open devices, open lines, active CM links, CTI connections
cucm ast tftp	TFTP server counters per node — total requests and aborted requests
cucm ast sdl	SDL signal queue depths per node — High, Normal, Low, Lowest queues with in-queue and processed signal counts
cucm ast ris	RIS (Real-time Information Server) collector status — primary/backup collector hostname, collecting rate, enabled flag, startup time, last collected time
cucm ast heartbeat	Heartbeat counters — CM and TFTP nodes with cumulative heartbeat rate
cucm ast alerts	RTMT-style alert summary — all 100+ alerts with triggered/enabled/safe-range status. Use --triggered to show only active alerts
cucm ast perfmon	Full perfmon object catalog — all perfmon objects per host with instance flag and counter count

Examples

# Disk usage across all partitions
cucm ast disk

# Live call counts
cucm ast calls --output json

# Show only triggered (active) RTMT alerts
cucm ast alerts --triggered

# Show all alerts including un-triggered (use jq to filter group)
cucm ast alerts --output json | jq '.[] | select(.group == "CallManager")'

# Trunk call activity
cucm ast trunks

# SDL queue depths (watch for growing NumOfSignalsInQueue in QueueHigh)
cucm ast sdl

# Full perfmon object catalog for capacity planning
cucm ast perfmon --output csv > perfmon_objects.csv

# Heartbeat rate — high values indicate healthy, active CM node
cucm ast heartbeat

# RIS collector info — confirms which node is primary data source
cucm ast ris

# CTI session counts — useful for JTAPI/TAPI capacity planning
cucm ast cti

# TFTP request counts — rises with phone registrations and config fetches
cucm ast tftp

AST Endpoint Map (for reference)

All requests hit https://{publisher}/ast/Astisapi.dll?{query}.

Query string	cucm ast command
GetPreCannedInfo&Items=getPartitionInfoRequest	disk
GetPreCannedInfo&Items=getCallActivityRequest	calls
GetPreCannedInfo&Items=getGatewayActivityRequest	gateways
GetPreCannedInfo&Items=getTrunkActivityRequest	trunks
GetPreCannedInfo&Items=getCtiManagerInfoRequest	cti
GetPreCannedInfo&Items=getTftpInfoRequest	tftp
GetPreCannedInfo&Items=getSdlqueueInfoRequest	sdl
GetPreCannedInfo&Items=getRisCollectorInfoRequest	ris
GetPreCannedInfo&Items=getHeartbeatInfoRequest	heartbeat
GetAlertSummaryList	alerts
PerfmonListObject	perfmon

Alert Columns

Column	Meaning
alertID	Internal alert name (may include service prefix like Cisco CallManager:CALLMANAGER:SDLLinkOOS)
displayName	Human-readable alert name shown in RTMT
group	Alert category: System, CallManager, etc.
triggered	true = alert is currently firing
enabled	true = alert monitoring is active
withinSafeRange	true = value is within configured threshold
timestamp	Epoch milliseconds when alert last fired (-1 = never fired)

---

PAWS — Platform Administrative Web Service

PAWS (/platform-services/services/) exposes OS-level administration for CUCM's Linux platform. It uses platform credentials (the OS admin account, typically admin) — separate from the AXL account. PAWS uses SOAP over HTTP with Axis2 WS-Addressing headers required on every request.

Set platform credentials before using PAWS:

cucm auth set-credentials --type platform --username admin --cluster <name>

Command Reference

Command	What it shows
cucm paws cluster status	OS-level cluster node info — hostname, IP address, status, DB role, node type for all nodes
cucm paws cluster replication	Whether cluster database replication is healthy (replicationOK: true/false)
cucm paws drs status	Current DRS (Disaster Recovery System) backup/restore operation status
cucm paws drs backup	Initiate a DRS backup to an SFTP server

Examples

# Show all cluster nodes with OS-level status and DB roles
cucm paws cluster status

cucm paws cluster status --output json
# Example output:
# [{"address":"10.0.0.10","dbRole":"cluster.node.type.primary",
#   "hostname":"cucm-pub.example.com","status":"cluster.node.status.online","type":"cluster.node.type.primary"}]

# Check replication health (important after DR events or subscriber failures)
cucm paws cluster replication

# Check if a DRS backup is running or what the last result was
cucm paws drs status

# Initiate a DRS backup to SFTP
cucm paws drs backup \
  --sftp-server 10.0.0.50 \
  --sftp-user backupuser \
  --sftp-password secret \
  --sftp-dir /backups/cucm

PAWS Cluster Status Fields

Field	Meaning
hostname	FQDN of the cluster node
address	IP address of the node
status	cluster.node.status.online = healthy; other values indicate issues
dbRole	cluster.node.type.primary = publisher; cluster.node.type.secondary = subscriber
type	Node type (mirrors dbRole)

PAWS Services and Namespaces (for reference)

Service	SOAP Endpoint	Operations
ClusterNodesService	/platform-services/services/ClusterNodesService	getClusterStatus, isClusterReplicationOK
DataExportService	/platform-services/services/DataExportService	dataExport (takes args0=sftpHost, args1=port, args2=user, args3=pass, args4=dir)
DataExportStatusService	/platform-services/services/DataExportStatusService	dataExportStatus

PAWS uses WS-Addressing (WSA) with urn:<operationName> action format and namespace http://services.api.platform.vos.cisco.com.

---

DIME — Log File Downloads

DIME (/logcollectionservice/services/DimeGetFileService) downloads files directly from a CUCM node's filesystem. Despite the name (Direct Internet Message Encapsulation), CUCM 12.x+ returns MIME multipart/related (SOAP with Attachments). It uses AXL credentials (the default type — no extra setup required).

Key facts

• Publisher only by default; use --node <IP> to target a subscriber
• Files are always on the CUCM node (Linux filesystem), not the CUCM database
• If the path doesn't start with /var/log, /var/log/active/ is prepended automatically
• Writes to stdout by default (redirect with >); use --output <file> to save directly

Command Reference

Command	What it does
cucm dime get-file <path>	Download a log file from a CUCM node and write it to stdout or --output <file>

Flags for get-file:

Flag	Default	Description
--node <IP>	publisher	Target a specific cluster node (subscriber)
--output <file>	stdout	Write file bytes to a local path instead of stdout

Examples

# Download the main CUCM syslog (auto-detects /var/log/active/ prefix)
cucm dime get-file /var/log/active/syslog/CiscoSyslog > CiscoSyslog.txt

# Short path — /var/log/active/ is prepended automatically
cucm dime get-file syslog/CiscoSyslog --output /tmp/syslog.txt

# Download a Call Manager SDI trace file
cucm dime get-file /var/log/active/cm/trace/callmanager/sdi/ccm08001.txt --output ccm08001.txt

# Download from a subscriber node
cucm dime get-file /var/log/active/syslog/CiscoSyslog --node 10.0.0.11 --output sub1_syslog.txt

# Grep live syslog without saving
cucm dime get-file syslog/CiscoSyslog | grep ERROR

Common Log File Paths

Path	Description
/var/log/active/syslog/CiscoSyslog	Main platform syslog — all services
/var/log/active/cm/trace/callmanager/sdi/ccm*.txt	Call Manager SDI traces
/var/log/active/cm/trace/cisco/unified communications manager/	Detailed CCM traces
/var/log/active/cm/trace/dsp/	DSP traces
/var/log/active/install/install.log	Installation log

DIME Endpoint Reference

Detail	Value
URL	https://{host}:8443/logcollectionservice/services/DimeGetFileService
Operation	GetOneFile(FileName)
SOAPAction	http://schemas.cisco.com/ast/soap/action/#LogCollectionPort#GetOneFile
SOAP style	RPC-encoded (body namespace http://schemas.cisco.com/ast/soap/)
Response format	multipart/related (CUCM 12.x+)

---

When Answering Questions

• Always run cucm <command> --help to verify exact flag names before constructing commands
• Never say "the CLI doesn't expose this" — the CUCM database is fully accessible via cucm query sql; any relationship between objects can be queried using the association tables above
• For associated/related data, always use cucm query sql with JOINs — never the built-in CRUD commands
• Before writing a SQL query, verify table and column names using schema discovery; never guess
• Use --output json and pipe to jq for field extraction or filtering
• Use --dry-run to preview write operations before executing
• When the cluster is unclear, run cucm auth list to show configured clusters

Choosing the Right API for Real-Time Data

Question	Best command
Is a phone currently registered? What is its IP?	cucm device status <name> (Risport)
How many calls are active right now?	cucm ast calls (AST)
Is disk space running low?	cucm ast disk (AST)
Are there active RTMT alerts?	cucm ast alerts --triggered (AST)
What CUCM services are running on a node?	cucm services list [--node <host>] (Serviceability)
Are all cluster nodes online (OS-level)?	cucm paws cluster status (PAWS — needs platform creds)
Is DB replication healthy?	cucm paws cluster replication (PAWS — needs platform creds)
What perfmon counters exist for a service?	`cucm ast perfmon --output json
What gateway types are active?	cucm ast gateways (AST)
How many CTI/JTAPI sessions are open?	cucm ast cti (AST)
Need a raw log file from the CUCM filesystem?	cucm dime get-file <path> (DIME)