Expand the CLI documentation.
The pyinfra is an extremely powerful tool for ad-hoc execution and management of remote servers.
-## Command Execution
+
+## CLI arguments & options
+
+As described in the [getting started page](./getting_started), pyinfra needs an **inventory** and some **operatons**. These are used with the CLI as below:
+
+```sh
+Usage: pyinfra [OPTIONS] INVENTORY OPERATIONS...
+
+# INVENTORY
+
++ a file (inventory.py)
++ hostname (host.net)
++ Comma separated hostnames: host-1.net,host-2.net,@local
+
+# OPERATIONS
+
+# Run one or more deploys against the inventory
+pyinfra INVENTORY deploy_web.py [deploy_db.py]...
+
+# 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]...
+```
+
+### Options
+
+```sh
+Options:
+ -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:
@@ -13,7 +68,7 @@ pyinfra inventory.py exec -- my_command_goes_here --some-argument
Note:
Anything on the right hand side of the ``--`` will be passed into the target
-### Debugging distributed services using pyinfra
+#### Example: debugging distributed services using pyinfra
One of pyinfra's top design features is its ability to return remote command output in realtime. This can be used to debug N remote services, and is perfect for debugging distributed services.
@@ -23,10 +78,22 @@ For example - a large Elasticsearch cluster. It can be useful to stream the log
pyinfra inventory.py exec --sudo -- tail -f /var/log/elasticsearch/elasticsearch.log
```
-## Operations
+### 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:
+
+```sh
+pyinfra inventory.py apt.packages nginx sudo=true
+```
+
+#### Example: managing services with ad-hoc pyinfra commands
-In addition to executing simple commands, pyinfra can execute any of it's builtin operations on remote hosts direct via the CLI. For example here we ensure that `htop` is installed on the remote servers:
+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:
```sh
-pyinfra inventory.py apt.packages htop sudo=true
+pyinfra inventory.py init.service nginx running=true enabled=true
```
