infrahubctl Commands

Complete reference for all infrahubctl CLI commands

The infrahubctl command is the main entry point for interacting with Infrahub from the command line. It provides access to database management, server control, development utilities, and system maintenance.

Command Overview

infrahubctl [OPTIONS] COMMAND [ARGS]...

Global Options

Option	Description
--help	Show help message and exit

Top-Level Commands

shell

Start a Python interactive shell within Infrahub context.

infrahubctl shell

Requirements: IPython must be installed.

Available Objects in Shell:

• db - InfrahubDatabase instance
• Branch - Branch class
• NodeManager - NodeManager class for querying nodes
• registry - Global registry instance
• service - InfrahubServices instance

Example Session:

infrahubctl shell

--------------------------------------
infrahub interactive shell initialized
--------------------------------------
Available objects:
* db: InfrahubDatabase
* Branch: Branch
* NodeManager: NodeManager
* registry: Registry
* service: InfrahubServices

Example use:
In [1] tags = await NodeManager.query(schema='BuiltinTag', db=db)

In [1]: tags = await NodeManager.query(schema='BuiltinTag', db=db)
In [2]: len(tags)
Out[2]: 5

upgrade

Upgrade Infrahub to the latest version by running migrations and updating schemas.

infrahubctl upgrade [OPTIONS] [CONFIG_FILE]

Arguments:

Argument	Description	Default
CONFIG_FILE	Path to configuration file	infrahub.toml

Options:

Option	Description	Default
--check	Check upgrade status without applying	False
--rebase-branches	Rebase and migrate branches after upgrade	False
--interactive	Prompt to accept/deny rebase of each branch	False

Environment Variables:

• INFRAHUB_CONFIG - Configuration file path

Examples:

Check what would be upgraded:

infrahubctl upgrade --check

Checking current state of the database
Database up-to-date (v10), no migration to execute.
Core Schema Up to date, nothing to update

Perform full upgrade with branch rebasing:

infrahubctl upgrade --rebase-branches

Checking current state of the database
Database needs to be updated (v10 -> v11), 1 migrations pending
Migration: 011_update_relationship_schema ✅
Core Schema has diff, will need to be updated
The Core Schema has been updated
Found 2 branches that need to be rebased
Planning rebase and migrations for 2 branches: feature-1, feature-2
Rebasing branch 'feature-1' (ID: 123e4567-e89b-12d3-a456-426614174000)... ✅
Rebasing branch 'feature-2' (ID: 123e4567-e89b-12d3-a456-426614174001)... ✅

Interactive branch rebase:

infrahubctl upgrade --rebase-branches --interactive

Found 2 branches that need to be rebased
Rebase branch feature-1? [y/N]: y
Rebase branch feature-2? [y/N]: n
Planning rebase and migrations for 1 branch: feature-1

What it Does:

1. Detects and runs pending graph migrations
2. Updates the core schema to the latest version
3. Upgrades internal objects (menu, permissions)
4. Sets up Prefect task manager components
5. Optionally rebases branches that need migration

Command Groups

server

Control the Infrahub API server. See Server Commands for details.

infrahubctl server [COMMAND]

db

Manage the graph database. See Database Commands for details.

infrahubctl db [COMMAND]

dev

Internal development commands for schema export and database initialization.

infrahubctl dev [COMMAND]

dev export-graphql-schema

Export the Core GraphQL schema to a file.

infrahubctl dev export-graphql-schema [OPTIONS]

Options:

Option	Description	Default
--config-file	Configuration file path	infrahub.toml
--out	Output file path	schema.graphql

Example:

infrahubctl dev export-graphql-schema --out /tmp/schema.graphql

This generates a sorted GraphQL schema file from the internal and core schemas.

dev export-json-schema

Export the REST API OpenAPI schema to a file.

infrahubctl dev export-json-schema [OPTIONS]

Options:

Option	Description	Default
--out	Output file path	openapi.json

Example:

infrahubctl dev export-json-schema --out api-spec.json

{
  "openapi": "3.1.0",
  "info": {
    "title": "Infrahub API",
    "version": "latest"
  },
  "paths": {
    ...
  }
}

dev export-node-schema

Export the repository configuration schema to a file.

infrahubctl dev export-node-schema [OPTIONS]

Options:

Option	Description	Default
--config-file	Configuration file path	infrahub.toml
--out	Output file path	develop.json

Example:

infrahubctl dev export-node-schema --out schema/node-schema.json

Generates a JSON schema file titled “InfrahubSchema” for repository configurations.

dev db-init

Erase the database and initialize it with the core schema.

