cisco-axl 2.0.0 → 2.1.2

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/.github/workflows/release.yml

@@ -3,11 +3,11 @@ name: Release
 on:
   push:
     tags:
-      - 'v*'
+      - "v*"
 
 permissions:
-  id-token: write    # Required for OIDC authentication
-  contents: write    # Required for creating GitHub Release
+  id-token: write # Required for OIDC authentication
+  contents: write # Required for creating GitHub Release
 
 jobs:
   publish:
@@ -19,8 +19,8 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '22'
-          registry-url: 'https://registry.npmjs.org'
+          node-version: "22"
+          registry-url: "https://registry.npmjs.org"
 
       - name: Update npm
         run: npm install -g npm@latest
@@ -41,7 +41,7 @@ jobs:
         run: node -e "const axlService = require('./dist/index.js'); console.log('CJS require OK');"
 
       - name: Publish to npm
-        run: npm publish --access public
+        run: npm publish --access public --provenance
 
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v2

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
@@ -35,11 +42,7 @@ If you are using self-signed certificates on Cisco VOS products you may need to
 
 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
+## Quick Start
 
 ```bash
 # Configure a cluster
@@ -52,27 +55,31 @@ cisco-axl config test
 cisco-axl list Phone --search "name=SEP%"
 
 # Get a specific phone
-cisco-axl get Phone SEP001122334455 --returned-tags "name,model,description"
+cisco-axl get Phone SEP001122334455
 
 # 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
+## Configuration
 
-# Execute any AXL operation
-cisco-axl execute doLdapSync --tags '{"name":"LDAP_Main"}'
+```bash
+cisco-axl config add <name> --host <host> --username <user> --password <pass> --cucm-version <ver> --insecure
+cisco-axl config use <name>       # switch active cluster
+cisco-axl config list             # list all clusters
+cisco-axl config show             # show active cluster (masks passwords)
+cisco-axl config remove <name>    # remove a cluster
+cisco-axl config test             # test connectivity
 ```
 
-### Commands
+Auth precedence: CLI flags > env vars (`CUCM_HOST`, `CUCM_USERNAME`, `CUCM_PASSWORD`, `CUCM_VERSION`) > config file.
+
+Config stored at `~/.cisco-axl/config.json`. Supports [ss-cli](https://github.com/sieteunoseis/ss-cli) `<ss:ID:field>` placeholders.
+
+## CLI 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) |
@@ -80,281 +87,52 @@ cisco-axl execute doLdapSync --tags '{"name":"LDAP_Main"}'
 | `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
-
-```bash
-# 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
+| `operations` | List available operations |
+| `describe <operation>` | Show tag schema for an operation |
+| `doctor` | Check AXL connectivity and health |
 
-# Per-command cluster override
-cisco-axl list Phone --search "name=SEP%" --cluster lab
+See [full CLI reference](docs/cli.md) for bulk CSV, command chaining, piping with `--stdin`, and operation discovery.
 
-# 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](https://github.com/sieteunoseis/ss-cli) integration via `<ss:ID:field>` placeholders.
-
-### Output Formats
-
-```bash
-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
-```
+## Global Flags
 
-### Bulk Operations from CSV
-
-Requires optional packages: `npm install json-variables csv-parse`
-
-```bash
-# 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`):
-```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
-```
-
-### Audit Trail
-
-All operations are logged to `~/.cisco-axl/audit.jsonl` (JSONL format). Credentials are never logged. Use `--no-audit` to skip.
+| Flag | Description |
+|------|-------------|
+| `--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 |
 
 ## Library API
 
-### Setup
-
 ```javascript
 const axlService = require("cisco-axl");
+const service = new axlService("10.10.20.1", "administrator", "ciscopsdt", "14.0");
 
-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
-
-```javascript
-// 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
-
-```javascript
-// Get a single item by name or UUID
+// Get, list, add, update, remove
 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.listItems("Phone", { name: "SEP%" });
 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
-
-```javascript
-// 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
+await service.executeSqlQuery("SELECT name FROM routepartition");
 
-```javascript
+// Any AXL 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
-
-```javascript
-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}`);
-});
+await service.executeOperation("addRoutePartition", tags);
 ```
 
-### Error Handling
+See [full API documentation](docs/api.md) for all methods, error handling, batch operations, TypeScript, retry config, and logging.
 
-```javascript
-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
-
-```javascript
-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
-
-```javascript
-// CommonJS
-const axlService = require("cisco-axl");
-
-// ESM
-import axlService from "cisco-axl";
-import { AXLAuthError, AXLOperationError } from "cisco-axl";
-```
-
-### json-variables Support
-
-```javascript
-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:
-
-```bash
-npm run staging
-```
-
-## TypeScript Support
-
-```typescript
-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);
-```
+## Giving Back
 
-See the `examples/typescript` directory for more examples.
+If you found this helpful, consider:
 
-## Giving Back
+[!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://buymeacoffee.com/automatebldrs)
 
-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).
+## License
 
-[Buy Me a Coffee](https://www.buymeacoffee.com/automatebldrs)
+MIT

package/claude-hooks.json

@@ -0,0 +1,30 @@
+{
+  "name": "cisco-axl",
+  "description": "Hooks for Cisco CUCM AXL CLI",
+  "author": "sieteunoseis",
+  "version": "1.0.0",
+  "hooks": [
+    {
+      "name": "Block write operations",
+      "description": "Blocks add, update, remove, execute, and sql update commands",
+      "default": true,
+      "event": "PreToolUse",
+      "matcher": "Bash",
+      "hook": {
+        "type": "command",
+        "command": "jq -r '.tool_input.command' | { read -r cmd; if echo \"$cmd\" | grep -qE '^(npx )?cisco-axl (add|update|remove|execute|sql update)'; then echo '{\"decision\":\"block\",\"reason\":\"BLOCKED: cisco-axl write operation. Use --read-only or get explicit user approval.\"}'; fi; }"
+      }
+    },
+    {
+      "name": "Enforce --read-only flag",
+      "description": "Requires --read-only on every cisco-axl command",
+      "default": false,
+      "event": "PreToolUse",
+      "matcher": "Bash",
+      "hook": {
+        "type": "command",
+        "command": "jq -r '.tool_input.command' | { read -r cmd; if echo \"$cmd\" | grep -qE '^(npx )?cisco-axl ' && ! echo \"$cmd\" | grep -q '\\-\\-read-only'; then echo '{\"decision\":\"block\",\"reason\":\"BLOCKED: cisco-axl must be run with --read-only. Retry with the flag.\"}'; fi; }"
+      }
+    }
+  ]
+}

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)")
@@ -32,14 +34,22 @@ module.exports = function registerAddCommand(program) {
       let errorMsg;
 
       try {
-        enforceReadOnly(globalOpts, "add");
+        await 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);