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

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)

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*"

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