# Command-line interface

This page documents the details of Fabric’s command-line interface, `fab`.

## Options & arguments

Note

By default, `fab` honors all of the same CLI options as Invoke’s ‘inv’ program; only additions and overrides are listed here!

For example, Fabric implements `--prompt-for-passphrase` and `--prompt-for-login-password` because they are SSH specific, but it inherits a related option – –prompt-for-sudo-password – from Invoke, which handles sudo autoresponse concerns.

-H, --hosts

  Takes a comma-separated string listing hostnames against which tasks should be executed, in serial. See Runtime specification of host lists.

-i, --identity

  Overrides the `key_filename` value in the `connect_kwargs` config setting (which is read by `Connection`, and eventually makes its way into Paramiko; see the docstring for `Connection` for details.)

  Typically this can be thought of as identical to `ssh -i <path>`, i.e. supplying a specific, runtime private key file. Like `ssh -i`, it builds an iterable of strings and may be given multiple times.

  New in version 3.1: this also ends up in the `authentication.identities` configuration value and will be referenced by `fabric.auth.OpenSSHAuthStrategy`, if in use.

  Default: `[]`.

--prompt-for-login-password

  Causes Fabric to prompt ‘up front’ for a value to store as the `connect_kwargs.password` config setting (used by Paramiko when authenticating via passwords and, in some versions, also used for key passphrases.) Useful if you do not want to configure such values in on-disk conf files or via shell environment variables.

--prompt-for-passphrase

  Causes Fabric to prompt ‘up front’ for a value to store as the `connect_kwargs.passphrase` config setting (used by Paramiko to decrypt private key files.) Useful if you do not want to configure such values in on-disk conf files or via shell environment variables.

-S, --ssh-config

  Takes a path to load as a runtime SSH config file. See Loading and using ssh_config files.

-t, --connect-timeout

  Takes an integer of seconds after which connection should time out. Supplies the default value for the `timeouts.connect` config setting.

## Seeking & loading tasks

`fab` follows all the same rules as Invoke’s collection loading, with the sole exception that the default collection name sought is `fabfile` instead of `tasks`. Thus, whenever Invoke’s documentation mentions `tasks` or `tasks.py`, Fabric substitutes `fabfile` / `fabfile.py`.

For example, if your current working directory is `/home/myuser/projects/mywebapp`, running `fab --list` will cause Fabric to look for `/home/myuser/projects/mywebapp/fabfile.py` (or `/home/myuser/projects/mywebapp/fabfile/__init__.py` - Python’s import system treats both the same). If it’s not found there, `/home/myuser/projects/fabfile.py` is sought next; and so forth.

## Runtime specification of host lists

While advanced use cases may need to take matters into their own hands, you can go reasonably far with the core `--hosts` flag, which specifies one or more hosts the given task(s) should execute against.

By default, execution is a serial process: for each task on the command line, run it once for each host given to `--hosts`. Imagine tasks that simply print `Running <task name> on <host>!`:

    $ fab --hosts host1,host2,host3 taskA taskB
    Running taskA on host1!
    Running taskA on host2!
    Running taskA on host3!
    Running taskB on host1!
    Running taskB on host2!
    Running taskB on host3!

Note

When `--hosts` is not given, `fab` behaves similarly to Invoke’s command-line interface, generating regular instances of `Context` instead of `Connections`.

## Executing arbitrary/ad-hoc commands

`fab` leverages a lesser-known command line convention and may be called in the following manner:

    $ fab [options] -- [shell command]

where everything after the `--` is turned into a temporary `Connection.run` call, and is not parsed for `fab` options. If you’ve specified a host list via an earlier task or the core CLI flags, this usage will act like a one-line anonymous task.

For example, let’s say you wanted kernel info for a bunch of systems:

    $ fab -H host1,host2,host3 -- uname -a

Such a command is equivalent to the following Fabric library code:

    from fabric import Group

    Group('host1', 'host2', 'host3').run("uname -a")

Most of the time you will want to just write out the task in your fabfile (anything you use once, you’re likely to use again) but this feature provides a handy, fast way to dash off an SSH-borne command while leveraging predefined connection settings.