cisco-axl 2.0.0 → 2.1.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,26 @@
+{
+  "name": "cisco-axl",
+  "description": "Cisco CUCM AXL CLI skills for provisioning phones, lines, route patterns, partitions, CSS, and more via the Administrative XML API",
+  "version": "2.0.0",
+  "author": {
+    "name": "Jeremy Worden",
+    "url": "https://github.com/sieteunoseis"
+  },
+  "homepage": "https://github.com/sieteunoseis/cisco-axl#readme",
+  "repository": "https://github.com/sieteunoseis/cisco-axl",
+  "license": "MIT",
+  "keywords": [
+    "cisco",
+    "cucm",
+    "axl",
+    "unified-communications",
+    "voip",
+    "telephony",
+    "provisioning",
+    "soap",
+    "callmanager",
+    "cli",
+    "automation",
+    "bulk-provisioning"
+  ]
+}

package/.github/FUNDING.yml

@@ -0,0 +1 @@
+buy_me_a_coffee: automatebldrs

package/.github/workflows/ci.yml

@@ -12,7 +12,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [18, 20, 22]
+        node-version: [20, 22]
 
     steps:
       - uses: actions/checkout@v4

package/README.md

@@ -1,5 +1,12 @@
 # Cisco AXL Library & CLI
 
