cisco-axl-cli

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.