infrahubctl dev db-init [OPTIONS] [CONFIG_FILE]

Arguments:

Argument	Description	Default
CONFIG_FILE	Path to configuration file	infrahub.toml

Options:

Option	Description
--config-file	Configuration file path

Example:

infrahubctl dev db-init

Delete All Nodes
Initializing database with core schema...

Warning: This command deletes ALL data in the database. Use only in development.

dev load-test-data

Load test data into the database from the test_data directory.

infrahubctl dev load-test-data [OPTIONS] [CONFIG_FILE]

Arguments:

Argument	Description	Default
CONFIG_FILE	Path to configuration file	infrahub.toml
--dataset	Dataset name to load	dataset01

Options:

Option	Description
--config-file	Configuration file path

Example:

infrahubctl dev load-test-data --dataset dataset02

Loading test data from infrahub.test_data.dataset02...
Created 50 nodes
Created 120 relationships

events

(Hidden) Interact with the events system.

infrahubctl events [COMMAND]

events listen

Listen to events in the message bus and print them.

infrahubctl events listen [OPTIONS] [TOPIC]

Arguments:

Argument	Description	Default
TOPIC	Routing key pattern to match	# (all events)
CONFIG_FILE	Path to configuration file	infrahub.toml

Example:

infrahubctl events listen "branch.*"

Waiting for events matching the topic `branch.*`. To exit press CTRL+C
{'routing_key': 'branch.create', 'message': {'branch': 'feature-1', 'timestamp': '2024-03-02T10:15:23Z'}}
{'routing_key': 'branch.merge', 'message': {'branch': 'feature-1', 'timestamp': '2024-03-02T10:20:45Z'}}

tasks

(Hidden) Manage Prefect task manager.

infrahubctl tasks [COMMAND]

tasks init

Initialize the Prefect task manager.

infrahubctl tasks init [OPTIONS] [CONFIG_FILE]

Arguments:

Argument	Description	Default
CONFIG_FILE	Path to configuration file	infrahub.toml

Options:

Option	Description	Default
--debug	Enable debug logging	False

Example:

infrahubctl tasks init

tasks execute

Execute a test workflow in the task manager.

infrahubctl tasks execute [OPTIONS] [CONFIG_FILE]

Arguments:

Argument	Description	Default
CONFIG_FILE	Path to configuration file	infrahub.toml

Options:

Option	Description	Default
--debug	Enable debug logging	False

Example:

infrahubctl tasks execute

{'firstname': 'John', 'lastname': 'Doe'}

tasks flush flow-runs

Delete old Prefect flow runs.

infrahubctl tasks flush flow-runs [OPTIONS] [CONFIG_FILE]

Arguments:

Argument	Description	Default
CONFIG_FILE	Path to configuration file	infrahub.toml

Options:

Option	Description	Default
--days-to-keep	Number of days of flow runs to keep	30
--batch-size	Number of runs to delete per batch	100

Example:

infrahubctl tasks flush flow-runs --days-to-keep 7

Deleting flow runs older than 7 days...
Deleted 450 flow runs

tasks flush stale-runs

Delete stale (stuck in RUNNING state) Prefect flow runs.

infrahubctl tasks flush stale-runs [OPTIONS] [CONFIG_FILE]

Arguments:

Argument	Description	Default
CONFIG_FILE	Path to configuration file	infrahub.toml

Options:

Option	Description	Default
--days-to-keep	Age threshold for stale runs	2
--batch-size	Number of runs to process per batch	100

Example:

infrahubctl tasks flush stale-runs

Processing stale flow runs older than 2 days...
Found 5 stale runs

git-agent

(Hidden) Control the Git Agent service.

infrahubctl git-agent [COMMAND]

git-agent start

Start the Infrahub Git Agent.

infrahubctl git-agent start [OPTIONS] [PORT]

Arguments:

Argument	Description	Default
PORT	Metrics endpoint port	8000

Options:

Option	Description	Default
--debug	Enable debug logging	False
--config-file	Configuration file path	infrahub.toml

Environment Variables:

• INFRAHUB_CONFIG - Configuration file path
• INFRAHUB_METRICS_PORT - Metrics endpoint port

Example:

infrahubctl git-agent start --debug --config-file /etc/infrahub/config.toml 9090

infrahub.database | DEBUG | Connecting to database
Initializing Git Agent ...
Initialized Git Agent ...
Starting metrics server on port 9090

The Git Agent manages Git repository synchronization and handles repository-related events.

See Also

• Database Commands - Complete database command reference
• Server Commands - Server control commands
• CLI Overview - Introduction and common usage patterns