cisco-axl-cli

name	cisco-axl-cli
description	Use when managing Cisco CUCM via the cisco-axl CLI — phones, lines, route patterns, partitions, calling search spaces, SIP profiles, and any AXL operation. Covers CRUD operations, SQL queries, operation discovery, bulk provisioning from CSV, and raw AXL execute commands.
license	MIT
metadata	{"author":"sieteunoseis","version":"1.0.0"}

Cisco AXL CLI

A CLI for Cisco Unified Communications Manager (CUCM) Administrative XML (AXL) operations.

Setup

The CLI must be available. Either:

# Option 1: Use npx (no install needed, works immediately)
npx cisco-axl --help

# Option 2: Install globally for faster repeated use
npm install -g cisco-axl

If using npx, prefix all commands with npx: npx cisco-axl list Phone ... If installed globally, use directly: cisco-axl list Phone ...

Configuration

Configure a CUCM cluster (interactive prompt for password — never pass credentials on the command line):

cisco-axl config add <name> --host <hostname> --username <user> --cucm-version <ver> --insecure
# You will be prompted securely for the password

Valid versions: 11.0, 11.5, 12.0, 12.5, 14.0, 15.0. Use --insecure for self-signed certificates (common in CUCM).

Or use environment variables (set via your shell profile, a .env file, or a secrets manager — never hardcode credentials):

# These should be set securely, e.g. via dotenv, vault, or shell profile
# CUCM_HOST, CUCM_USERNAME, CUCM_PASSWORD, CUCM_VERSION

Test the connection:

cisco-axl config test

Common Workflows

Get a single item

cisco-axl get Phone SEP001122334455
cisco-axl get Line 1001
cisco-axl get RoutePartition PT_INTERNAL
cisco-axl get Phone SEP001122334455 --returned-tags "name,model,description"

List items with search

cisco-axl list Phone --search "name=SEP%"
cisco-axl list Line --search "pattern=1%"
cisco-axl list Css --search "name=CSS_%"
cisco-axl list Phone --search "name=SEP%" --returned-tags "name,description" --format toon
cisco-axl list Phone --search "name=SEP%" --auto-page --max-results 5000

Add an item

cisco-axl add RoutePartition --data '{"name":"PT_INTERNAL","description":"Internal partition"}'

Update an item

cisco-axl update Phone SEP001122334455 --data '{"description":"Updated description"}'

Remove an item

cisco-axl remove RoutePartition PT_INTERNAL

SQL queries

cisco-axl sql query "SELECT name, description FROM device WHERE name LIKE 'SEP%'"
cisco-axl sql update "UPDATE device SET description='test' WHERE name='SEP001122334455'"

Discovering Operations

This is the CLI's most powerful feature. Discover and use ANY AXL operation dynamically — no static command definitions.

Step 1: Find operations

cisco-axl operations --filter phone
cisco-axl operations --filter ldap
cisco-axl operations --type action --filter phone    # apply, reset, restart, etc.
cisco-axl operations --type crud                     # add, get, list, update, remove

Step 2: See what tags an operation needs

cisco-axl describe getPhone
cisco-axl describe addLine --detailed    # shows required/optional/types

Step 3: Execute it

cisco-axl execute doLdapSync --tags '{"name":"LDAP_Main"}'
cisco-axl execute applyPhone --tags '{"name":"SEP001122334455"}'

Bulk Operations from CSV

For provisioning multiple items, use templates with CSV files. Requires optional packages: npm install json-variables csv-parse

Create a template (phone-template.json):

{
  "name": "SEP%%mac%%",
  "devicePoolName": "%%devicePool%%",
  "description": "%%description%%",
  "class": "Phone",
  "protocol": "SIP"
}

Create a CSV (phones.csv):

mac,devicePool,description
001122334455,DP_HQ,Lobby Phone
001122334466,DP_BRANCH,Conf Room A

Run bulk add:

cisco-axl add Phone --template phone-template.json --csv phones.csv
cisco-axl add Phone --template phone-template.json --csv phones.csv --dry-run   # preview first
cisco-axl add Phone --template phone-template.json --csv phones.csv --concurrency 10

Single template with inline vars:

cisco-axl add Phone --template phone-template.json --vars '{"mac":"001122334455","devicePool":"DP_HQ","description":"Lobby"}'

Bulk updates and execute too:

cisco-axl update Phone --template update-template.json --csv updates.csv
cisco-axl execute addLine --template line-template.json --csv lines.csv

Output Formats

Use --format to control output:

• --format table — human-readable tables (default)
• --format json — structured JSON for parsing
• --format toon — token-efficient format (recommended for AI agents, ~40% fewer tokens than JSON)
• --format csv — CSV for spreadsheet export

For AI agents: Use --format toon for list queries to reduce token usage. Use --format json when you need to parse nested structures.

Multiple Clusters

cisco-axl config add lab --host 10.0.0.1 --username admin --cucm-version 14.0 --insecure
cisco-axl config add prod --host 10.0.0.2 --username axladmin --cucm-version 15.0 --insecure
# You will be prompted securely for each password
cisco-axl config use prod
cisco-axl list Phone --search "name=SEP%" --cluster lab    # override per-command

Command Chaining

Shell && chains commands sequentially — each waits for the previous to complete, and the chain stops on the first failure:

# Create a partition, CSS, and line in order
cisco-axl add RoutePartition --data '{"name":"PT_INTERNAL","description":"Internal"}' && \
cisco-axl add Css --data '{"name":"CSS_INTERNAL","members":{"member":{"routePartitionName":"PT_INTERNAL","index":"1"}}}' && \
cisco-axl add Line --data '{"pattern":"1000","routePartitionName":"PT_INTERNAL"}'

Piping with --stdin

Use --stdin to pipe JSON between commands or from other tools:

# Get a phone's config, modify it with jq, update it
cisco-axl get Phone SEP001122334455 --format json | jq '.description = "Updated via pipe"' | cisco-axl update Phone SEP001122334455 --stdin

# Pipe JSON from a file
cat phone-config.json | cisco-axl add Phone --stdin

# Chain get → transform → execute
cisco-axl describe applyPhone --format json | jq '.name = "SEP001122334455"' | cisco-axl execute applyPhone --stdin

The --stdin flag is available on add, update, and execute commands. It is mutually exclusive with --data/--tags and --template.

Global Flags

• Item types are PascalCase matching AXL: Phone, Line, RoutePartition, Css, DevicePool, SipTrunk, TransPattern, RouteGroup, RouteList, etc.
• Use cisco-axl operations to discover exact type names.
• Use cisco-axl describe <operation> --detailed --format json to learn required vs optional tags.
• The --clean flag removes empty/null values from results.
• The --no-attributes flag removes XML attribute metadata.
• The --insecure flag is needed for most CUCM environments (self-signed certs).
• All operations are audit-logged to ~/.cisco-axl/audit.jsonl. Use --no-audit to skip.
• Use --dry-run with templates to preview resolved JSON before executing.