CLI command reference

Complete reference for the Infrahub Ops CLI tools (infrahub-backup, infrahub-collect), their commands, flags, and options.

infrahub-backup

Command structure

infrahub-backup [global-flags] <command> [flags] [arguments]

Global flags

These flags apply to all infrahub-backup commands:

Flag	Description	Default	Environment Variable
`--project <name>`	Target specific Docker Compose project	Auto-detect	`INFRAHUB_PROJECT`
`--backup-dir <path>`	Directory for backup files	`./infrahub_backups`	`INFRAHUB_BACKUP_DIR`
`--log-format <text\|json>`	Output format for logs	`text`	`INFRAHUB_LOG_FORMAT`
`--s3-bucket <name>`	S3 bucket name for backup storage	-	`INFRAHUB_S3_BUCKET`
`--s3-prefix <path>`	S3 key prefix (path within bucket)	-	`INFRAHUB_S3_PREFIX`
`--s3-endpoint <url>`	Custom S3 endpoint URL (for MinIO)	-	`INFRAHUB_S3_ENDPOINT`
`--s3-region <region>`	AWS region for S3 bucket	`us-east-1`	`INFRAHUB_S3_REGION`
`--help, -h`	Show help for any command	-	-

Backup commands

create

Creates a comprehensive backup of the Infrahub instance.

Syntax:

infrahub-backup create [flags]

Flags:

Flag	Description	Default	Environment Variable
`--force`	Force backup even if tasks are running	`false`	`INFRAHUB_FORCE`
`--redact`	Redact all attribute values before backup (destructive, requires `--force`)	`false`	`INFRAHUB_REDACT`
`--neo4jmetadata <type>`	Neo4j metadata to include	`all`	`INFRAHUB_NEO4JMETADATA`
`--exclude-taskmanager`	Exclude the task manager (Prefect) database from the backup archive	`false`	`INFRAHUB_EXCLUDE_TASKMANAGER`
`--s3-upload`	Upload backup to S3 after creation	`false`	`INFRAHUB_S3_UPLOAD`
`--s3-keep-local`	Keep local backup file after S3 upload	`false`	`INFRAHUB_S3_KEEP_LOCAL`
`--sleep`	Sleep duration after backup for manual file transfer	`0`	`INFRAHUB_SLEEP`

Neo4j metadata options:

all - Include all user and role metadata
users - Include only user accounts
roles - Include only role definitions
none - Exclude all metadata

Examples:

# Basic backup
infrahub-backup create

# Force backup with running tasks
infrahub-backup create --force

# Backup without user metadata
infrahub-backup create --neo4jmetadata=none

# Backup and upload to S3
infrahub-backup create --s3-upload --s3-bucket my-backups --s3-prefix infrahub/prod

# Backup and upload to S3, keeping local copy
infrahub-backup create --s3-upload --s3-bucket my-backups --s3-keep-local

# Create a redacted backup (replaces all attribute values with random UUIDs)
infrahub-backup create --redact --force

restore

Restores Infrahub from a backup file or S3 URI.

Syntax:

infrahub-backup restore <backup-file|s3-uri>

Arguments:

<backup-file|s3-uri> - Path to backup archive or S3 URI (required)
- Local file: infrahub_backup_20250929_143022.tar.gz
- S3 URI: s3://bucket/prefix/infrahub_backup_20250929_143022.tar.gz

Flags:

Flag	Description	Default
`--exclude-taskmanager`	Skip restoring the task manager database even if the dump is present	`false`
`--migrate-format`	Run Neo4j database format migration after restore	`false`
`--reset-deployment-id`	Generate a new Root node UUID after restore to detach this instance from the source deployment ID	`false`

Examples:

# Restore from local file
infrahub-backup restore infrahub_backup_20250929_143022.tar.gz

# Restore from S3
infrahub-backup restore s3://my-backups/infrahub/prod/infrahub_backup_20250929_143022.tar.gz

# Restore from MinIO
infrahub-backup restore --s3-endpoint http://minio.local:9000 s3://my-backups/infrahub_backup_20250929_143022.tar.gz

# Restore when the task manager database was excluded from the backup
infrahub-backup restore infrahub_backup_20251022_120000.tar.gz --exclude-taskmanager

Environment commands

environment detect

Detects and displays the current deployment environment.

Syntax:

infrahub-backup environment detect

Example output:

INFO[0000] Detecting deployment environment...
INFO[0000] Docker environment detected
INFO[0000] Found Docker Compose project: infrahub-demo

environment list

Lists all available Infrahub Docker Compose projects.

Syntax:

infrahub-backup environment list

Example output:

infrahub-production  Running   7/7
infrahub-staging     Running   7/7
infrahub-dev         Stopped   0/7

Utility commands

version

Displays version information.

Syntax:

infrahub-backup version

Example output:

Version: 1.0.0

update

Updates the running binary to a newer release. Downloads the matching artifact from GitHub Releases, verifies its SHA-256 checksum, and replaces the binary atomically. Available on both infrahub-backup and infrahub-collect.

Syntax:

infrahub-backup update [flags]

Flags:

Flag	Description	Default
`--check`	Report whether an update is available without installing it	`false`
`--yes, -y`	Skip the confirmation prompt (required for non-interactive use)	`false`
`--version <tag>`	Install a specific release (e.g. `v1.7.2`) instead of the latest	latest

Environment variables:

Variable	Description
`GITHUB_TOKEN` / `GH_TOKEN`	Optional GitHub token to raise the API rate limit on CI/shared IPs. Never required for normal use.

Self-update is refused for binaries installed via Homebrew or running inside a container image, for development builds, and when the binary location is not writable. See How to update the CLI.

infrahub-collect

Command structure

infrahub-collect [global-flags] <command> [flags]

Global flags

These flags apply to all infrahub-collect commands:

Flag	Description	Default	Environment Variable
`--project <name>`	Target specific Docker Compose project	Auto-detect	`INFRAHUB_PROJECT`
`--k8s-namespace <name>`	Target specific Kubernetes namespace	Auto-detect	`INFRAHUB_K8S_NAMESPACE`
`--output-dir <path>`	Directory for bundle files	`./infrahub_bundles`	`INFRAHUB_OUTPUT_DIR`
`--log-format <text\|json>`	Output format for logs	`text`	`INFRAHUB_LOG_FORMAT`
`--help, -h`	Show help for any command	-	-

Collect commands

create

Collects a troubleshooting bundle from the Infrahub instance. Collection is read-only: no container or pod is stopped, restarted, or scaled. Individual collector failures are recorded in the bundle manifest and do not abort the run.

Syntax:

infrahub-collect create [flags]

Flags:

Flag	Description	Default	Environment Variable
`--log-lines <n>`	Maximum log lines collected per container	`100000`	`INFRAHUB_LOG_LINES`
`--include-backup`	Also create a backup using the standard backup behavior	`false`	`INFRAHUB_INCLUDE_BACKUP`
`--include-queries`	Include database query logs (may contain customer data)	`false`	`INFRAHUB_INCLUDE_QUERIES`
`--benchmark`	Run the OpsMill benchmark and include its results (requires image download; skipped with a warning if unavailable)	`false`	`INFRAHUB_BENCHMARK`

Examples:

# Basic collection
infrahub-collect create

# Target a specific Kubernetes namespace
infrahub-collect create --k8s-namespace=infrahub-prod

# Collect with more log history
infrahub-collect create --log-lines=500000

# Collect logs and a backup in one run
infrahub-collect create --include-backup

# Performance investigation with benchmark
infrahub-collect create --benchmark

Output:

A single archive named support_bundle_<timestamp>.tar.gz in the output directory. Inside the archive, all files live under a top-level bundle/ directory, with a bundle_information.json manifest recording an explicit outcome for every collector.

Collectors:

Collector	What it gathers
Service logs	Container logs for every Infrahub service, all replicas, plus previous-container logs for restarted pods
Database logs	Neo4j server logs (`neo4j.log`, `debug.log`); full log directory with `--include-queries`
Message-queue status	RabbitMQ queues, exchanges, bindings, connections, channels, and status
Cache status	Redis info, client list, configuration, slow log, and database size
Task-worker state	Prefect worker status, one directory per replica
Task-manager state	Work pools, work queues, recent flow runs, events, and automations
Server info	Versions, installed packages, API information/configuration/schema, masked environment variables
Container metrics	Resource usage via `docker compose stats` or `kubectl top`
Backup (opt-in)	Backup produced by the standard backup behavior (`--include-backup`)
Benchmark (opt-in)	OpsMill benchmark results (`--benchmark`)

Environment and utility commands

infrahub-collect provides the same environment detect, environment list, version, and update commands as infrahub-backup, with identical behavior. See update for the self-update flags and refusal cases.

Configuration precedence

Configuration values are resolved in this order:

Command-line flags (highest priority)
Environment variables
Default values (lowest priority)

infrahub-backup​

Command structure​

Global flags​

Backup commands​

create​

restore​

Environment commands​

environment detect​

environment list​

Utility commands​

version​

update​

infrahub-collect​

Command structure​

Global flags​

Collect commands​

create​

Environment and utility commands​

Configuration precedence​

Related documentation​

infrahub-backup

Command structure

Global flags

Backup commands

create

restore

Environment commands

environment detect

environment list

Utility commands

version

update

infrahub-collect

Command structure

Global flags

Collect commands

create

Environment and utility commands

Configuration precedence

Related documentation