CLI Basics
The rabbitmq-backup CLI provides seven commands that cover the full backup lifecycle: create backups, restore them, inspect what you have, and manage RabbitMQ definitions independently.
Global Options
Every command supports these flags:
-v, --verbose Enable verbose logging (-v for debug, -vv for trace)
-h, --help Print help
-V, --version Print version
You can also control log verbosity through the RUST_LOG environment variable, which takes priority over the -v flag:
RUST_LOG=debug rabbitmq-backup backup --config backup.yaml
Commands at a Glance
| Command | Purpose |
|---|---|
backup | Back up messages and definitions from RabbitMQ to storage |
restore | Restore messages and definitions to a RabbitMQ cluster |
list | List available backups in a storage location |
describe | Show detailed information about a specific backup |
validate | Verify backup integrity (checksums, manifests, segments) |
definitions-export | Export RabbitMQ definitions only (no messages) |
definitions-import | Import definitions into a RabbitMQ cluster |
backup
Back up messages and definitions from RabbitMQ to storage. This is the primary command -- it connects to your broker, reads messages non-destructively, compresses them into segments, and writes them to your configured storage backend.
rabbitmq-backup backup --config <CONFIG_FILE>
Flags:
| Flag | Required | Description |
|---|---|---|
-c, --config | Yes | Path to the YAML configuration file |
Examples:
# Run a backup with the default config
rabbitmq-backup backup --config backup.yaml
# Run with debug logging
rabbitmq-backup backup -v --config backup.yaml
# Run with trace-level logging for troubleshooting
rabbitmq-backup backup -vv --config backup.yaml
The backup configuration file controls which queues to include/exclude, the storage backend, compression settings, requeue strategy, and more. See Configuration Reference for the full schema.
restore
Restore messages and definitions from a backup to a RabbitMQ cluster. Supports publisher confirms for reliable delivery and dry-run mode for pre-flight validation.
rabbitmq-backup restore --config <CONFIG_FILE>
Flags:
| Flag | Required | Description |
|---|---|---|
-c, --config | Yes | Path to the YAML configuration file |
Examples:
# Restore from a backup
rabbitmq-backup restore --config restore.yaml
# Dry-run: validate without publishing any messages
# (set dry_run: true in the config file)
rabbitmq-backup restore --config restore-dryrun.yaml
Restoring to a queue that already contains messages will add messages to the queue -- it does not replace existing content. If you need an empty target, purge the queue first.
list
List all available backups found in a storage location. Works with any supported storage backend.
rabbitmq-backup list --path <STORAGE_PATH>
Flags:
| Flag | Required | Description |
|---|---|---|
-p, --path | Yes | Storage path: local path, s3://bucket/prefix, azure://container/prefix, or gcs://bucket/prefix |
-b, --backup-id | No | Filter to a specific backup ID |
Examples:
# List backups on local filesystem
rabbitmq-backup list --path /var/lib/rabbitmq-backup/data
# List backups in S3
rabbitmq-backup list --path s3://my-bucket/rabbitmq-backups
# List backups in Azure Blob Storage
rabbitmq-backup list --path azure://my-container/backups
# List backups in Google Cloud Storage
rabbitmq-backup list --path gcs://my-bucket/backups
describe
Show detailed metadata about a specific backup, including queue names, message counts, segment counts, and sizes.
rabbitmq-backup describe --path <STORAGE_PATH> --backup-id <BACKUP_ID>
Flags:
| Flag | Required | Description |
|---|---|---|
-p, --path | Yes | Storage path |
-b, --backup-id | Yes | Backup ID to describe |
-f, --format | No | Output format: text (default), json, or yaml |
Examples:
# Describe a backup in human-readable format
rabbitmq-backup describe --path ./data --backup-id backup-001
# Output as JSON (useful for scripting)
rabbitmq-backup describe --path s3://bucket/prefix --backup-id backup-001 --format json
# Output as YAML
rabbitmq-backup describe --path ./data --backup-id backup-001 --format yaml
Use --format json when piping output to jq or other tools:
rabbitmq-backup describe --path ./data --backup-id backup-001 --format json | jq '.queues[].message_count'
validate
Verify the integrity of a backup. Checks that manifests are present and well-formed, definitions files decompress correctly, and segment checksums match.
rabbitmq-backup validate --path <STORAGE_PATH> --backup-id <BACKUP_ID>
Flags:
| Flag | Required | Description |
|---|---|---|
-p, --path | Yes | Storage path |
-b, --backup-id | Yes | Backup ID to validate |
-d, --deep | No | Enable deep validation: verify every segment's checksum byte-by-byte |
Examples:
# Quick validation (manifest + structure only)
rabbitmq-backup validate --path ./data --backup-id backup-001
# Deep validation (verify all segment checksums)
rabbitmq-backup validate --path s3://bucket/prefix --backup-id backup-001 --deep
Run quick validation after every backup as part of your automation. Reserve deep validation for periodic audits or before critical restores -- it reads every segment from storage and can be slow for large backups.
definitions-export
Export RabbitMQ definitions (exchanges, queues, bindings, policies, users, permissions) via the Management HTTP API. This is a lightweight operation that captures topology only -- no messages.
rabbitmq-backup definitions-export --config <CONFIG_FILE> [--output <FILE>]
Flags:
| Flag | Required | Description |
|---|---|---|
-c, --config | Yes | Path to the YAML configuration file (uses source.management_url and credentials) |
-o, --output | No | Output file path. If omitted, definitions are printed to stdout |
Examples:
# Export definitions to a file
rabbitmq-backup definitions-export --config config.yaml --output definitions.json
# Export to stdout (pipe to jq for formatting)
rabbitmq-backup definitions-export --config config.yaml | jq .
# Export and compress
rabbitmq-backup definitions-export --config config.yaml --output definitions.json
zstd definitions.json
definitions-import
Import definitions into a RabbitMQ cluster via the Management HTTP API. Use this to recreate topology before restoring messages, or to replicate topology across environments.
rabbitmq-backup definitions-import --config <CONFIG_FILE> --input <FILE>
Flags:
| Flag | Required | Description |
|---|---|---|
-c, --config | Yes | Path to the YAML configuration file (uses target.management_url and credentials) |
-i, --input | Yes | Path to the definitions JSON file to import |
Examples:
# Import definitions from a file
rabbitmq-backup definitions-import --config config.yaml --input definitions.json
# Typical workflow: export from source, import to target
rabbitmq-backup definitions-export --config source.yaml --output defs.json
rabbitmq-backup definitions-import --config target.yaml --input defs.json
Importing definitions is additive -- it will not delete existing exchanges, queues, or bindings. If a resource already exists with the same name, the import will update it to match the definition file. Users and permissions are merged.
What's Next?
- First Backup Tutorial -- put these commands together in a full workflow
- CLI Reference -- exhaustive flag and option documentation
- Configuration Reference -- full YAML configuration schema