cisco-axl 2.1.0 → 2.1.2

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

@@ -42,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
@@ -59,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) |
@@ -87,313 +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
-
-# 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](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
-```
-
-### 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
-```
-
-### 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
-```
+| `operations` | List available operations |
+| `describe <operation>` | Show tag schema for an operation |
+| `doctor` | Check AXL connectivity and health |
 
-The `--stdin` flag is available on `add`, `update`, and `execute`. It is mutually exclusive with `--data`/`--tags` and `--template`.
+See [full CLI reference](docs/cli.md) for bulk CSV, command chaining, piping with `--stdin`, and operation discovery.
 
-### Audit Trail
+## Global Flags
 
-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
+await service.executeSqlQuery("SELECT name FROM routepartition");
 
-```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
-
-```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}`);
-});
-```
-
-### Error Handling
-
-```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
+await service.executeOperation("addRoutePartition", tags);
 ```
 
-## TypeScript Support
+See [full API documentation](docs/api.md) for all methods, error handling, batch operations, TypeScript, retry config, and logging.
 
-```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

@@ -34,7 +34,7 @@ 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) {

package/cli/commands/doctor.js

@@ -0,0 +1,134 @@
+"use strict";
+
+const { loadConfig, getConfigPath, getConfigDir } = require("../utils/config.js");
+const { resolveConfig } = require("../utils/connection.js");
+
+module.exports = function (program) {
+  program.command("doctor")
+    .description("Check AXL connectivity and configuration health")
+    .action(async (opts, command) => {
+      const globalOpts = command.optsWithGlobals();
+      let passed = 0;
+      let warned = 0;
+      let failed = 0;
+
+      const ok = (msg) => { console.log(`  ✓ ${msg}`); passed++; };
+      const warn = (msg) => { console.log(`  ⚠ ${msg}`); warned++; };
+      const fail = (msg) => { console.log(`  ✗ ${msg}`); failed++; };
+
+      console.log("\n  cisco-axl doctor");
+      console.log("  " + "─".repeat(50));
+
+      // 1. Configuration
+      console.log("\n  Configuration");
+      let conn;
+      try {
+        const data = loadConfig();
+        if (!data.activeCluster) {
+          fail("No active cluster configured");
+          console.log("    Run: cisco-axl config add <name> --host <host> --username <user> --password <pass> --cucm-version <ver>");
+          printSummary(passed, warned, failed);
+          return;
+        }
+        ok(`Active cluster: ${data.activeCluster}`);
+        const cluster = data.clusters[data.activeCluster];
+        ok(`Host: ${cluster.host}`);
+        ok(`Username: ${cluster.username}`);
+        ok(`CUCM version: ${cluster.version}`);
+
+        if (cluster.insecure) warn("TLS verification: disabled (--insecure)");
+        else ok("TLS verification: enabled");
+
+        conn = await resolveConfig(globalOpts);
+      } catch (err) {
+        fail(`Config error: ${err.message}`);
+        printSummary(passed, warned, failed);
+        return;
+      }
+
+      // 2. AXL API connectivity
+      console.log("\n  AXL API");
+      try {
+        if (conn.insecure) { process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0"; }
+        const axlService = require("../../dist/index.js");
+        const service = new axlService(conn.host, conn.username, conn.password, conn.version);
+
+        await service.testAuthentication();
+        ok(`AXL API: connected`);
+
+        // Try a simple SQL query to verify read access
+        try {
+          const sqlResult = await service.executeSqlQuery("SELECT COUNT(*) AS cnt FROM device");
+          const rows = Array.isArray(sqlResult) ? sqlResult : sqlResult?.row || [];
+          const count = rows[0]?.cnt || "?";
+          ok(`SQL query: ${count} device(s) in database`);
+        } catch {
+          warn("SQL query: could not query device table — may lack permissions");
+        }
+
+        // Check operation count
+        try {
+          const ops = await service.returnOperations();
+          const count = Array.isArray(ops) ? ops.length : 0;
+          ok(`AXL operations: ${count} available`);
+        } catch {
+          warn("Could not list AXL operations");
+        }
+      } catch (err) {
+        const msg = err.message || String(err);
+        if (msg.includes("401") || msg.includes("Authentication") || msg.includes("Unauthorized")) {
+          fail("AXL API: authentication failed — check username/password");
+        } else if (msg.includes("ECONNREFUSED")) {
+          fail("AXL API: connection refused — check host and port");
+        } else if (msg.includes("ENOTFOUND")) {
+          fail("AXL API: hostname not found — check host");
+        } else if (msg.includes("certificate")) {
+          fail("AXL API: TLS certificate error — try adding --insecure to the cluster config");
+        } else {
+          fail(`AXL API: ${msg}`);
+        }
+      }
+
+      // 3. Security
+      console.log("\n  Security");
+      try {
+        const fs = require("node:fs");
+        const configPath = getConfigPath();
+        const stats = fs.statSync(configPath);
+        const mode = (stats.mode & 0o777).toString(8);
+        if (mode === "600") ok(`Config file permissions: ${mode} (secure)`);
+        else warn(`Config file permissions: ${mode} — should be 600. Run: chmod 600 ${configPath}`);
+      } catch { /* config file may not exist yet */ }
+
+      // 4. Audit trail
+      try {
+        const fs = require("node:fs");
+        const path = require("node:path");
+        const auditPath = path.join(getConfigDir(), "audit.jsonl");
+        if (fs.existsSync(auditPath)) {
+          const stats = fs.statSync(auditPath);
+          const sizeMB = (stats.size / 1024 / 1024).toFixed(1);
+          ok(`Audit trail: ${sizeMB}MB`);
+          if (stats.size > 8 * 1024 * 1024) warn("Audit trail approaching 10MB rotation limit");
+        } else {
+          ok("Audit trail: empty (no operations logged yet)");
+        }
+      } catch { /* ignore */ }
+
+      printSummary(passed, warned, failed);
+    });
+
+  function printSummary(passed, warned, failed) {
+    console.log("\n  " + "─".repeat(50));
+    console.log(`  Results: ${passed} passed, ${warned} warning${warned !== 1 ? "s" : ""}, ${failed} failed`);
+    if (failed > 0) {
+      process.exitCode = 1;
+      console.log("  Status:  issues found — review failures above");
+    } else if (warned > 0) {
+      console.log("  Status:  healthy with warnings");
+    } else {
+      console.log("  Status:  all systems healthy");
+    }
+    console.log("");
+  }
+};

package/cli/commands/execute.js

@@ -34,7 +34,7 @@ module.exports = function registerExecuteCommand(program) {
       let errorMsg;
 
       try {
-        enforceReadOnly(globalOpts, "execute");
+        await enforceReadOnly(globalOpts, "execute");
 
         // Read from stdin if --stdin flag is set
         if (cmdOpts.stdin) {

package/cli/commands/remove.js

@@ -24,7 +24,7 @@ module.exports = function registerRemoveCommand(program) {
       let errorMsg;
 
       try {
-        enforceReadOnly(globalOpts, "remove");
+        await enforceReadOnly(globalOpts, "remove");
 
         const service = await createService(globalOpts);
         const opts = {

package/cli/commands/sql.js

@@ -75,7 +75,7 @@ module.exports = function registerSqlCommand(program) {
       let errorMsg;
 
       try {
-        enforceReadOnly(globalOpts, "sql update");
+        await enforceReadOnly(globalOpts, "sql update");
 
         const service = await createService(globalOpts);
         const opts = {

package/cli/commands/update.js

@@ -34,7 +34,7 @@ module.exports = function registerUpdateCommand(program) {
       let errorMsg;
 
       try {
-        enforceReadOnly(globalOpts, "update");
+        await enforceReadOnly(globalOpts, "update");
 
         // Read from stdin if --stdin flag is set
         if (cmdOpts.stdin) {

package/cli/index.js

@@ -3,9 +3,17 @@
 const { Command } = require("commander");
 const pkg = require("../package.json");
 
-import("update-notifier").then(({ default: updateNotifier }) => {
+// Suppress Node.js TLS warning when --insecure is used
+const originalEmitWarning = process.emitWarning;
+process.emitWarning = (warning, ...args) => {
+  if (typeof warning === "string" && warning.includes("NODE_TLS_REJECT_UNAUTHORIZED")) return;
+  originalEmitWarning.call(process, warning, ...args);
+};
+
+try {
+  const updateNotifier = require("update-notifier").default || require("update-notifier");
   updateNotifier({ pkg }).notify();
-}).catch(() => {});
+} catch {};
 
 const program = new Command();
 
@@ -37,6 +45,7 @@ require("./commands/sql.js")(program);
 require("./commands/execute.js")(program);
 require("./commands/operations.js")(program);
 require("./commands/describe.js")(program);
+require("./commands/doctor.js")(program);
 // require("./commands/phone.js")(program);
 // require("./commands/line.js")(program);
 // require("./commands/user.js")(program);

package/cli/utils/confirm.js

@@ -0,0 +1,34 @@
+const readline = require("readline");
+const { getRandomWord } = require("./wordlist.js");
+
+function checkWriteAllowed(clusterConfig, globalOpts = {}) {
+  const readOnly = clusterConfig?.readOnly || globalOpts.readOnly;
+  if (!readOnly) return Promise.resolve(true);
+
+  if (!process.stdin.isTTY) {
+    throw new Error(
+      "This cluster is configured as read-only. " +
+      "Interactive TTY required for write confirmation. " +
+      "Change config with: cisco-axl config update <name> --no-read-only"
+    );
+  }
+
+  const word = getRandomWord();
+  const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+
+  return new Promise((resolve, reject) => {
+    rl.question(
+      `\n⚠ This cluster is configured as read-only.\nTo proceed, type "${word}" to confirm: `,
+      (answer) => {
+        rl.close();
+        if (answer.trim().toLowerCase() === word.toLowerCase()) {
+          resolve({ confirmed: true, word });
+        } else {
+          reject(new Error("Confirmation failed. Write operation cancelled."));
+        }
+      }
+    );
+  });
+}
+
+module.exports = { checkWriteAllowed };

package/cli/utils/readonly.js

@@ -1,31 +1,26 @@
 "use strict";
 
+const { checkWriteAllowed } = require("./confirm.js");
+
 /**
  * Check if read-only mode is active (via --read-only flag or cluster config).
- * Throws an error if a write operation is attempted in read-only mode.
+ * If read-only, requires interactive TTY confirmation with a random word.
+ * Non-interactive sessions (AI agents without TTY) fail automatically.
  *
  * @param {object} globalOpts - Commander global options
  * @param {string} operation - The operation being attempted (for error message)
  */
-function enforceReadOnly(globalOpts, operation) {
-  if (globalOpts.readOnly) {
-    throw new Error(
-      `Operation "${operation}" blocked — read-only mode is active.\n` +
-      "Read-only mode only allows: get, list, describe, operations, sql query.\n" +
-      "Remove --read-only flag to perform write operations."
-    );
-  }
-
-  // Also check cluster config for readOnly setting
+async function enforceReadOnly(globalOpts, operation) {
   const { getActiveCluster } = require("./config.js");
   const cluster = getActiveCluster(globalOpts.cluster);
-  if (cluster && cluster.readOnly) {
-    throw new Error(
-      `Operation "${operation}" blocked — cluster "${cluster.name}" is configured as read-only.\n` +
-      "Update the cluster config to allow write operations:\n" +
-      `  cisco-axl config add ${cluster.name} ... (without read-only)`
-    );
-  }
+  const clusterConfig = cluster || {};
+
+  // Build a combined config for checkWriteAllowed
+  const config = {
+    readOnly: globalOpts.readOnly || clusterConfig.readOnly || false,
+  };
+
+  await checkWriteAllowed(config, globalOpts);
 }
 
 module.exports = { enforceReadOnly };

package/cli/utils/wordlist.js

@@ -0,0 +1,9 @@
+const crypto = require("crypto");
+
+function getRandomWord() {
+  // Generate a random 8-char string that doesn't exist in the codebase
+  // Not guessable, not brute-forceable from a known word list
+  return crypto.randomBytes(4).toString("hex");
+}
+
+module.exports = { getRandomWord };

package/docs/api.md

@@ -0,0 +1,191 @@
+# Library API Reference
+
+## Setup
+
+```javascript
+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 }
+});
+```
+
+## ESM / TypeScript
+
+```javascript
+// CommonJS
+const axlService = require("cisco-axl");
+
+// ESM
+import axlService from "cisco-axl";
+import { AXLAuthError, AXLOperationError } from "cisco-axl";
+```
+
+```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);
+```
+
+See the `examples/typescript` directory for more examples.
+
+## 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
+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
+
+```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
+
+```javascript
+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}`);
+});
+```
+
+## Error Handling
+
+```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")
+  }
+});
+```
+
+## 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 |

package/docs/claude-code-hooks.md

@@ -0,0 +1,85 @@
+# Claude Code Hooks for cisco-axl
+
+[Claude Code hooks](https://docs.anthropic.com/en/docs/claude-code/hooks) let you enforce guardrails when AI agents use the CLI. The examples below block write operations so Claude can only read from CUCM.
+
+## Quick Install
+
+Install the write-safety hook with one command using [cc-hooks-install](https://github.com/sieteunoseis/cc-hooks-install):
+
+```bash
+npx cc-hooks-install add sieteunoseis/cisco-axl
+```
+
+This fetches the hook definitions from this repo, shows an interactive prompt to select which hooks to install, and merges them into your `~/.claude/settings.json`.
+
+If you prefer to install manually, see below.
+
+## Block Write Operations
+
+Add this to your `~/.claude/settings.json` (global) or `.claude/settings.json` (project-level) under `hooks.PreToolUse`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "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; }"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### What it blocks
+
+| Command                                        | Blocked | Why                 |
+| ---------------------------------------------- | ------- | ------------------- |
+| `cisco-axl get Phone SEP...`                   | No      | Read operation      |
+| `cisco-axl list Phone --search "name=SEP%"`    | No      | Read operation      |
+| `cisco-axl sql query "SELECT ..."`             | No      | Read-only SQL       |
+| `cisco-axl operations --filter phone`          | No      | Schema discovery    |
+| `cisco-axl describe getPhone`                  | No      | Schema discovery    |
+| `cisco-axl add Phone --data '{...}'`           | **Yes** | Creates a resource  |
+| `cisco-axl update Phone SEP... --data '{...}'` | **Yes** | Modifies a resource |
+| `cisco-axl remove Phone SEP...`                | **Yes** | Deletes a resource  |
+| `cisco-axl execute applyPhone --tags '{...}'`  | **Yes** | Executes an action  |
+| `cisco-axl sql update "UPDATE ..."`            | **Yes** | Modifies database   |
+
+### Alternative: Use the built-in `--read-only` flag
+
+The CLI has a native `--read-only` flag that restricts to `get`, `list`, `describe`, `operations`, and `sql query`:
+
+```bash
+cisco-axl --read-only add Phone --data '{...}'
+# Error: Write operations are not allowed in read-only mode
+```
+
+You can enforce this globally by adding a hook that appends `--read-only` to every command:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "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; }"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Audit Logging
+
+All cisco-axl operations are logged to `~/.cisco-axl/audit.jsonl` by default. This provides a record of every command run by Claude or any other agent.

package/docs/cli.md

@@ -0,0 +1,109 @@
+# CLI Reference
+
+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.
+
+## 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 |
+| `doctor` | Check AXL connectivity and configuration health |
+
+## Operation Discovery
+
+```bash
+# 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"}'
+```
+
+## 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"
+}
+```
+
+## 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`.
+
+## 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
+```
+
+## 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
+```

package/package.json

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

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

@@ -1,13 +1,17 @@
 ---
 name: cisco-axl-cli
 description: Use when managing Cisco CUCM via the cisco-axl CLI — phones, lines, route patterns, partitions, calling search spaces, SIP profiles, and any AXL operation. Covers CRUD operations, SQL queries, operation discovery, bulk provisioning from CSV, and raw AXL execute commands.
+license: MIT
+metadata:
+  author: sieteunoseis
+  version: "1.0.0"
 ---
 
 # Cisco AXL CLI
 
 A CLI for Cisco Unified Communications Manager (CUCM) Administrative XML (AXL) operations.
 
-## Prerequisites
+## Setup
 
 The CLI must be available. Either:
 
@@ -22,20 +26,22 @@ 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
+### Configuration
 
-Configure a CUCM cluster:
+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> --password <pass> --cucm-version <ver> --insecure
+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:
+Or use environment variables (set via your shell profile, a `.env` file, or a secrets manager — never hardcode credentials):
 
 ```bash
-export CUCM_HOST=10.0.0.1 CUCM_USERNAME=admin CUCM_PASSWORD=secret CUCM_VERSION=14.0
+# These should be set securely, e.g. via dotenv, vault, or shell profile
+# CUCM_HOST, CUCM_USERNAME, CUCM_PASSWORD, CUCM_VERSION
 ```
 
 Test the connection:
@@ -44,7 +50,7 @@ Test the connection:
 cisco-axl config test
 ```
 
-## Common Operations
+## Common Workflows
 
 ### Get a single item
 
@@ -90,7 +96,7 @@ 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
+### Discovering Operations
 
 This is the CLI's most powerful feature. Discover and use ANY AXL operation dynamically — no static command definitions.
 
@@ -117,7 +123,7 @@ cisco-axl execute doLdapSync --tags '{"name":"LDAP_Main"}'
 cisco-axl execute applyPhone --tags '{"name":"SEP001122334455"}'
 ```
 
-## Bulk Operations from CSV
+### Bulk Operations from CSV
 
 For provisioning multiple items, use templates with CSV files. Requires optional packages: `npm install json-variables csv-parse`
 
@@ -173,16 +179,17 @@ Use `--format` to control output:
 
 **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
+### Multiple Clusters
 
 ```bash
-cisco-axl config add lab --host 10.0.0.1 --username admin --password pass --cucm-version 14.0 --insecure
-cisco-axl config add prod --host 10.0.0.2 --username axladmin --password pass --cucm-version 15.0 --insecure
+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
+### Command Chaining
 
 Shell `&&` chains commands sequentially — each waits for the previous to complete, and the chain stops on the first failure:
 
@@ -193,7 +200,7 @@ cisco-axl add Css --data '{"name":"CSS_INTERNAL","members":{"member":{"routePart
 cisco-axl add Line --data '{"pattern":"1000","routePartitionName":"PT_INTERNAL"}'
 ```
 
-## Piping with --stdin
+### Piping with --stdin
 
 Use `--stdin` to pipe JSON between commands or from other tools:
 
@@ -210,7 +217,7 @@ cisco-axl describe applyPhone --format json | jq '.name = "SEP001122334455"' | c
 
 The `--stdin` flag is available on `add`, `update`, and `execute` commands. It is mutually exclusive with `--data`/`--tags` and `--template`.
 
-## Tips
+## 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.