CLI Reference

rabbitmq-backup is a Rust-based CLI tool for non-destructive backup and restore of RabbitMQ messages and definitions. This page documents every command and flag.

Installation

# From source
cargo install --path crates/rabbitmq-backup-cli

# Or build a release binary
cargo build --release
# Binary at: target/release/rabbitmq-backup

Global Flags

Flag	Short	Description
`--verbose`	`-v`	Enable verbose logging. Count-based: `-v` sets log level to `debug`, `-vv` sets it to `trace`.
`--version`		Print version information and exit.
`--help`	`-h`	Print help information and exit.

Logging Precedence

Logging level is determined in this order:

RUST_LOG environment variable -- if set, takes full priority (e.g. RUST_LOG=rabbitmq_backup_core=trace)
-v flag -- -v enables debug, -vv enables trace for the rabbitmq_backup_core and rabbitmq_backup_cli modules
Default -- info level

Commands

`backup`

Back up messages and definitions from a RabbitMQ cluster to storage.

rabbitmq-backup backup --config <path>

Arguments

Flag	Short	Required	Description
`--config`	`-c`	Yes	Path to the YAML configuration file. The config must have `mode: backup`.

What It Does

Initializes the storage backend (S3, Azure, GCS, or filesystem).
Connects to the RabbitMQ Management API and fetches cluster info.
Exports definitions (vhosts, exchanges, queues, bindings, users) if include_definitions: true.
Discovers queues matching the configured queues selection criteria.
Partitions queues into AMQP (classic/quorum) and stream types.
Backs up AMQP queues in parallel (up to max_concurrent_queues) using the configured requeue_strategy.
Backs up stream queues via the native Stream Protocol if stream_enabled: true.
Writes compressed segments to storage with a 32-byte RBAK header and CRC32 footer.
Generates and stores manifest.json at {backup_id}/manifest.json.

Example

# Basic backup
rabbitmq-backup backup --config backup.yaml

# With debug logging
rabbitmq-backup backup -v --config backup.yaml

# With trace logging
rabbitmq-backup backup -vv --config backup.yaml

Expected Output

INFO  Storage backend initialized
INFO  Connected to RabbitMQ cluster
INFO  Exporting definitions...
INFO  Definitions exported successfully
INFO  Backing up 3 queue(s) (max 4 concurrent)
INFO  Backing up queue orders (vhost=/, type=classic, messages=1542)
INFO  Backing up queue payments (vhost=/, type=quorum, messages=823)
INFO  Backing up queue events (vhost=/, type=classic, messages=256)
INFO  Queue orders backed up: 1542 messages in 2 segment(s)
INFO  Queue payments backed up: 823 messages in 1 segment(s)
INFO  Queue events backed up: 256 messages in 1 segment(s)
INFO  Backup complete: 3 queues, 2621 messages, 4 segments, 1048576 bytes

`restore`

Restore messages and definitions from storage to a RabbitMQ cluster.

rabbitmq-backup restore --config <path>

Arguments

Flag	Short	Required	Description
`--config`	`-c`	Yes	Path to the YAML configuration file. The config must have `mode: restore`.

What It Does

Initializes the storage backend.
Loads the manifest.json for the configured backup_id.
Optionally restores definitions to the target cluster via Management API.
For each queue in the manifest, reads segments from storage.
Applies PITR (Point-in-Time Recovery) filtering using time_window_start / time_window_end.
Publishes messages to the target cluster in batches, with optional publisher confirms and rate limiting.
Supports queue/vhost/exchange remapping.
Optionally creates missing target queues for direct-to-queue restores when create_missing_queues: true.
Optionally uses checkpoint_state to skip completed queues and resume partial restores.
Fails the restore job if mandatory publishes are returned or confirms fail.
Reports statistics: restored, skipped (PITR), and failed messages.

Example

# Basic restore
rabbitmq-backup restore --config restore.yaml

