cisco-axl

Cisco AXL Library & CLI

A JavaScript library and CLI to interact with Cisco CUCM via AXL SOAP API. Dynamically discovers all AXL operations from the WSDL schema — any operation for your specified version is available without static definitions.

Administrative XML (AXL) information can be found at: Administrative XML (AXL) Reference.

Installation

npm install cisco-axl

Global CLI install

npm install -g cisco-axl

Or run without installing:

npx cisco-axl --help

AI Agent Skills

npx skills add sieteunoseis/cisco-axl

Requirements

If you are using self-signed certificates on Cisco VOS products you may need to disable TLS verification, or use the --insecure CLI flag.

Supported CUCM versions: 11.0, 11.5, 12.0, 12.5, 14.0, 15.0

CLI

The CLI provides full AXL access from the command line — CRUD operations, SQL queries, operation discovery, bulk provisioning from CSV, and a raw execute escape hatch for any AXL operation.

Quick Start

# Configure a cluster
cisco-axl config add lab --host 10.0.0.1 --username admin --password secret --cucm-version 14.0 --insecure

# Test the connection
cisco-axl config test

# List phones
cisco-axl list Phone --search "name=SEP%"

# Get a specific phone
cisco-axl get Phone SEP001122334455 --returned-tags "name,model,description"

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

# Discover available operations
cisco-axl operations --filter phone
cisco-axl operations --type action --filter phone

# Describe what tags an operation needs
cisco-axl describe getPhone --detailed

# Execute any AXL operation
cisco-axl execute doLdapSync --tags '{"name":"LDAP_Main"}'

Commands

Command	Description
config add/use/list/show/remove/test	Manage multi-cluster configurations
get <type> <identifier>	Get a single item
list <type>	List items with search, pagination, returned tags
add <type>	Add an item (inline JSON, template, or bulk CSV)
update <type> <identifier>	Update an item
remove <type> <identifier>	Remove an item
sql query/update	Execute SQL against CUCM
execute <operation>	Run any raw AXL operation
operations	List available operations with --filter and --type crud|action
describe <operation>	Show tag schema with --detailed for required/optional/type info

Configuration

# Multiple clusters
cisco-axl config add lab --host 10.0.0.1 --username admin --password secret --cucm-version 14.0 --insecure
cisco-axl config add prod --host 10.0.0.2 --username axladmin --password secret --cucm-version 15.0 --insecure
cisco-axl config use prod
cisco-axl config list

# Per-command cluster override
cisco-axl list Phone --search "name=SEP%" --cluster lab

# Environment variables (CI/CD, AI agents)
export CUCM_HOST=10.0.0.1 CUCM_USERNAME=admin CUCM_PASSWORD=secret CUCM_VERSION=14.0

Config stored at ~/.cisco-axl/config.json. Supports optional Secret Server integration via <ss:ID:field> placeholders.

Output Formats

cisco-axl list Phone --search "name=SEP%" --format table  # default, human-readable
cisco-axl list Phone --search "name=SEP%" --format json   # structured JSON
cisco-axl list Phone --search "name=SEP%" --format toon   # token-efficient for AI agents
cisco-axl list Phone --search "name=SEP%" --format csv    # spreadsheet export

Bulk Operations from CSV

Requires optional packages: npm install json-variables csv-parse

# Bulk add phones from template + CSV
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

# Single template with inline vars
cisco-axl add Phone --template phone-template.json --vars '{"mac":"001122334455","dp":"DP_HQ"}'

Template file (phone-template.json):

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

Global Flags

--format table|json|toon|csv   Output format (default: table)
--insecure                     Skip TLS certificate verification
--clean                        Remove empty/null values from results
--no-attributes                Remove XML attributes from results
--read-only                    Restrict to read-only operations
--no-audit                     Disable audit logging for this command
--debug                        Enable debug logging

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 like jq:

# 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

# Discover tags, fill them in, 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. It is mutually exclusive with --data/--tags and --template.

Audit Trail

All operations are logged to ~/.cisco-axl/audit.jsonl (JSONL format). Credentials are never logged. Use --no-audit to skip.

Library API

Setup

const axlService = require("cisco-axl");

let service = new axlService("10.10.20.1", "administrator", "ciscopsdt", "14.0");

// With options
let service = new axlService("10.10.20.1", "administrator", "ciscopsdt", "14.0", {
  logging: { level: "info" },
  retry: { retries: 3, retryDelay: 1000 }
});

Logging

// Via environment variable
// DEBUG=true

// Via constructor
let service = new axlService("10.10.20.1", "administrator", "ciscopsdt", "14.0", {
  logging: {
    level: "info",  // "error" | "warn" | "info" | "debug"
    handler: (level, message, data) => {
      myLogger[level](message, data);
    }
  }
});

// Change at runtime
service.setLogLevel("debug");

Convenience Methods

