Skip to main content

CLI Reference

Complete reference documentation for all OSO Kafka Backup CLI commands.

Global Options

These options apply to all commands:

kafka-backup [OPTIONS] <COMMAND>
OptionDescription
-v, --verboseEnable verbose logging. Use -v for debug, -vv for trace
-h, --helpPrint help information
-V, --versionPrint version information

backup

Run a backup operation from a Kafka cluster to storage.

kafka-backup backup --config <PATH>

Options

FlagTypeRequiredDescription
-c, --configPATHYesPath to backup configuration YAML

Examples

# Basic backup
kafka-backup backup --config backup.yaml

# With debug logging
kafka-backup -v backup --config /etc/kafka-backup/production.yaml

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

Exit Codes

CodeMeaning
0Backup completed successfully (or graceful shutdown)
1Backup failed

Graceful Shutdown

The backup and restore commands handle SIGTERM and SIGINT (Ctrl+C) for graceful shutdown (v0.8.1+). On signal:

  1. In-progress segments are flushed to storage
  2. A final checkpoint is saved
  3. The process exits with code 0

This ensures safe interruption and allows resuming from the last checkpoint.


restore

Restore data from a backup to a Kafka cluster.

kafka-backup restore --config <PATH>

Options

FlagTypeRequiredDescription
-c, --configPATHYesPath to restore configuration YAML

Examples

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

# Restore with verbose output
kafka-backup -v restore --config dr-restore.yaml

list

List available backups or show details of a specific backup.

kafka-backup list --path <PATH> [--backup-id <ID>]

Options

FlagTypeRequiredDescription
-p, --pathPATHYesPath to storage location (local path or S3 URI)
-b, --backup-idSTRINGNoSpecific backup ID to show details for

Examples

# List all backups in local storage
kafka-backup list --path /var/lib/kafka-backup/data

# List backups in S3
kafka-backup list --path s3://my-bucket/backups

# Show details for a specific backup
kafka-backup list --path /data --backup-id daily-backup-001

Output

Available Backups:
─────────────────────────────────────────────────────────────
daily-backup-001
Created: 2024-12-03T02:00:00Z
Topics: 5
Records: 1,234,567
Size: 128 MB (compressed)
─────────────────────────────────────────────────────────────

status

Show status and statistics of a backup job. Supports two modes:

  1. Static inspection: Inspect stored backup artifacts using --path and --backup-id
  2. Live monitoring: Monitor a running backup using --config (optionally with --watch)
# Static inspection
kafka-backup status --path <PATH> --backup-id <ID> [--db-path <PATH>]

# Live monitoring (one-shot)
kafka-backup status --config <PATH>

# Live monitoring (continuous watch)
kafka-backup status --config <PATH> --watch [--interval <SECS>]

Options

FlagTypeRequiredDescription
-p, --pathPATHNo*Path to storage location (for static inspection)
-b, --backup-idSTRINGNo*Backup ID to show status for (for static inspection)
--db-pathPATHNoPath to offset database (for tracking progress)
-c, --configPATHNo*Path to config file (for live monitoring)
--watchFLAGNoEnable continuous watch mode (requires --config)
--intervalINTNoRefresh interval in seconds for watch mode (default: 2)

*Either --config OR both --path and --backup-id are required.

Examples

Static inspection of stored backup:

kafka-backup status --path /data --backup-id backup-001

kafka-backup status -p /data -b backup-001 --db-path /var/lib/kafka-backup/offsets.db

Live monitoring of running backup (one-shot):

kafka-backup status --config backup.yaml

Live monitoring with continuous watch:

# Default 2-second refresh
kafka-backup status --config backup.yaml --watch

# Custom 5-second refresh interval
kafka-backup status --config backup.yaml --watch --interval 5

Live Monitoring Output

When using --config, the status command connects to the running backup's metrics server (/health and /metrics endpoints) and displays:

================================================================
OSO Kafka Backup - Live Status
================================================================
Backup ID: production-backup Uptime: 00:15:32
Status: RUNNING
================================================================
Progress
|- Records: 1,234,567
|- Bytes: 256.0 MB (compressed)
|- Throughput: 15234 rec/s | 3.2 MB/s
|- Lag: 45,000 records (orders-0)
================================================================
Components
|- kafka: [OK] ok
|- storage: [OK] ok
|- checkpointing: [OK] ok
================================================================
Compression: 3.2x ratio | Errors: 0
================================================================
Last updated: 2025-01-30 14:32:15 | Refresh: 2s | Ctrl+C to exit