# Dry-run (validate without publishing)
# Set dry_run: true in the config file
rabbitmq-backup restore --config restore-dryrun.yaml

Expected Output

INFO  Storage backend initialized
INFO  Loaded manifest: 3 queues, 2621 messages, 4 segments
INFO  Restoring definitions from backup-001/definitions/definitions.json.zst
INFO  Current target definitions rollback snapshot written to backup-001/definitions/rollback-before-import-...
INFO  Definitions restored successfully
INFO  Restoring queue //orders -> //orders (2 segments, 1542 messages)
INFO  Restoring queue //payments -> //payments (1 segments, 823 messages)
INFO  Restoring queue //events -> //events (1 segments, 256 messages)
INFO  Queue orders restored: 1542 published, 0 skipped (PITR), 0 failed
INFO  Queue payments restored: 823 published, 0 skipped (PITR), 0 failed
INFO  Queue events restored: 256 published, 0 skipped (PITR), 0 failed
INFO  Restore complete: 2621 restored, 0 skipped, 0 failed (3 queues)

Dry-Run Output

INFO  DRY RUN -- no messages will be published
Dry run summary:
  Backup ID: backup-001
  Queues:    3
  Messages:  2621
  Segments:  4
  Size:      1048576 bytes

Restore Safety Options

Use these config fields for production restores:

restore:
  restore_definitions: true
  definitions_selection:
    queues: ["orders"]
  publish_mode: direct-to-queue
  create_missing_queues: true
  checkpoint_state: /var/lib/rabbitmq-backup/restore-checkpoint.db

definitions_selection imports only selected backed-up topology before messages.
create_missing_queues declares absent target queues before direct-to-queue publishing and requires target Management API credentials.
checkpoint_state records restore progress so reruns do not duplicate completed queues.
Missing routes and publisher confirm failures return a non-zero restore result.

`list`

List available backups in a storage location.

rabbitmq-backup list --path <storage-path>

Arguments

Flag	Short	Required	Description
`--path`	`-p`	Yes	Storage path. Accepts local paths or cloud URIs: `s3://bucket/prefix`, `azure://account.blob.core.windows.net/container`, `gcs://bucket`, `file:///path`.
`--backup-id`	`-b`	No	If specified, show details for this specific backup only.

Example

# List all backups on local filesystem
rabbitmq-backup list --path /var/lib/rabbitmq-backup/data

# List backups in S3
rabbitmq-backup list --path s3://rabbitmq-backups

# List backups in Azure Blob
rabbitmq-backup list --path azure://myaccount.blob.core.windows.net/backups

# List a specific backup
rabbitmq-backup list --path s3://rabbitmq-backups --backup-id backup-001

Expected Output

Available backups:
  backup-001  2025-04-10T14:30:00Z  3 queues  2621 messages  1.0 MB
  backup-002  2025-04-11T08:15:00Z  3 queues  3104 messages  1.2 MB
  backup-003  2025-04-12T02:00:00Z  5 queues  8942 messages  3.4 MB

`describe`

Show detailed information about a specific backup.

rabbitmq-backup describe --path <storage-path> --backup-id <id> [--format <format>]

Arguments

Flag	Short	Required	Default	Description
`--path`	`-p`	Yes		Storage path (same format as `list`).
`--backup-id`	`-b`	Yes		The backup ID to describe.
`--format`	`-f`	No	`text`	Output format: `text`, `json`, or `yaml`.

Example

# Human-readable output
rabbitmq-backup describe --path s3://bucket --backup-id backup-001

# JSON output (for scripting)
rabbitmq-backup describe --path s3://bucket --backup-id backup-001 --format json

# YAML output
rabbitmq-backup describe --path s3://bucket --backup-id backup-001 --format yaml

Expected Text Output

