Skip to main content

​
Command Modes

pyinfra supports five primary command modes, each designed for different use cases.

​
Deploy Files

Execute one or more Python deploy files containing operations.

​
Syntax

​
Description

Deploy files are Python scripts that define operations to execute on target hosts. All files must have a .py extension. pyinfra will load and execute each file in sequence.

​
Examples

Single deploy file:
Multiple deploy files:
With working directory:

​
Behavior

  • Files are executed in the order specified
  • Each file can modify config, which is reset after execution
  • Operations are collected during file execution and run later
  • File paths are resolved relative to the current working directory (or --chdir if specified)

​
Operations

Execute a single operation directly from the command line.

​
Syntax

​
Description

Run a specific operation from the pyinfra operations library. The operation name must contain a dot (e.g., server.user, apt.packages).

​
Examples

Create a user:
Install packages:
Create a file:

​
Argument Formats

Positional arguments:
Keyword arguments:
JSON format:

​
Type Parsing

Arguments are automatically parsed:
  • true, false → Boolean
  • Numbers → Integer or float
  • Strings in quotes → String
  • Bare words → String

​
Exec (Shell Commands)

Execute arbitrary shell commands on target hosts.

​
Syntax

​
Description

Run raw shell commands across all target hosts. The -- separator is required to distinguish the command from pyinfra options.

​
Examples

Simple command:
Check disk space:
Restart service:
Multiple commands:

​
Behavior

  • Output is printed to the console in real-time
  • The command is executed using server.shell operation
  • Exit codes are captured and reported
  • Retries are configured via --retry and --retry-delay options

​
Facts

Gather facts (system information) from target hosts.

​
Syntax

​
Description

Collect facts about the target systems without making changes. Facts provide information about the current state of hosts.

​
Examples

Single fact:
Multiple facts:
Fact with arguments:
Multiple facts with arguments:

​
Common Facts

  • server.LinuxName - Linux distribution name
  • server.Users - List of system users
  • server.Hostname - System hostname
  • server.Os - Operating system type
  • files.File - File information (requires path= argument)
  • files.Directory - Directory information
  • server.Date - System date and time

​
Output

Facts are displayed in a structured format showing:
  • Fact name and arguments
  • Results for each host
  • Any errors encountered

​
Debug Inventory

Inspect and debug inventory configuration.

​
Syntax

​
Description

Display detailed information about the inventory, including:
  • All hosts and their names
  • Host data and variables
  • Group memberships
  • Connection details

​
Examples

Debug inventory file:
Debug with data overrides:
Debug with limit:

​
Output

The command displays:
  • Host count
  • Host names and connection information
  • Data available to each host
  • Group structure

​
Use Cases

  • Verify inventory is loaded correctly
  • Check host data values
  • Debug group assignments
  • Validate data overrides
  • Test limit patterns

​
Command Selection Logic

pyinfra automatically determines the command mode based on the operations argument:
  1. debug-inventory → Debug Inventory mode
  2. fact → Facts mode
  3. exec → Exec mode
  4. All arguments end with .py → Deploy Files mode
  5. First argument contains . → Operations mode
  6. Otherwise → Error (invalid operation)

​
Error Handling

Each command mode has specific error handling:
  • Deploy Files: Missing files cause immediate error
  • Operations: Invalid operation names are caught on import
  • Exec: Command failures are reported but execution continues
  • Facts: Missing facts cause warnings, not failures
  • Debug Inventory: Connection is not required