Crucible CLI

The kubectl of Azure Service Bus — CLI for message operations, DLQ management, and namespace monitoring.

Install

npm install -g crucible-cli

Quick Start

# Add a namespace (connection string)
crucible config add dev --connection-string "Endpoint=sb://..."

# Or use Entra ID (DefaultAzureCredential)
crucible config add prod --namespace "my-ns.servicebus.windows.net"

# Interactive browser login
crucible login --tenant <tenant-id>

# Health overview
crucible status
crucible status --watch          # auto-refresh every 5s
crucible status --sort dlq       # surface problems first
crucible status --dlq            # only entities with dead-letters
crucible status --dlq-subs       # topics with DLQ subs (shows all sibling subs)
crucible status --dlq-topics     # one row per topic with DLQ (aggregated)
crucible status --filter "*dev*" # glob filter on entity name

# Live TUI dashboard
crucible monitor                 # htop-style, press q to quit
crucible monitor --entity orders # filter to matching entities
crucible monitor --interval 10   # poll every 10s

# Browse messages
crucible peek my-queue
crucible peek my-topic/my-sub --dlq --count 50
crucible inspect my-queue --seq 12345

# Search
crucible search my-queue --body "OrderId:123"
crucible search my-queue --property "CorrelationId=abc"

# Dead-letter management (queues)
crucible deadletter my-queue --reasons
crucible replay my-queue --dry-run
crucible replay my-queue --count 10 --backup before-replay.json
crucible purge my-queue --dlq

# Dead-letter management (topic subscriptions)
crucible deadletter my-topic/my-sub --reasons
crucible replay my-topic/my-sub --dry-run
crucible purge my-topic/my-sub --dlq

# Send messages
crucible send my-queue --body '{"orderId": 123}'
crucible send my-topic/my-sub --body '{"event": "retry"}'
crucible send my-queue --file payload.json --count 100 --delay 50

# Export / Import
crucible export my-queue --dlq --format json > dlq-messages.json
crucible export my-topic/my-sub --dlq --format json > dlq-messages.json
crucible export my-queue --format csv > messages.csv
crucible import my-queue --file dlq-messages.json

# Namespace topology
crucible topology                # tree view
crucible topology --rules        # include filter expressions
crucible topology --format mermaid > topology.md

# Snapshot & drift detection
crucible snapshot -o baseline.json
crucible diff baseline.json      # compare live vs snapshot
crucible diff ns-dev.servicebus.windows.net ns-prod.servicebus.windows.net

# Cost analysis
crucible costs
crucible costs --optimize        # surface unused queues, DLQ issues

# Local DLQ alerting
crucible watch my-queue --dlq-threshold 10 --notify
crucible watch my-queue --dlq-threshold 100 --exec 'curl -X POST https://hooks.slack.com/... -d "{\"text\":\"DLQ alert: $CRUCIBLE_ENTITY has $CRUCIBLE_DLQ messages\"}"'

Entity Format

Most commands accept an <entity> argument. Use the queue name for queues, or topic/subscription for topic subscriptions:

| Format | Target | |---|---| | my-queue | Queue named my-queue | | my-topic/my-sub | Subscription my-sub on topic my-topic |

For example, crucible deadletter my-queue targets a queue's DLQ, while crucible deadletter my-topic/my-sub targets the subscription's DLQ.

Commands

Foundation

| Command | Description | |---|---| | crucible config add/list/use/remove | Manage namespace profiles | | crucible login | Interactive browser login (Entra ID) |

Core Operations

| Command | Description | |---|---| | crucible status | Health overview — --filter, --dlq, --dlq-subs, --dlq-topics, --watch, --sort, --json | | crucible peek | Peek messages — --dlq, --count, --format json\|table | | crucible inspect | Inspect single message by --seq sequence number | | crucible search | Search by --body text or --property key=value | | crucible deadletter | List DLQ messages, --reasons to aggregate by dead-letter reason | | crucible replay | Replay DLQ messages — --count, --filter, --dry-run, --to, --backup | | crucible purge | Purge messages with confirmation — --dlq, --yes, --backup | | crucible send | Send messages — --body, --file, --property, --count, --schedule |

Monitoring & Advanced

| Command | Description | |---|---| | crucible monitor | Live TUI dashboard (ink) — real-time counts, DLQ trends, --entity, --interval | | crucible watch | Local DLQ alerts — --dlq-threshold, --exec, --notify | | crucible export | Export messages as JSON or CSV (pipe-friendly) | | crucible import | Bulk send from JSON file | | crucible topology | Namespace tree — --format tree\|json\|mermaid, --rules to show filter expressions |

Power Features

| Command | Description | |---|---| | crucible snapshot | Save namespace state (entities, configs, rules) to JSON | | crucible diff | Compare snapshot vs live, or two namespaces (exit code 2 on drift) | | crucible costs | Estimated monthly cost breakdown, --optimize for suggestions |

Authentication

Crucible supports three auth methods:

| Method | Usage | |---|---| | Connection string | crucible config add dev --connection-string "Endpoint=sb://..." | | Entra ID (automatic) | crucible config add prod --namespace "ns.servicebus.windows.net" — uses DefaultAzureCredential (picks up az login, env vars, managed identity) | | Entra ID (interactive) | crucible login --tenant <tenant-id> — opens browser for login |

All commands support --namespace <fqdn> to override the active profile.

Scripting

• --json on status, deadletter, inspect, export, costs, diff, peek, search
• --yes on purge (skip confirmation)
• --backup <file> on replay and purge (save messages before destructive ops)
• Exit codes: 0 success, 1 error, 2 warning/drift detected

# CI example: fail if namespace has drifted from baseline
crucible diff baseline.json || echo "Drift detected!"

# Export DLQ messages as JSON for scripting
crucible export my-queue --dlq --format json | jq '.[].body'

License

MIT