Static Inspection Output

When using --path and --backup-id, shows:

  • Manifest information (created date, source cluster)
  • Topic/partition/segment counts
  • Record and size statistics (compressed and uncompressed)
  • Compression ratio
  • Offset tracking status per partition

Requirements for Live Monitoring

Metrics must be enabled in your backup config:

metrics:
enabled: true
port: 8080
bind_address: "0.0.0.0"

describe

Show detailed backup manifest information.

kafka-backup describe --path <PATH> --backup-id <ID> [--format <FORMAT>]

Options

FlagTypeRequiredDefaultDescription
-p, --pathPATHYes-Path to storage location
-b, --backup-idSTRINGYes-Backup ID to describe
-f, --formatSTRINGNotextOutput format: text, json, yaml

Examples

# Human-readable output
kafka-backup describe --path /data --backup-id backup-001

# JSON for scripting
kafka-backup describe -p /data -b backup-001 --format json

# YAML output
kafka-backup describe -p /data -b backup-001 -f yaml

Output Information

  • Backup ID and creation timestamp
  • Source cluster ID and brokers
  • Compression algorithm
  • Topic/partition/segment/record counts
  • Compressed and uncompressed sizes
  • Compression ratio
  • Time range of backed-up data
  • Per-topic and per-partition details

validate

Validate backup integrity.

kafka-backup validate --path <PATH> --backup-id <ID> [--deep]

Options

FlagTypeRequiredDefaultDescription
-p, --pathPATHYes-Path to storage location
-b, --backup-idSTRINGYes-Backup ID to validate
--deepBOOLNofalsePerform deep validation (read and verify each segment)

Examples

# Shallow validation (quick - checks existence and metadata)
kafka-backup validate --path /data --backup-id backup-001

# Deep validation (thorough - reads and parses all segments)
kafka-backup validate -p /data -b backup-001 --deep

Validation Report

Validation Report: backup-001
════════════════════════════════════════════════════════════

Segments:
Checked: 156
Valid: 156
Missing: 0
Corrupted: 0

Records Validated: 2,456,789

Issues Found: 0

Result: ✓ VALID

validate-restore

Validate a restore configuration without executing it.

kafka-backup validate-restore --config <PATH> [--format <FORMAT>]

Options

FlagTypeRequiredDefaultDescription
-c, --configPATHYes-Path to restore configuration file
-f, --formatSTRINGNotextOutput format: text, json, yaml

Examples

# Validate restore config
kafka-backup validate-restore --config restore.yaml

# Get JSON report for CI/CD
kafka-backup validate-restore -c restore.yaml --format json

Report Contents

  • Restore status (VALID or INVALID)
  • Topics to restore (count and names)
  • Segments to process
  • Records and bytes to restore
  • Time range of restore
  • Consumer offset actions
  • Errors and warnings

show-offset-mapping

Show offset mapping for a backup.

kafka-backup show-offset-mapping --path <PATH> --backup-id <ID> [--format <FORMAT>]

Options

FlagTypeRequiredDefaultDescription
-p, --pathPATHYes-Path to storage location
-b, --backup-idSTRINGYes-Backup ID to show offset mapping for
-f, --formatSTRINGNotextOutput: text, json, yaml, csv

Examples

# Human-readable output
kafka-backup show-offset-mapping --path /data --backup-id backup-001

# CSV for spreadsheets
kafka-backup show-offset-mapping -p /data -b backup-001 --format csv

# JSON for programmatic use
kafka-backup show-offset-mapping -p /data -b backup-001 -f json

Output

Offset Mapping: backup-001
─────────────────────────────────────────────────────────────
Topic Partition Source Start Source End Records
─────────────────────────────────────────────────────────────
orders 0 0 150233 150234
orders 1 0 148891 148892
orders 2 0 152456 152457
payments 0 0 78234 78235
...

