cisco-axl 2.0.0 → 2.1.2

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.0.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,8 @@
     "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": {
     "@types/node": "^22.19.15",

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

@@ -1,6 +1,10 @@
 ---
 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
@@ -9,18 +13,35 @@ A CLI for Cisco Unified Communications Manager (CUCM) Administrative XML (AXL) o
 
 ## Setup
 
-Configure a CUCM cluster:
+The CLI must be available. Either:
 
 ```bash
-cisco-axl config add <name> --host <hostname> --username <user> --password <pass> --cucm-version <ver> --insecure
+# 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 ...`
+
+### 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
+# 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:
@@ -29,7 +50,7 @@ Test the connection:
 cisco-axl config test
 ```
 
-## Common Operations
+## Common Workflows
 
 ### Get a single item
 
@@ -75,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.
 
@@ -102,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`
 
@@ -158,16 +179,45 @@ 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
 ```
 
-## Tips
+### 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`.
+
+## 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.