Skip to content
Roots
  • Home page

WP Packages is our new WPackagist replacement that's 17x faster and updates every 5 minutes

Trellis

Roots and WP Packages are independent open source projects, supported only by developers like you. We’ve been improving the WordPress developer experience since 2011, and your support keeps it independent.

Support Roots

Trellis CLI Command-Line Interface

View as Markdown:

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) 

$ brew install roots/tap/trellis-cli

Script

We also offer a quick script version:

$ 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 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 via Homebrew) 

$ brew uninstall roots/tap/trellis-cli

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

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

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:

$ TRELLIS_ASK_VAULT_PASS=true trellis provision production

Last updated

Help us improve this page.

Contributors

swalkinshaw
Acorn Bedrock Sage Trellis

Getting Started

The Basics

Security

Digging Deeper

Troubleshooting

Extensions

Guides