Configuration reference

Complete reference for configuring the Infrahub Ops CLI tools through environment variables and runtime flags.

Configuration methods

Tools can be configured through these methods, applied in precedence order:

1. Command-line flags (highest priority)
2. Environment variables
3. Default values (lowest priority)

Environment variables

Core configuration

Variable	Description	Default	Example
INFRAHUB_BACKUP_DIR	Directory for storing backup files	./infrahub_backups	/data/backups
INFRAHUB_OUTPUT_DIR	Directory for storing troubleshooting bundles	./infrahub_bundles	/data/bundles
INFRAHUB_LOG_FORMAT	Output format for logs	text	json

Retention configuration

Variable	Description	Default	Example
INFRAHUB_RETENTION_DAYS	Keep backups newer than N days (N >= 1, unset to disable)	unset	30
INFRAHUB_RETENTION_COUNT	Keep the N most recent backups (N >= 1, unset to disable)	unset	60

Both rules combine as a union, and the most recent backup at each location always survives. A value that is not a whole number of at least 1 — including an explicit 0 — is a validation error that aborts the run rather than disabling the rule; a variable that is present but empty counts as unset. See Manage backup retention.

Docker compose configuration

Variable	Description	Default	Example
INFRAHUB_PROJECT	Docker Compose project name	Auto-detect	infrahub-prod

Database configuration

Neo4j

Variable	Description	Default	Example
INFRAHUB_DB_DATABASE	Neo4j database name	neo4j	infrahub
INFRAHUB_DB_USERNAME	Neo4j username	neo4j	admin
INFRAHUB_DB_PASSWORD	Neo4j password	admin	SecurePass123

Task manager PostgreSQL

Variable	Description	Default	Example
PREFECT_API_DATABASE_CONNECTION_URL	PostgreSQL connection string	Auto-detect	postgresql://user:pass@localhost/prefect

Collect configuration

Variable	Description	Default	Example
INFRAHUB_BENCHMARK_IMAGE	Container image used by the opt-in --benchmark run	registry.opsmill.io/opsmill/bench	registry.example.com/opsmill/bench

Command-line flag reference

Global flags

Flag	Environment Override	Description
--backup-dir	INFRAHUB_BACKUP_DIR	Set backup directory
--project	INFRAHUB_PROJECT	Target specific Docker Compose project
--log-format	INFRAHUB_LOG_FORMAT	Set log output format

Backup command flags

Flag	Description
--force	Force backup creation even if tasks are running
--neo4jmetadata	Neo4j metadata to include (all, none, users, roles)
--retention-days	Prune backups older than N days after a successful backup
--retention-count	Keep only the N most recent backups after a successful backup

Collect command flags

Flag	Environment Override	Description
--log-lines	INFRAHUB_LOG_LINES	Maximum log lines collected per container (default 100000)
--include-backup	INFRAHUB_INCLUDE_BACKUP	Also create a backup during collection
--include-queries	INFRAHUB_INCLUDE_QUERIES	Include database query logs in the bundle
--benchmark	INFRAHUB_BENCHMARK	Run the OpsMill benchmark and include its results

Auto-detection behavior

Docker Compose project detection

Order of detection:

1. --project flag
2. INFRAHUB_PROJECT environment variable
3. Search for running Infrahub containers

Detection command:

docker compose ls --filter "name=*infrahub*"

Kubernetes pod detection

For each service, the tool tries these label selectors in order and uses the first one that returns pods:

1. infrahub/service=<service>. The Infrahub Helm chart and the Infrahub high availability deployment example set this label on every component.
2. For the database service only, helm.neo4j.com/pod_category=neo4j-instance, which the Neo4j Helm chart sets on every Neo4j server pod.
3. app.kubernetes.io/component=<service>, then app=<service>, then component=<service>.

If no selector returns pods, the tool uses the pods whose name contains the service name.

Other software in the namespace can set the labels in step 3 to the same values. For example, CloudNativePG labels its PostgreSQL pods app.kubernetes.io/component=database, the same value as the Neo4j service name. Set infrahub/service on the pods of every Infrahub service, so the tool finds them in step 1.

When several pods match and the tool needs one, it uses the pod labelled cnpg.io/instanceRole=primary or role=primary, and otherwise the first pod.

Database credential detection

For Docker Compose deployments:

# Neo4j credentials from environment
docker compose exec database printenv NEO4J_AUTH

# PostgreSQL credentials from environment
docker compose exec task-manager-db printenv POSTGRES_PASSWORD

Troubleshooting configuration

Debug configuration loading

View effective configuration:

infrahub-backup --help

Test configuration

Validate configuration without running operations:

infrahub-backup environment detect

Common issues

Cannot detect environment

# Check Docker
docker compose ls
docker ps

# Check for Infrahub containers
docker ps --filter "name=infrahub"

Authentication failures

# Verify credentials are set
env | grep INFRAHUB
env | grep PREFECT

# Test database connectivity
docker compose exec database cypher-shell -u neo4j

Examples

Minimal configuration

For basic Docker Compose setup:

export INFRAHUB_BACKUP_DIR=/backups
infrahub-backup create

Production configuration

#!/bin/bash
# production-backup.sh

export INFRAHUB_LOG_FORMAT=json
export INFRAHUB_PROJECT=infrahub-production
export INFRAHUB_BACKUP_DIR=/data/backups/infrahub
export INFRAHUB_DB_PASSWORD="${NEO4J_PASSWORD}"

infrahub-backup create --neo4jmetadata=all

Related documentation

• CLI command reference
• Install Infrahub Backup
• Install Infrahub Collect