Using the CLI

pyinfra is an extremely powerful tool for ad-hoc execution and management of remote servers.

CLI arguments & options

As described in the getting started page, pyinfra needs an inventory and some operations. These are used with the CLI as below:



+ a file (
+ hostname (
+ Comma separated hostnames:,,@local


# Run one or more deploys against the inventory
pyinfra INVENTORY []...

# Run a single operation against the inventory
pyinfra INVENTORY server.user pyinfra home=/home/pyinfra

# Execute an arbitrary command on the inventory
pyinfra INVENTORY exec -- echo "hello world"

# Run one or more facts on the inventory
pyinfra INVENTORY fact linux_distribution [users]...
pyinfra INVENTORY all-facts

# Debug (print) inventory hosts, groups and data
pyinfra INVENTORY debug-inventory


  -v                      Print std[out|err] from operations/facts.
  --user TEXT             SSH user to connect as.
  --port INTEGER          SSH port to connect to.
  --key PATH              Private key filename.
  --key-password TEXT     Privte key password.
  --password TEXT         SSH password.
  --sudo                  Whether to execute operations with sudo.
  --sudo-user TEXT        Which user to sudo when sudoing.
  --su-user TEXT          Which user to su to.
  --parallel INTEGER      Number of operations to run in parallel.
  --fail-percent INTEGER  % of hosts allowed to fail.
  --dry                   Don't execute operations on the target hosts.
  --limit TEXT            Restrict the target hosts by name and group name.
  --no-wait               Don't wait between operations for hosts to complete.
  --serial                Run operations in serial, host by host.
  --facts                 Print available facts list and exit.
  --operations            Print available operations list and exit.
  --version               Show the version and exit.
  --help                  Show this message and exit.

Ad-hoc command execution

pyinfra can execute shell commands on remote hosts by using pyinfra exec. For example:

pyinfra exec -- my_command_goes_here --some-argument

Note: Anything on the right hand side of the -- will be passed into the target

Example: debugging distributed services using pyinfra

One of pyinfra’s top design features is its ability to return remote command output in real-time. This can be used to debug N remote services, and is perfect for debugging distributed services.

For example - a large Elasticsearch cluster. It can be useful to stream the log of every instance in parallel, which can be achieved easily like so:

pyinfra exec --sudo -- tail -f /var/log/elasticsearch/elasticsearch.log

Executing ad-hoc operations

In addition to executing simple commands, pyinfra can execute any of it’s builtin operations on remote hosts direct via the CLI.

Example: managing packages with ad-hoc pyinfra commands

For example, here we ensure that nginx is installed on the remote servers:

# Ubuntu example
pyinfra apt.packages nginx sudo=true update=true

# Centos example
pyinfra yum.packages nginx sudo=true

Example: managing services with ad-hoc pyinfra commands

Now that nginx is installed on the box, we can use pyinfra to control the nginx service - here we ensure it’s running and enabled to start on system boot:

pyinfra init.service nginx running=true enabled=true

Example: rebooting with ad-hoc pyinfra commands

We can reboot instances a couple of ways using adhoc commands (assuming sudo is enabled in

# using server.reboot()
pyinfra service.reboot reboot_timeout=0 delay=0

# using exec
pyinfra exec -- reboot

Additional debug info

For additional debug info, use one of these options:

  • --debug Print debug info.

  • --debug-facts Print facts after generating operations and exit.

  • --debug-operations Print operations after generating and exit.

Shell Autocompletion

Add the following to your ~/.bash_profile or ~/.profile files:

  • bash source scripts/

  • zsh source scripts/pyinfra-complete.zsh.

These files were generated using these commands:

env _PYINFRA_COMPLETE=source pyinfra >
env _PYINFRA_COMPLETE=source_zsh pyinfra > pyinfra-complete.zsh