To reset consumer groups, use:
kafka-consumer-groups --bootstrap-server <broker> \
--group <group-name> --topic orders:0 \
--reset-offsets --to-offset 150233 --execute

offset-reset

Generate or execute consumer group offset reset plans.

offset-reset plan

Generate an offset reset plan from backup's offset mapping.

kafka-backup offset-reset plan \
--path <PATH> \
--backup-id <ID> \
--groups <GROUPS> \
--bootstrap-servers <SERVERS> \
[--format <FORMAT>] \
[--dry-run <BOOL>]

Options

FlagTypeRequiredDefaultDescription
-p, --pathPATHYes-Path to storage location
-b, --backup-idSTRINGYes-Backup ID with offset mapping
-g, --groupsSTRINGYes-Consumer groups (comma-separated)
--bootstrap-serversSTRINGYes-Kafka bootstrap servers
-f, --formatSTRINGNotextOutput: text, json, csv, shell-script
--dry-runBOOLNotruePreview only, no changes

Examples

kafka-backup offset-reset plan \
--path /data \
--backup-id backup-001 \
--groups my-group,another-group \
--bootstrap-servers localhost:9092

# Generate shell script
kafka-backup offset-reset plan \
-p /data -b backup-001 \
-g consumer-group \
--bootstrap-servers broker-1:9092 \
--format shell-script

offset-reset execute

Execute an offset reset plan.

kafka-backup offset-reset execute \
--path <PATH> \
--backup-id <ID> \
--groups <GROUPS> \
--bootstrap-servers <SERVERS> \
[--security-protocol <PROTOCOL>]

Options

FlagTypeRequiredDefaultDescription
-p, --pathPATHYes-Path to storage location
-b, --backup-idSTRINGYes-Backup ID
-g, --groupsSTRINGYes-Consumer groups
--bootstrap-serversSTRINGYes-Kafka bootstrap servers
--security-protocolSTRINGNoPLAINTEXTSecurity: PLAINTEXT, SSL, SASL_SSL, SASL_PLAINTEXT
--sasl-mechanismSTRINGNo-SASL mechanism: PLAIN, SCRAM-SHA256, SCRAM-SHA512, GSSAPI
--sasl-usernameSTRINGNo-SASL username (for PLAIN / SCRAM)
--sasl-passwordSTRINGNo-SASL password (for PLAIN / SCRAM). Prefer SASL_PASSWORD env var.
--sasl-kerberos-service-nameSTRINGNo-Broker service-principal name (GSSAPI only, e.g. kafka)
--sasl-keytabPATHNo-Path to Kerberos keytab (GSSAPI only)
--sasl-krb5-configPATHNo-Override path to krb5.conf (GSSAPI only)
SASL/GSSAPI requires a feature-gated build

--sasl-mechanism GSSAPI is rejected at startup unless the CLI was built with --features gssapi. See Security Setup → SASL/GSSAPI.

Examples

kafka-backup offset-reset execute \
--path /data \
--backup-id backup-001 \
--groups my-group \
--bootstrap-servers localhost:9092

# With SSL
kafka-backup offset-reset execute \
-p /data -b backup-001 \
-g consumer-group \
--bootstrap-servers broker-1:9092 \
--security-protocol SSL

# With SASL/GSSAPI (requires --features gssapi at build time)
kafka-backup offset-reset execute \
-p /data -b backup-001 \
-g consumer-group \
--bootstrap-servers broker.prod.corp:9098 \
--security-protocol SASL_PLAINTEXT \
--sasl-mechanism GSSAPI \
--sasl-kerberos-service-name kafka \
--sasl-keytab /etc/kafka-backup/client.keytab \
--sasl-krb5-config /etc/krb5.conf

offset-reset script

Generate a shell script for manual offset reset.

kafka-backup offset-reset script \
--path <PATH> \
--backup-id <ID> \
--groups <GROUPS> \
--bootstrap-servers <SERVERS> \
[--output <PATH>]

Options

FlagTypeRequiredDefaultDescription
-o, --outputPATHNostdoutOutput file path

offset-reset-bulk

Execute bulk parallel offset reset (optimized for large consumer groups).

kafka-backup offset-reset-bulk \
--path <PATH> \
--backup-id <ID> \
--groups <GROUPS> \
--bootstrap-servers <SERVERS> \
[OPTIONS]

