Trellis CLI

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 DigitalOcean droplet creation
• Better Ansible Vault support for encrypting files
• (New) Built-in virtual machine support for development environments

and much more.

# Installation

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

brew install roots/tap/trellis-cli

# Script

We also offer a quick script version:

# You might need sudo before bash
curl -sL https://roots.io/trellis/cli/get | bash

# Sets bindir or installation directory, Defaults to '/usr/local/bin'
curl -sL https://roots.io/trellis/cli/get | bash -s -- -b /path/to/my/bin

# 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 or any specific version
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, WSL via Homebrew)

# Cleanup previous versions (if installed)
brew uninstall roots/tap/trellis-cli

# Install
brew install --HEAD roots/tap/trellis-cli-dev

# Upgrade
brew upgrade --fetch-HEAD roots/tap/trellis-cli-dev

# Windows Install

trellis-cli does offer a native Windows exe but we recommend you use WSL for Trellis. The above install methods will work for WSL as well.

If you do want to use the native Windows exe, you'll need to do the following setup after downloading the Windows build:

1. Open system properties
2. Open environment variables
3. Under system variables add new variable, TRELLIS, pointing to the location of the trellis.exe file, like C:\trellis_1.0.0
4. Edit path from system variables and add new named %TRELLIS%
5. Save the changes

# Usage

Run trellis for the complete usage and help.

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

# Commands

# 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:

vm

images

Example config:

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

Example env var usage:

TRELLIS_ASK_VAULT_PASS=true trellis provision production