// Get a single item by name or UUID
await service.getItem("Phone", "SEP001122334455");
await service.getItem("Phone", { uuid: "abc-123" });

// List items with search criteria and returned tags
await service.listItems("RoutePartition");  // all partitions
await service.listItems("Phone", { name: "SEP%" }, { name: "", model: "" });

// Add, update, remove
await service.addItem("RoutePartition", { name: "NEW-PT", description: "New" });
await service.updateItem("Phone", "SEP001122334455", { description: "Updated" });
await service.removeItem("RoutePartition", "NEW-PT");

// SQL
const rows = await service.executeSqlQuery("SELECT name FROM routepartition");
await service.executeSqlUpdate("UPDATE routepartition SET description='test' WHERE name='NEW-PT'");

Operation Discovery

// List all operations
const ops = await service.returnOperations();
const phoneOps = await service.returnOperations("phone");

// Get tag schema
const tags = await service.getOperationTags("addRoutePartition");

// Get detailed metadata (required, nillable, type)
const detailed = await service.getOperationTagsDetailed("addRoutePartition");
console.log(detailed.routePartition.required);  // true
console.log(detailed.routePartition.children.name.type);  // "string"

Execute Any Operation

const tags = await service.getOperationTags("addRoutePartition");
tags.routePartition.name = "INTERNAL-PT";
tags.routePartition.description = "Internal directory numbers";

const result = await service.executeOperation("addRoutePartition", tags);
console.log("UUID:", result);

Batch Operations

const results = await service.executeBatch([
  { operation: "getPhone", tags: { name: "SEP001122334455" } },
  { operation: "getPhone", tags: { name: "SEP556677889900" } },
], 5); // concurrency limit

results.forEach((r) => {
  console.log(r.success ? `${r.operation}: OK` : `${r.operation}: ${r.error.message}`);
});

Error Handling

const { AXLAuthError, AXLNotFoundError, AXLOperationError, AXLValidationError } = require("cisco-axl");

try {
  await service.executeOperation("getPhone", { name: "INVALID" });
} catch (error) {
  if (error instanceof AXLAuthError) console.log("Bad credentials");
  else if (error instanceof AXLNotFoundError) console.log("Operation not found:", error.operation);
  else if (error instanceof AXLOperationError) console.log("SOAP fault:", error.message);
  else if (error instanceof AXLValidationError) console.log("Invalid input:", error.message);
}

Retry Configuration

let service = new axlService("10.10.20.1", "admin", "pass", "14.0", {
  retry: {
    retries: 3,
    retryDelay: 1000,
    retryOn: (error) => error.message.includes("ECONNRESET")
  }
});

ESM Support

// CommonJS
const axlService = require("cisco-axl");

// ESM
import axlService from "cisco-axl";
import { AXLAuthError, AXLOperationError } from "cisco-axl";

json-variables Support

var lineTemplate = {
  pattern: "%%_extension_%%",
  alertingName: "%%_firstName_%% %%_lastName_%%",
  description: "%%_firstName_%% %%_lastName_%%",
  _data: {
    extension: "1001",
    firstName: "Tom",
    lastName: "Smith",
  },
};

const lineTags = jVar(lineTemplate);
await service.executeOperation("updateLine", lineTags);

Methods Reference

Core

Method	Description
new axlService(host, user, pass, version, opts?)	Constructor
testAuthentication()	Test credentials against AXL endpoint
returnOperations(filter?)	List available operations
getOperationTags(operation)	Get tag schema for an operation
getOperationTagsDetailed(operation)	Get detailed tag metadata (required/nillable/type)
executeOperation(operation, tags, opts?)	Execute any AXL operation
executeBatch(operations[], concurrency?)	Parallel batch execution
setLogLevel(level)	Change log level at runtime

Convenience

Method	Description
getItem(type, identifier, opts?)	Get single item by name or UUID
listItems(type, search?, returnedTags?, opts?)	List items with filtering
addItem(type, data, opts?)	Add a new item
updateItem(type, identifier, updates, opts?)	Update an existing item
removeItem(type, identifier, opts?)	Remove an item
executeSqlQuery(sql)	Run a SQL SELECT query
executeSqlUpdate(sql)	Run a SQL INSERT/UPDATE/DELETE

Examples

Check the examples folder for different ways to use this library.

Run the integration tests against a CUCM cluster:

npm run staging

TypeScript Support

import axlService from 'cisco-axl';

const service = new axlService("10.10.20.1", "administrator", "ciscopsdt", "14.0");

const tags = await service.getOperationTags("listRoutePartition");
tags.searchCriteria.name = "%%";
const result = await service.executeOperation("listRoutePartition", tags);

See the examples/typescript directory for more examples.

Giving Back

If you would like to support my work and the time I put in creating the code, you can click the image below to get me a coffee. I would really appreciate it (but is not required).

Buy Me a Coffee