Skip to main content
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

OptionDescription
--helpShow 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:
ArgumentDescriptionDefault
CONFIG_FILEPath to configuration fileinfrahub.toml
Options:
OptionDescriptionDefault
--checkCheck upgrade status without applyingFalse
--rebase-branchesRebase and migrate branches after upgradeFalse
--interactivePrompt to accept/deny rebase of each branchFalse
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:
OptionDescriptionDefault
--config-fileConfiguration file pathinfrahub.toml
--outOutput file pathschema.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:
OptionDescriptionDefault
--outOutput file pathopenapi.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:
OptionDescriptionDefault
--config-fileConfiguration file pathinfrahub.toml
--outOutput file pathdevelop.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:
ArgumentDescriptionDefault
CONFIG_FILEPath to configuration fileinfrahub.toml
Options:
OptionDescription
--config-fileConfiguration 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:
ArgumentDescriptionDefault
CONFIG_FILEPath to configuration fileinfrahub.toml
--datasetDataset name to loaddataset01
Options:
OptionDescription
--config-fileConfiguration 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:
ArgumentDescriptionDefault
TOPICRouting key pattern to match# (all events)
CONFIG_FILEPath to configuration fileinfrahub.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:
ArgumentDescriptionDefault
CONFIG_FILEPath to configuration fileinfrahub.toml
Options:
OptionDescriptionDefault
--debugEnable debug loggingFalse
Example: 
infrahubctl tasks init

​
tasks execute

Execute a test workflow in the task manager. 
infrahubctl tasks execute [OPTIONS] [CONFIG_FILE]
Arguments:
ArgumentDescriptionDefault
CONFIG_FILEPath to configuration fileinfrahub.toml
Options:
OptionDescriptionDefault
--debugEnable debug loggingFalse
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:
ArgumentDescriptionDefault
CONFIG_FILEPath to configuration fileinfrahub.toml
Options:
OptionDescriptionDefault
--days-to-keepNumber of days of flow runs to keep30
--batch-sizeNumber of runs to delete per batch100
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:
ArgumentDescriptionDefault
CONFIG_FILEPath to configuration fileinfrahub.toml
Options:
OptionDescriptionDefault
--days-to-keepAge threshold for stale runs2
--batch-sizeNumber of runs to process per batch100
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:
ArgumentDescriptionDefault
PORTMetrics endpoint port8000
Options:
OptionDescriptionDefault
--debugEnable debug loggingFalse
--config-fileConfiguration file pathinfrahub.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

Build docs developers (and LLMs) love

Get started for freeTalk to us