Backup: backup-001
  Created:      2025-04-10T14:30:00Z
  Completed:    2025-04-10T14:32:15Z
  Tool Version: 0.1.0
  Cluster:      rabbit@node1
  RabbitMQ:     3.13.2

  Definitions:
    Vhosts: 2   Exchanges: 8   Queues: 5   Users: 3
    Size: 4.2 KB

  Queues:
    /orders (classic) - 1542 messages, 2 segments, 512.0 KB
      segment-0001.zst  1000 msgs  340.0 KB  sha256:abc123...
      segment-0002.zst   542 msgs  172.0 KB  sha256:def456...
    /payments (quorum) - 823 messages, 1 segment, 280.0 KB
      segment-0001.zst   823 msgs  280.0 KB  sha256:789abc...
    /events (classic) - 256 messages, 1 segment, 92.0 KB
      segment-0001.zst   256 msgs   92.0 KB  sha256:012def...

  Totals:
    Messages: 2621   Segments: 4   Size: 884.0 KB

Expected JSON Output

{
  "backup_id": "backup-001",
  "created_at": 1712756400000,
  "completed_at": 1712756535000,
  "backup_tool_version": "0.1.0",
  "source_cluster": "rabbit@node1",
  "rabbitmq_version": "3.13.2",
  "definitions": {
    "key": "backup-001/definitions/definitions.json.zst",
    "vhost_count": 2,
    "queue_count": 5,
    "exchange_count": 8,
    "user_count": 3,
    "size_bytes": 4300
  },
  "queues": [
    {
      "vhost": "/",
      "name": "orders",
      "queue_type": "classic",
      "message_count": 1542,
      "segments": [...]
    }
  ],
  "total_messages": 2621,
  "total_bytes": 905216,
  "total_segments": 4
}

`validate`

Validate the integrity of a backup by checking manifests, segment headers, CRC32 checksums, and SHA-256 hashes.

rabbitmq-backup validate --path <storage-path> --backup-id <id> [--deep]

Arguments

Flag	Short	Required	Default	Description
`--path`	`-p`	Yes		Storage path.
`--backup-id`	`-b`	Yes		The backup ID to validate.
`--deep`	`-d`	No	`false`	Deep validation: download and verify every segment's CRC32 checksum and SHA-256 hash, plus verify record count matches the header. Without `--deep`, only the manifest structure and segment existence are checked.

Example

# Quick validation (manifest + existence checks)
rabbitmq-backup validate --path s3://bucket --backup-id backup-001

# Deep validation (download and verify every segment)
rabbitmq-backup validate --path s3://bucket --backup-id backup-001 --deep

Expected Output (Quick)

Validating backup-001...
  Manifest:     OK
  Definitions:  OK (1 file)
  Segments:     OK (4 files exist)
Validation PASSED

Expected Output (Deep)

Validating backup-001 (deep mode)...
  Manifest:     OK
  Definitions:  OK (1 file)
  Segment backup-001/queues/_default/orders/segment-0001.zst
    Magic:    RBAK  OK
    Version:  1     OK
    CRC32:    OK
    SHA-256:  OK (matches manifest)
    Records:  1000  OK (matches header)
  Segment backup-001/queues/_default/orders/segment-0002.zst
    Magic:    RBAK  OK
    ...
Validation PASSED (4/4 segments OK)

`definitions-export`

Export RabbitMQ definitions (topology and metadata) without backing up messages. This is a lightweight operation that only calls the Management API.

rabbitmq-backup definitions-export --config <path> [--output <file>]

Arguments

Flag	Short	Required	Default	Description
`--config`	`-c`	Yes		Path to the YAML configuration file (needs `source` section).
`--output`	`-o`	No	stdout	Output file path. If omitted, definitions JSON is written to stdout.

Example

# Export to stdout
rabbitmq-backup definitions-export --config config.yaml

# Export to file
rabbitmq-backup definitions-export --config config.yaml --output definitions.json

# Pipe to jq for inspection
rabbitmq-backup definitions-export --config config.yaml | jq '.queues | length'

