A CLI Tool For Managing Trellis

Trellis is one of the most powerful elements of the Roots stack: It provides the blueprint and management tools to allow anyone to spin up a fast, secure WordPress server that they control, and offers a zero-downtime atomic deploy system that makes your deploys fast, safe, and reversible.

If there’s a downside to Trellis, it’s that it requires juggling a handful of tools that aren’t always familiar to a web developer–Vagrant, Ansible, Python, VirtualBox (or another VM provider)… There are commands to remember, versions to manage, and more.

Fortunately, we now have a tool to help you manage all of that from a single command and abstract away the tools so you don’t need to worry about them. It’s called trellis-cli, and it’s our officially recommended way of interacting with your Trellis projects.

I say “now”… In fact, trellis-cli has been around for a while, and many of you have already been using it, but as we’ve just released 1.6 it seemed like a good time for a more official announcement to help get the word out.

Installing trellis-cli

If you’re using Homebrew on macOS or Linux, installing is pretty easy:

brew install roots/tap/trellis-cli

You can also install it with a script we provide:

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

For other install methods, see the documentation.

Using trellis-cli

Now that you have it installed, trellis-cli provides a number of tools to help you manage your Trellis project. The full list of commands is available in the docs or by running trellis --help, but here are a couple commands that might interest you–just navigate to the directory of a Trellis project (or someplace where you want to create a new one), and run one of the following commands:

• trellis new — Create a new Trellis project.
• trellis init — Initialize a development environment by setting up virtualenv (for Python version management) and installing dependencies with pip. Anisble and Python version issues are one of the most common Trellis problems, and this command helps wrangle all of that for you.
• trellis up — Start up and provision your Vagrant environment.
• trellis vault — Access to the Trellis’s anisble-vault functionality, to decrypt/encrypt secrets.
• trellis deploy — Deploy your site to any of the environments defined in your configuration.
• trellis rollback — Roll back to a previous deployment.
• trellis valet — Set up your project to use Laravel Valet for local development.
• trellis droplet — Set up and manage a Digital Ocean droplet.
• trellis droplet create — So long as you’ve set up a DigitalOcean personal access token, you can spin up new droplets without leaving the command line for any of your defined environments: It’s as simple as trellis droplet create production (or staging, or development, or client-test, or…you get the idea). For details, see the docs.
• And more…

One of trellis-cli’s usability improvements is a robust autocomplete. In addition to commands and subcommands, it will autocomplete environments for appropriate commands (i.e. deploy) based on what’s defined in your project—like in this example.

Trellis-cli also opens up some incredible possibilities for automation through our setup-trellis-cli& GitHub action—like automated deploys.

If you use Trellis, then you should be using trellis-cli to interact with and manage your Trellis projects. Although the cli doesn’t have its own dedicated docs, we’ve updated the Trellis docs to include examples of usage wherever it’s useful.

Just released is trellis-cli 1.6, which includes the following:

• Fix virtualenv in paths containing spaces (#207)
• Improve the un-initialized warning message (#257)
• Improve check command and bump python req to 3.8 (#261)
• Improve failure modes during new project creation (#263)
• test: use T.TempDir to create temporary test directory by Juneezee& (#264)
• Upgrade to go v1.17 by @TangRufus (#266)
• Use built-in testing.Setenv (#267)
• Update Dockerfile: go 1.17, bullseye, python3 (#269)
• Enable –debug by @evance (#270)
• Fixes #259 – use manual input for known hosts in key generate cmd (#273)
• Remove all ioutil usage (#274)