Options

FlagTypeRequiredDefaultDescription
-p, --pathPATHYes-Path to storage location
-b, --backup-idSTRINGYes-Backup ID
-g, --groupsSTRINGYes-Consumer groups (comma-separated)
--bootstrap-serversSTRINGYes-Kafka bootstrap servers
--max-concurrentINTNo50Maximum concurrent requests
--max-retriesINTNo3Maximum retry attempts
--security-protocolSTRINGNoPLAINTEXTSecurity: PLAINTEXT, SSL, SASL_SSL, SASL_PLAINTEXT
--sasl-mechanismSTRINGNo-SASL mechanism: PLAIN, SCRAM-SHA256, SCRAM-SHA512, GSSAPI
--sasl-usernameSTRINGNo-SASL username (for PLAIN / SCRAM)
--sasl-passwordSTRINGNo-SASL password (for PLAIN / SCRAM). Prefer SASL_PASSWORD env var.
--sasl-kerberos-service-nameSTRINGNo-Broker service-principal name (GSSAPI only, e.g. kafka)
--sasl-keytabPATHNo-Path to Kerberos keytab (GSSAPI only)
--sasl-krb5-configPATHNo-Override path to krb5.conf (GSSAPI only)
-f, --formatSTRINGNotextOutput: text, json
SASL/GSSAPI requires a feature-gated build

--sasl-mechanism GSSAPI is rejected at startup unless the CLI was built with --features gssapi. See Security Setup → SASL/GSSAPI.

Examples

kafka-backup offset-reset-bulk \
--path /data \
--backup-id backup-001 \
--groups group1,group2 \
--bootstrap-servers broker-1:9092,broker-2:9092 \
--max-concurrent 100

# With metrics output
kafka-backup offset-reset-bulk \
-p /data -b backup-001 \
-g my-group \
--bootstrap-servers localhost:9092 \
--format json

# With SASL/GSSAPI (requires --features gssapi at build time)
kafka-backup offset-reset-bulk \
-p /data -b backup-001 \
-g my-group \
--bootstrap-servers broker.prod.corp:9098 \
--security-protocol SASL_PLAINTEXT \
--sasl-mechanism GSSAPI \
--sasl-kerberos-service-name kafka \
--sasl-keytab /etc/kafka-backup/client.keytab \
--sasl-krb5-config /etc/krb5.conf \
--max-concurrent 100

Performance

  • ~50x faster than sequential offset reset
  • Per-partition retry with exponential backoff
  • Detailed metrics (p50/p99 latency, throughput)
  • Progress reporting

offset-rollback

Snapshot and rollback consumer group offsets.

offset-rollback snapshot

Create a snapshot of current consumer group offsets.

kafka-backup offset-rollback snapshot \
--path <PATH> \
--groups <GROUPS> \
--bootstrap-servers <SERVERS> \
[--description <DESC>]

Options

FlagTypeRequiredDescription
-p, --pathPATHYesPath to store snapshots
-g, --groupsSTRINGYesConsumer groups
--bootstrap-serversSTRINGYesKafka bootstrap servers
-d, --descriptionSTRINGNoSnapshot description
--security-protocolSTRINGNoSecurity: PLAINTEXT, SSL, SASL_SSL, SASL_PLAINTEXT
--sasl-mechanismSTRINGNoSASL mechanism: PLAIN, SCRAM-SHA256, SCRAM-SHA512, GSSAPI
--sasl-usernameSTRINGNoSASL username (for PLAIN / SCRAM)
--sasl-passwordSTRINGNoSASL password (for PLAIN / SCRAM). Prefer SASL_PASSWORD env var.
--sasl-kerberos-service-nameSTRINGNoBroker service-principal name (GSSAPI only, e.g. kafka)
--sasl-keytabPATHNoPath to Kerberos keytab (GSSAPI only)
--sasl-krb5-configPATHNoOverride path to krb5.conf (GSSAPI only)
-f, --formatSTRINGNoOutput: text, json
SASL/GSSAPI requires a feature-gated build

--sasl-mechanism GSSAPI is rejected at startup unless the CLI was built with --features gssapi. See Security Setup → SASL/GSSAPI.