What Is Exported

The exported JSON follows the RabbitMQ Management API definitions format and includes:

Virtual hosts
Users and permissions
Exchanges
Queues
Bindings
Policies
Parameters
Global parameters

`definitions-import`

Import definitions from a JSON file into a RabbitMQ cluster.

rabbitmq-backup definitions-import --config <path> --input <file>

Arguments

Flag	Short	Required	Description
`--config`	`-c`	Yes	Path to the YAML configuration file (needs `target` section with Management API credentials).
`--input`	`-i`	Yes	Path to the definitions JSON file to import.

Example

# Import definitions
rabbitmq-backup definitions-import --config config.yaml --input definitions.json

caution

Importing definitions will create or update vhosts, exchanges, queues, bindings, users, and policies on the target cluster. Existing objects with the same names will be updated. This operation cannot be automatically rolled back.

Exit Codes

Code	Meaning
`0`	Success
`1`	Runtime error (connection failure, storage error, etc.)
`2`	CLI argument parsing error (missing required flag, unknown command)

Environment Variables

Variable	Description
`RUST_LOG`	Override log level (e.g. `RUST_LOG=rabbitmq_backup_core=debug,rabbitmq_backup_cli=info`)
`AWS_ACCESS_KEY_ID`	S3 access key (fallback if not in config)
`AWS_SECRET_ACCESS_KEY`	S3 secret key (fallback if not in config)
`AZURE_STORAGE_KEY`	Azure storage account key (fallback)
`AZURE_STORAGE_ACCOUNT_KEY`	Azure storage account key (alternative env var)
`AZURE_STORAGE_SAS_TOKEN`	Azure SAS token (fallback)
`AZURE_CLIENT_ID`	Azure AD client ID for service principal auth
`AZURE_TENANT_ID`	Azure AD tenant ID for service principal auth
`AZURE_CLIENT_SECRET`	Azure AD client secret for service principal auth
`AZURE_FEDERATED_TOKEN_FILE`	If set, enables workload identity auth for Azure
`GOOGLE_APPLICATION_CREDENTIALS`	Path to GCS service account JSON key file

Shell Completion

You can generate shell completion scripts using the standard clap mechanism:

# Bash
rabbitmq-backup completions bash > /etc/bash_completion.d/rabbitmq-backup

# Zsh
rabbitmq-backup completions zsh > /usr/local/share/zsh/site-functions/_rabbitmq-backup

# Fish
rabbitmq-backup completions fish > ~/.config/fish/completions/rabbitmq-backup.fish

note

Shell completions are a planned feature. The current binary does not yet include a completions subcommand.

Installation​

Global Flags​

Logging Precedence​

Commands​

backup​

Arguments​

What It Does​

Example​

Expected Output​

restore​

Arguments​

What It Does​

Example​

Expected Output​

Dry-Run Output​

Restore Safety Options​

list​

Arguments​

Example​

Expected Output​

describe​

Arguments​

Example​

Expected Text Output​

Expected JSON Output​

validate​

Arguments​

Example​

Expected Output (Quick)​

Expected Output (Deep)​

definitions-export​

Arguments​

Example​

What Is Exported​

definitions-import​

Arguments​

Example​

Exit Codes​

Environment Variables​

Shell Completion​

Installation

Global Flags

Logging Precedence

Commands

`backup`

Arguments

What It Does

Example

Expected Output

`restore`

Arguments

What It Does

Example

Expected Output

Dry-Run Output

Restore Safety Options

`list`

Arguments

Example

Expected Output

`describe`

Arguments

Example

Expected Text Output

Expected JSON Output

`validate`

Arguments

Example

Expected Output (Quick)

Expected Output (Deep)

`definitions-export`

Arguments

Example

What Is Exported

`definitions-import`

Arguments

Example

Exit Codes

Environment Variables

Shell Completion