cisco-axl-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cisco AXL CLI

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

一个用于执行Cisco Unified Communications Manager (CUCM) 管理XML (AXL) 操作的CLI工具。

Setup

安装配置

The CLI must be available. Either:

bash

undefined

需先确保CLI可用，可选择以下任意一种方式：

bash

undefined

Option 1: Use npx (no install needed, works immediately)

选项1：使用npx（无需安装，可直接运行）

npx cisco-axl --help

Option 2: Install globally for faster repeated use

选项2：全局安装，便于重复快速使用

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 ...`

npm install -g cisco-axl


如果使用npx，所有命令前需添加`npx`前缀：`npx cisco-axl list Phone ...`
如果已全局安装，可直接使用：`cisco-axl list Phone ...`

Configuration

配置项

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

bash

cisco-axl config add <name> --host <hostname> --username <user> --cucm-version <ver> --insecure

配置CUCM集群（交互式输入密码，永远不要在命令行中传递凭据）：

bash

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):

```bash


支持的版本：11.0, 11.5, 12.0, 12.5, 14.0, 15.0。如果使用自签名证书（CUCM环境中十分常见）请添加`--insecure`参数。

也可使用环境变量（通过shell配置文件、`.env`文件或者密钥管理器设置，永远不要硬编码凭据）：

```bash

These should be set securely, e.g. via dotenv, vault, or shell profile

这些变量需要安全设置，例如通过dotenv、vault或者shell配置文件

CUCM_HOST, CUCM_USERNAME, CUCM_PASSWORD, CUCM_VERSION


Test the connection:

```bash
cisco-axl config test


测试连接：

```bash
cisco-axl config test

Common Workflows

常用工作流

Get a single item

获取单个条目

bash

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"

bash

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

带搜索条件列出条目

bash

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

bash

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

添加条目

bash

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

bash

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

Update an item

更新条目

bash

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

bash

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

Remove an item

删除条目

bash

cisco-axl remove RoutePartition PT_INTERNAL

bash

cisco-axl remove RoutePartition PT_INTERNAL

SQL queries

SQL查询

bash

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'"

bash

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.

这是本CLI最强大的功能，可动态发现并使用任意AXL操作，无需静态定义命令。

Step 1: Find operations

步骤1：查找操作

bash

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

bash

cisco-axl operations --filter phone
cisco-axl operations --filter ldap
cisco-axl operations --type action --filter phone    # apply、reset、restart等操作
cisco-axl operations --type crud                     # add、get、list、update、remove操作

Step 2: See what tags an operation needs

步骤2：查看操作需要的参数标签

bash

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

bash

cisco-axl describe getPhone
cisco-axl describe addLine --detailed    # 展示必填/可选参数及类型

Step 3: Execute it

步骤3：执行操作

bash

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

bash

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

Bulk Operations from CSV

从CSV执行批量操作

For provisioning multiple items, use templates with CSV files. Requires optional packages:

npm install json-variables csv-parse

如需部署多个条目，可结合CSV文件使用模板。需要先安装可选依赖包：

npm install json-variables csv-parse

Create a template (phone-template.json):

创建模板（phone-template.json）：

json

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

json

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

Create a CSV (phones.csv):

创建CSV文件（phones.csv）：

csv

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

csv

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

Run bulk add:

运行批量添加：

bash

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

bash

cisco-axl add Phone --template phone-template.json --csv phones.csv
cisco-axl add Phone --template phone-template.json --csv phones.csv --dry-run   # 先预览效果
cisco-axl add Phone --template phone-template.json --csv phones.csv --concurrency 10

Single template with inline vars:

单个模板搭配内联变量：

bash

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

bash

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

Bulk updates and execute too:

也支持批量更新和批量执行：

bash

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

bash

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.

使用

--format

参数控制输出格式：

```
--format table
```
— 人类易读的表格形式（默认）
```
--format json
```
— 结构化JSON，可用于解析
```
--format toon
```
— 低token格式（推荐AI Agent使用，比JSON少约40%的token）
```
--format csv
```
— CSV格式，可导出到电子表格

针对AI Agent： 列表查询时使用

--format toon

减少token消耗，需要解析嵌套结构时使用

--format json

。

Multiple Clusters

多集群管理

bash

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

bash

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

undefined

cisco-axl config use prod cisco-axl list Phone --search "name=SEP%" --cluster lab # 单条命令指定集群覆盖默认配置

undefined

Command Chaining

命令链式执行

Shell

&&

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

bash

undefined

Shell的

&&

可按顺序执行命令，每个命令等待上一个完成，遇到第一个错误就终止执行链：

bash

undefined

Create a partition, CSS, and line in order

按顺序创建分区、CSS和线路

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"}'

undefined

undefined

Piping with --stdin

结合--stdin使用管道

Use

--stdin

to pipe JSON between commands or from other tools:

bash

undefined

使用

--stdin

参数可在命令之间或者从其他工具传递JSON：

bash

undefined

Get a phone's config, modify it with jq, update it

获取话机配置，用jq修改后更新配置

cisco-axl get Phone SEP001122334455 --format json | jq '.description = "Updated via pipe"' | cisco-axl update Phone SEP001122334455 --stdin

Pipe JSON from a file

从文件读取JSON通过管道传递

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`.

cisco-axl describe applyPhone --format json | jq '.name = "SEP001122334455"' | cisco-axl execute applyPhone --stdin


`--stdin`参数可用于`add`、`update`和`execute`命令，它与`--data`/`--tags`以及`--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.

条目类型采用PascalCase命名，与AXL规范一致：
```
Phone
```
、
```
Line
```
、
```
RoutePartition
```
、
```
Css
```
、
```
DevicePool
```
、
```
SipTrunk
```
、
```
TransPattern
```
、
```
RouteGroup
```
、
```
RouteList
```
等。
使用
```
cisco-axl operations
```
可发现准确的类型名称。

使用

cisco-axl describe <operation> --detailed --format json

可了解必填和可选参数标签。

```
--clean
```
参数可移除结果中的空/Null值。
```
--no-attributes
```
参数可移除XML属性元数据。
大多数CUCM环境（自签名证书）需要添加
```
--insecure
```
参数。
所有操作都会记录审计日志到
```
~/.cisco-axl/audit.jsonl
```
，使用
```
--no-audit
```
可跳过日志记录。
搭配模板使用
```
--dry-run
```
可在执行前预览解析后的JSON。