Example

kafka-backup offset-rollback snapshot \
--path /data/snapshots \
--groups my-group \
--bootstrap-servers localhost:9092 \
--description "Before maintenance"

# With SASL/GSSAPI (requires --features gssapi at build time)
kafka-backup offset-rollback snapshot \
--path /data/snapshots \
--groups my-group \
--bootstrap-servers broker.prod.corp:9098 \
--security-protocol SASL_PLAINTEXT \
--sasl-mechanism GSSAPI \
--sasl-kerberos-service-name kafka \
--sasl-keytab /etc/kafka-backup/client.keytab \
--sasl-krb5-config /etc/krb5.conf \
--description "Before GSSAPI restore"

offset-rollback list

List available offset snapshots.

kafka-backup offset-rollback list --path <PATH>

offset-rollback show

Show details of a specific snapshot.

kafka-backup offset-rollback show \
--path <PATH> \
--snapshot-id <ID>

offset-rollback rollback

Rollback offsets to a previous snapshot.

kafka-backup offset-rollback rollback \
--path <PATH> \
--snapshot-id <ID> \
--bootstrap-servers <SERVERS> \
[--verify <BOOL>]

Options

FlagTypeRequiredDefaultDescription
--verifyBOOLNotrueVerify offsets after rollback

offset-rollback verify

Verify current offsets match a snapshot.

kafka-backup offset-rollback verify \
--path <PATH> \
--snapshot-id <ID> \
--bootstrap-servers <SERVERS>

offset-rollback delete

Delete a snapshot.

kafka-backup offset-rollback delete \
--path <PATH> \
--snapshot-id <ID>

three-phase-restore

Run complete three-phase restore with automatic offset reset.

kafka-backup three-phase-restore --config <PATH>

Options

FlagTypeRequiredDescription
-c, --configPATHYesPath to configuration file

What It Does

  1. Phase 1: Collect offset headers from source backup
  2. Phase 2: Restore data to target cluster
  3. Phase 3: Reset consumer group offsets

Example

kafka-backup three-phase-restore --config dr-restore.yaml

Output

Three-Phase Restore Report
════════════════════════════════════════════════════════════

Backup ID: production-backup-001
Status: ✓ SUCCESS

Phase 2 - Data Restore:
Records Restored: 2,456,789
Topics: 4
Duration: 8m 23s

Phase 3 - Offset Reset:
Strategy: header-based
Consumer Groups: 3
Partitions Reset: 33

Warnings: 0

snapshot-groups

Snapshot consumer group committed offsets for all topics covered by a backup.

Queries every broker individually (KRaft-safe — avoids missing groups whose coordinator lives on a non-bootstrap broker), fetches committed offsets, filters to groups with offsets on backed-up topics, and writes {backup_id}/consumer-groups-snapshot.json to the configured storage backend.

The snapshot can be loaded automatically at restore time with auto_consumer_groups: true in the restore configuration, or read manually to reconstruct consumer positions after a disaster recovery event.

kafka-backup snapshot-groups --config <FILE>

Options

FlagTypeRequiredDescription
-c, --configPATHYesPath to backup configuration file (must have mode: backup)
-v, --verboseflagNoEnable verbose logging (-v debug, -vv trace)

Examples

# Capture consumer group offsets after a one-shot backup
kafka-backup backup --config backup.yaml
kafka-backup snapshot-groups --config backup.yaml

# Verify the snapshot was written
aws s3 cp s3://my-bucket/my-backup/consumer-groups-snapshot.json - | jq .

# Use the snapshot at restore time
kafka-backup restore --config restore.yaml
# restore.yaml must include:
# restore:
# auto_consumer_groups: true

Output

The command writes {backup_id}/consumer-groups-snapshot.json to the configured storage backend with this structure:

{
"snapshot_time": 1744123456789,
"groups": [
{
"group_id": "my-app-group",
"offsets": {
"orders": {
"0": 1500,
"1": 1423,
"2": 1601
}
}
}
]
}