+[![npm version](https://img.shields.io/npm/v/cisco-axl.svg)](https://www.npmjs.com/package/cisco-axl)
+[![CI](https://github.com/sieteunoseis/cisco-axl/actions/workflows/ci.yml/badge.svg)](https://github.com/sieteunoseis/cisco-axl/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/node/v/cisco-axl.svg)](https://nodejs.org)
+[![Skills](https://img.shields.io/badge/skills.sh-cisco--axl--cli-blue)](https://skills.sh/sieteunoseis/cisco-axl)
+[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-support-orange?logo=buy-me-a-coffee)](https://buymeacoffee.com/automatebldrs)
+
 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:
@@ -26,7 +33,7 @@ npx cisco-axl --help
 ### AI Agent Skills
 
 ```bash
-npx skillsadd sieteunoseis/cisco-axl
+npx skills add sieteunoseis/cisco-axl
 ```
 
 ## Requirements
@@ -145,6 +152,38 @@ Template file (`phone-template.json`):
 --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:
+
+```bash
+# 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`:
+
+```bash
+# 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.

package/cli/commands/add.js

@@ -10,6 +10,7 @@
 const { createService } = require("../utils/connection.js");
 const { printResult, printError } = require("../utils/output.js");
 const { enforceReadOnly } = require("../utils/readonly.js");
+const { readStdin } = require("../utils/stdin.js");
 
 /**
  * Registers the add command on the given Commander program.
@@ -20,6 +21,7 @@ module.exports = function registerAddCommand(program) {
     .command("add <type>")
     .description("Add a new AXL item of the given type")
     .option("--data <json>", "JSON definition of the item to add")
+    .option("--stdin", "read JSON data from stdin (for piping)")
     .option("--template <file>", "JSON template file with %%var%% placeholders")
     .option("--vars <json>", "variables to resolve in template (JSON)")
     .option("--csv <file>", "CSV file for bulk operations (use with --template)")
@@ -34,12 +36,20 @@ module.exports = function registerAddCommand(program) {
       try {
         enforceReadOnly(globalOpts, "add");
 
+        // Read from stdin if --stdin flag is set
+        if (cmdOpts.stdin) {
+          const stdinData = await readStdin();
+          if (!stdinData) throw new Error("--stdin specified but no data piped. Pipe JSON via: echo '{...}' | cisco-axl add <type> --stdin");
+          cmdOpts.data = stdinData.trim();
+        }
+
         // Validate mutual exclusivity
-        if (cmdOpts.data && cmdOpts.template) {
-          throw new Error("--data and --template are mutually exclusive");
+        const inputCount = [cmdOpts.data, cmdOpts.template].filter(Boolean).length;
+        if (inputCount > 1) {
+          throw new Error("--data, --stdin, and --template are mutually exclusive");
         }
-        if (!cmdOpts.data && !cmdOpts.template) {
-          throw new Error("Either --data or --template must be provided");
+        if (inputCount === 0) {
+          throw new Error("Provide input via --data, --stdin, or --template");
         }
 
         const opts = {

package/cli/commands/config.js

@@ -14,38 +14,32 @@ const { createService } = require("../utils/connection.js");
  * @param {import("commander").Command} program
  */
 module.exports = function registerConfigCommand(program) {
-  const config = program.command("config").description("Manage CUCM cluster configuration");
+  const config = program
+    .command("config")
+    .description("Manage CUCM cluster configuration");
 
   // ── config add <name> ───────────────────────────────────────────────────────
 
   config
     .command("add <name>")
-    .description("Add a named CUCM cluster to config")
-    .requiredOption("--cucm-version <ver>", "CUCM version (e.g. 14.0)")
-    .action((name, opts) => {
+    .description("Add a named CUCM cluster to config (use --host, --username, --password, --version-cucm)")
+    .option("--cucm-version <ver>", "CUCM version (e.g. 14.0)")
+    .option("--insecure", "skip TLS verification for this cluster")
+    .action((name, opts, cmd) => {
       try {
-        // --host, --username, --password, --insecure come from global program options
-        const globalOpts = program.opts();
-
+        const globalOpts = cmd.optsWithGlobals();
         const host = globalOpts.host;
         const username = globalOpts.username;
         const password = globalOpts.password;
-        const insecure = globalOpts.insecure;
-
-        if (!host) {
-          throw new Error("Missing required option: --host");
-        }
-        if (!username) {
-          throw new Error("Missing required option: --username");
-        }
-        if (!password) {
-          throw new Error("Missing required option: --password");
-        }
-
-        // Commander camelCases --cucm-version to cucmVersion; addCluster expects version
-        const clusterOpts = { host, username, password, version: opts.cucmVersion };
-        if (insecure !== undefined) {
-          clusterOpts.insecure = insecure;
+        const version = opts.cucmVersion || globalOpts.versionCucm;
+        if (!host) throw new Error("Missing required option: --host");
+        if (!username) throw new Error("Missing required option: --username");
+        if (!password) throw new Error("Missing required option: --password");
+        if (!version) throw new Error("Missing required option: --cucm-version or --version-cucm");
+
+        const clusterOpts = { host, username, password, version };
+        if (opts.insecure || globalOpts.insecure) {
+          clusterOpts.insecure = true;
         }
 
         configUtil.addCluster(name, clusterOpts);

package/cli/commands/execute.js

@@ -10,6 +10,7 @@
 const { createService } = require("../utils/connection.js");
 const { printResult, printError } = require("../utils/output.js");
 const { enforceReadOnly } = require("../utils/readonly.js");
+const { readStdin } = require("../utils/stdin.js");
 
 /**
  * Registers the execute command on the given Commander program.
@@ -20,6 +21,7 @@ module.exports = function registerExecuteCommand(program) {
     .command("execute <operation>")
     .description("Execute a raw AXL operation with JSON tags")
     .option("--tags <json>", "JSON object of operation tags")
+    .option("--stdin", "read JSON tags from stdin (for piping)")
     .option("--template <file>", "JSON template file with %%var%% placeholders")
     .option("--vars <json>", "variables to resolve in template (JSON)")
     .option("--csv <file>", "CSV file for bulk operations (use with --template)")
@@ -34,12 +36,20 @@ module.exports = function registerExecuteCommand(program) {
       try {
         enforceReadOnly(globalOpts, "execute");
 
+        // Read from stdin if --stdin flag is set
+        if (cmdOpts.stdin) {
+          const stdinData = await readStdin();
+          if (!stdinData) throw new Error("--stdin specified but no data piped. Pipe JSON via: echo '{...}' | cisco-axl execute <op> --stdin");
+          cmdOpts.tags = stdinData.trim();
+        }
+
         // Validate mutual exclusivity
-        if (cmdOpts.tags && cmdOpts.template) {
-          throw new Error("--tags and --template are mutually exclusive");
+        const inputCount = [cmdOpts.tags, cmdOpts.template].filter(Boolean).length;
+        if (inputCount > 1) {
+          throw new Error("--tags, --stdin, and --template are mutually exclusive");
         }
-        if (!cmdOpts.tags && !cmdOpts.template) {
-          throw new Error("Either --tags or --template must be provided");
+        if (inputCount === 0) {
+          throw new Error("Provide input via --tags, --stdin, or --template");
         }
 
         const opts = {

package/cli/commands/update.js

@@ -10,6 +10,7 @@
 const { createService } = require("../utils/connection.js");
 const { printResult, printError } = require("../utils/output.js");
 const { enforceReadOnly } = require("../utils/readonly.js");
+const { readStdin } = require("../utils/stdin.js");
 
 /**
  * Registers the update command on the given Commander program.
@@ -20,6 +21,7 @@ module.exports = function registerUpdateCommand(program) {
     .command("update <type> [identifier]")
     .description("Update an existing AXL item by type and name or UUID")
     .option("--data <json>", "JSON object of fields to update")
+    .option("--stdin", "read JSON data from stdin (for piping)")
     .option("--template <file>", "JSON template file with %%var%% placeholders")
     .option("--vars <json>", "variables to resolve in template (JSON)")
     .option("--csv <file>", "CSV file for bulk operations (use with --template)")
@@ -34,12 +36,20 @@ module.exports = function registerUpdateCommand(program) {
       try {
         enforceReadOnly(globalOpts, "update");
 
+        // Read from stdin if --stdin flag is set
+        if (cmdOpts.stdin) {
+          const stdinData = await readStdin();
+          if (!stdinData) throw new Error("--stdin specified but no data piped. Pipe JSON via: echo '{...}' | cisco-axl update <type> <id> --stdin");
+          cmdOpts.data = stdinData.trim();
+        }
+
         // Validate mutual exclusivity
-        if (cmdOpts.data && cmdOpts.template) {
-          throw new Error("--data and --template are mutually exclusive");
+        const inputCount = [cmdOpts.data, cmdOpts.template].filter(Boolean).length;
+        if (inputCount > 1) {
+          throw new Error("--data, --stdin, and --template are mutually exclusive");
         }
-        if (!cmdOpts.data && !cmdOpts.template) {
-          throw new Error("Either --data or --template must be provided");
+        if (inputCount === 0) {
+          throw new Error("Provide input via --data, --stdin, or --template");
         }
 
         const opts = {

package/cli/index.js

@@ -1,14 +1,18 @@
 "use strict";
 
 const { Command } = require("commander");
-const { version } = require("../package.json");
+const pkg = require("../package.json");
+
+import("update-notifier").then(({ default: updateNotifier }) => {
+  updateNotifier({ pkg }).notify();
+}).catch(() => {});
 
 const program = new Command();
 
 program
   .name("cisco-axl")
   .description("CLI for Cisco CUCM AXL operations")
-  .version(version)
+  .version(pkg.version)
   .option("--format <type>", "output format: table, json, toon, csv", "table")
   .option("--host <host>", "CUCM hostname (overrides config/env)")
   .option("--username <user>", "CUCM username (overrides config/env)")

package/cli/utils/config.js

@@ -263,15 +263,30 @@ function resolveSsValue(id, field) {
 
       try {
         const data = JSON.parse(stdout);
-        // ss-cli returns an object; find the field case-insensitively
         const fieldLower = field.toLowerCase();
+
+        // First: check top-level keys (simple key-value secrets)
         const foundKey = Object.keys(data).find(
           (k) => k.toLowerCase() === fieldLower
         );
-        if (foundKey === undefined) {
-          return reject(new Error(`Field "${field}" not found in ss-cli response for secret ${id}`));
+        if (foundKey !== undefined) {
+          return resolve(data[foundKey]);
         }
-        resolve(data[foundKey]);
+
+        // Second: check items array (Secret Server template secrets)
+        // Items have fieldName, slug, and itemValue properties
+        if (Array.isArray(data.items)) {
+          const item = data.items.find(
+            (i) =>
+              (i.slug && i.slug.toLowerCase() === fieldLower) ||
+              (i.fieldName && i.fieldName.toLowerCase() === fieldLower)
+          );
+          if (item) {
+            return resolve(item.itemValue);
+          }
+        }
+
+        return reject(new Error(`Field "${field}" not found in secret ${id}`));
       } catch (parseErr) {
         reject(new Error(`Failed to parse ss-cli output for secret ${id}: ${parseErr.message}`));
       }

package/cli/utils/connection.js

@@ -119,9 +119,13 @@ async function resolveConfig(flags = {}) {
 async function createService(flags = {}) {
   const config = await resolveConfig(flags);
 
-  // Handle --insecure flag
+  // Handle --insecure flag — suppress Node's TLS warning since user opted in
   if (config.insecure || flags.insecure) {
     process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
+    process.emitWarning = ((orig) => function (warning, ...args) {
+      if (typeof warning === "string" && warning.includes("NODE_TLS_REJECT_UNAUTHORIZED")) return;
+      return orig.call(process, warning, ...args);
+    })(process.emitWarning);
   }
 
   // Build axlService options

package/cli/utils/stdin.js

@@ -0,0 +1,20 @@
+"use strict";
+
+/**
+ * Read all data from stdin as a string.
+ * Returns null if stdin is a TTY (no piped input).
+ */
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    if (process.stdin.isTTY) {
+      return resolve(null);
+    }
+    const chunks = [];
+    process.stdin.setEncoding("utf-8");
+    process.stdin.on("data", (chunk) => chunks.push(chunk));
+    process.stdin.on("end", () => resolve(chunks.join("")));
+    process.stdin.on("error", reject);
+  });
+}
+
+module.exports = { readStdin };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cisco-axl",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "A library and CLI for Cisco CUCM AXL operations",
   "main": "dist/index.js",
   "module": "main.mjs",
@@ -50,7 +50,8 @@
     "cli-table3": "^0.6.5",
     "commander": "^14.0.3",
     "csv-stringify": "^6.7.0",
-    "strong-soap": "^5.0.8"
+    "strong-soap": "^5.0.8",
+    "update-notifier": "^7.3.1"
   },
   "devDependencies": {
     "@types/node": "^22.19.15",

package/skills/cisco-axl-cli/SKILL.md

@@ -7,6 +7,21 @@ description: Use when managing Cisco CUCM via the cisco-axl CLI — phones, line
 
 A CLI for Cisco Unified Communications Manager (CUCM) Administrative XML (AXL) operations.
 
+## Prerequisites
+
+The CLI must be available. Either:
+
+```bash
+# 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 ...`
+
 ## Setup
 
 Configure a CUCM cluster:
@@ -167,6 +182,34 @@ 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:
+
+```bash
+# 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:
+
+```bash
+# 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`.
+
 ## Tips
 
 - Item types are PascalCase matching AXL: `Phone`, `Line`, `RoutePartition`, `Css`, `DevicePool`, `SipTrunk`, `TransPattern`, `RouteGroup`, `RouteList`, etc.