# Trellis CLI Command-Line Interface

trellis-cli is a command-line interface (CLI) to manage Trellis projects via the `trellis` command. The CLI provides a more consistent and integrated experience and includes:

* Automatic Python Virtualenv integration for easier dependency management
* Smart autocompletion (based on your defined environments and sites)
* One-command cloud server creation (DigitalOcean, Hetzner Cloud)
* Better Ansible Vault support for encrypting files
* (New) Built-in virtual machine support for development environments

and much more.

## Installation

### Quick Install (macOS, Linux via Homebrew)

```shell
$ brew install roots/tap/trellis-cli
```

### Script

We also offer a quick script version:

```shell
$ curl -sL https://roots.io/trellis/cli/get | bash
```

### Manual Install

trellis-cli provides binary releases for a variety of OSes. These binary versions can be manually downloaded and installed.

1. Download the [latest release](https://github.com/roots/trellis-cli/releases/latest) or any [specific version](https://github.com/roots/trellis-cli/releases)
2. Unpack it (eg: `tar -zxvf trellis_1.2.1_Linux_x86_64.tar.gz`)
3. Find the `trellis` binary in the unpacked directory, and move it to its desired destination (eg: `mv trellis_1.2.0_Darwin_x86_64/trellis /usr/local/bin/trellis`)
4. Make sure the above path is in your `$PATH`

### Dev/unstable install (macOS, Linux via Homebrew)

```shell
$ brew uninstall roots/tap/trellis-cli
```

```shell
$ brew install --HEAD roots/tap/trellis-cli-dev
```

```shell
$ brew upgrade --fetch-HEAD roots/tap/trellis-cli-dev
```

## Usage

Run `trellis` for the complete usage and help.

For subcommand documentation, run `trellis <command> -h`.

### Commands

| Command | Description |
| --- | --- |
| `alias` | Generate WP CLI aliases for remote environments |
| `check` | Checks if the required and optional Trellis dependencies are installed |
| `db` | Commands for database management |
| `deploy` | Deploys a site to the specified environment |
| `dotenv` | Template .env files to local system |
| `server` | Commands for cloud server management (DigitalOcean, Hetzner Cloud) |
| `exec` | Exec runs a command in the Trellis virtualenv |
| `galaxy` | Commands for Ansible Galaxy |
| `info` | Displays information about this Trellis project |
| `init` | Initializes an existing Trellis project |
| `key` | Commands for managing SSH keys |
| `logs` | Tails the Nginx log files for an environment |
| `new` | Creates a new Trellis project |
| `open` | Opens user-defined URLs (and more) which can act as shortcuts/bookmarks specific to your Trellis projects |
| `provision` | Provisions the specified environment |
| `rollback` | Rollback the last deploy of the site on the specified environment |
| `shell-init` | Prints a script which can be eval'd to set up Trellis' virtualenv integration in various shells |
| `ssh` | Connects to host via SSH |
| `valet` | Commands for Laravel Valet |
| `vault` | Commands for Ansible Vault |
| `vm` | Commands for managing development virtual machines |
| `xdebug-tunnel` | Commands for managing Xdebug tunnels |

## Configuration
There are four ways to set configuration settings for trellis-cli and they are
loaded in this order of precedence:

1. global config (`$HOME/.config/trellis/cli.yml`)
2. project config (`trellis.cli.yml`)
3. project config local override (`trellis.cli.local.yml`)
4. env variables

The global CLI config (defaults to `$HOME/.config/trellis/cli.yml`)
and will be loaded first (if it exists).

Next, if a project is detected, the project CLI config will be loaded if it
exists at `trellis.cli.yml` (within your `trellis` directory).
A Git ignored local override config is also supported at `trellis.cli.local.yml`.

Finally, env variables prefixed with `TRELLIS_` will be used as
overrides if they match a supported configuration setting. The prefix will be
stripped and the rest is lowercased to determine the setting key.

Note: only string, numeric, and boolean values are supported when using environment
variables.

Current supported settings:

| Setting | Description | Type | Default |
| --- | --- | -- | -- |
| `allow_development_deploys` | Whether to allows deploy to the `development` env | boolean | false |
| `ask_vault_pass` | Set Ansible to always ask for the vault pass | boolean | false |
| `check_for_updates` | Whether to check for new versions of trellis-cli | boolean | true |
| `database_app` | Database app to use in `db open` (Options: `tableplus`, `sequel-ace`)| string | none |
| `load_plugins` | Load external CLI plugins | boolean | true |
| `open` | List of name -> URL shortcuts | map[string]string | none |
| `virtualenv_integration` | Enable automated virtualenv integration | boolean | true |
| `server` | Options for cloud server management | Object | see below |
| `vm` | Options for dev virtual machines | Object | see below |

### `server`
| Setting | Description | Type | Default |
| --- | --- | -- | -- |
| `provider` | Cloud provider (Options: `digitalocean`, `hetzner`)| string | `digitalocean` |

### `vm`
| Setting | Description | Type | Default |
| --- | --- | -- | -- |
| `manager` | VM manager (Options: `auto` (depends on OS), `lima`)| string | "auto" |
| `ubuntu` | Ubuntu OS version (Options: `18.04`, `20.04`, `22.04`, `24.04`)| string | `24.04` |
| `hosts_resolver` | VM hosts resolver (Options: `hosts_file`)| string | `hosts_file` |
| `images` | Custom OS image | object | Set based on `ubuntu` version |

#### `images`
| Setting | Description | Type | Default |
| --- | --- | -- | -- |
| `location` | URL of Ubuntu image | string | none |
| `arch` | Architecture of image (eg: `x86_64`, `aarch64`) | string | none |

Example config:

```yaml
ask_vault_pass: false
check_for_updates: true
load_plugins: true
open:
  site: "https://mysite.com"
  admin: "https://mysite.com/wp/wp-admin"
server:
  provider: digitalocean
virtualenv_integration: true
vm:
  manager: auto
  ubuntu: 24.04
```

Example env var usage:
```shell
$ TRELLIS_ASK_VAULT_PASS=true trellis provision production
```