Notes

  • The config file must use mode: backup — the backup manifest is used to determine which topics are in scope for filtering.
  • To run this automatically after each backup cycle, set consumer_group_snapshot: true in the backup configuration instead.
  • In KRaft mode each broker is group coordinator for only a subset of consumer groups. This command queries all known brokers and deduplicates results, ensuring complete coverage without requiring a ZooKeeper-style single coordinator.

validation

Run backup validation checks and generate compliance evidence reports.

kafka-backup validation <SUBCOMMAND>

validation run

Execute validation checks against a restored cluster and generate evidence.

kafka-backup validation run --config <PATH> [OPTIONS]
FlagTypeRequiredDescription
-c, --configPATHYesPath to validation configuration YAML
--pitrINTNoPITR timestamp override (epoch milliseconds)
--triggered-bySTRINGNoRecord who/what triggered this run

Examples

# Basic validation run
$ kafka-backup validation run --config validation.yaml

# With PITR timestamp and audit trigger
$ kafka-backup validation run \
--config validation.yaml \
--pitr 1711929600000 \
--triggered-by "KPMG Q1 2026 audit"

Exit Codes

CodeMeaning
0All validation checks passed
1One or more checks failed

validation evidence-list

List evidence reports stored in object storage.

kafka-backup validation evidence-list --path <STORAGE_PATH> [OPTIONS]
FlagTypeRequiredDescription
-p, --pathSTRINGYesStorage location (e.g., s3://bucket/prefix)
-l, --limitINTNoMaximum reports to show (default: 50)

validation evidence-get

Download an evidence report from storage.

kafka-backup validation evidence-get --path <STORAGE_PATH> --report-id <ID> --output <FILE> [OPTIONS]
FlagTypeRequiredDescription
-p, --pathSTRINGYesStorage location
-r, --report-idSTRINGYesReport ID to download
-f, --formatSTRINGNoFormat: json (default) or pdf
-o, --outputSTRINGYesOutput file path

validation evidence-verify

Verify the cryptographic signature of an evidence report.

kafka-backup validation evidence-verify --report <FILE> --signature <FILE> [OPTIONS]
FlagTypeRequiredDescription
-r, --reportPATHYesPath to JSON evidence report
-s, --signaturePATHYesPath to detached signature (.sig) file
--public-keyPATHNoPath to PEM-encoded public key for ECDSA verification

Examples

# Verify SHA-256 checksum only
$ kafka-backup validation evidence-verify \
--report evidence-report.json \
--signature evidence-report.sig

# Verify SHA-256 + ECDSA signature
$ kafka-backup validation evidence-verify \
--report evidence-report.json \
--signature evidence-report.sig \
--public-key signing-key-pub.pem

Output

Report ID: validation-9275b4aa-2aeb-4910-a3a6-9e4aa1dc016a
Algorithm: ECDSA-P256-SHA256
Report SHA-256: 2482bbdfa113146e39a4884767002554...
SHA-256 checksum: VALID
ECDSA signature: VALID

Evidence report integrity: VERIFIED

migrate

Enterprise MSK ZooKeeper-to-KRaft migration commands. plan and precheck are free — no license required.

kafka-backup migrate msk-kraft <SUBCOMMAND>
SubcommandLicense RequiredDescription
planNoGenerate migration plan, runbook, IAM policies, cost estimate
precheckNoRead-only cluster compatibility checks
executeYesRun migration through drain-ready
resumeYesResume an in-flight migration
statusYesShow migration state and lag
cutoverYesFreeze producers, translate offsets, prepare for client switch
cutover-ackYesAcknowledge client switch, trigger validation
rollbackYesAbort migration (pre-cutover only)
finalizeYesRun validation, produce signed evidence bundle

See the MSK KRaft Migration CLI Reference for complete flags and options for each subcommand.


Environment Variables

The CLI respects these environment variables:

VariableDescription
KAFKA_BACKUP_CONFIGDefault config file path
RUST_LOGLogging level (e.g., info, debug, trace)
AWS_ACCESS_KEY_IDAWS access key for S3
AWS_SECRET_ACCESS_KEYAWS secret key for S3
AWS_REGIONAWS region for S3
AZURE_STORAGE_ACCOUNTAzure storage account name
AZURE_STORAGE_KEYAzure storage account key
GOOGLE_APPLICATION_CREDENTIALSPath to GCP service account JSON