trellis-cli
A command-line interface (CLI) to manage Trellis projects via the trellis
command. It includes:
- Smart autocompletion (based on your defined environments and sites)
- Automatic Virtualenv integration for easier dependency management
- Easy DigitalOcean droplet creation
- Better Ansible Vault support for encrypting files
Sponsors
trellis-cli is an open source project and completely free to use.
However, the amount of effort needed to maintain and develop new features and products within the Roots ecosystem is not sustainable without proper financial backing. If you have the capability, please consider sponsoring Roots.
Quick Install (macOS and Linux via Homebrew)
brew install roots/tap/trellis-cli
Quick Install (Unstable - macOS and Linux 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
Script
We also offer a quick script version:
# You might need sudo before bash
curl -sL https://roots.io/trellis/cli/get | bash
# Turns on debug logging
curl -sL https://roots.io/trellis/cli/get | bash -s -- -d
# 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.
- Download the latest release or any specific version
- Unpack it (
tar -zxvf trellis_1.0.0_Linux_x86_64.tar.gz
) - Find the
trellis
binary in the unpacked directory, and move it to its desired destination (mv trellis_1.0.0_Darwin_x86_64/trellis /usr/local/bin/trellis
) - Make sure the above path is in your
$PATH
Windows Install
For windows you also need to setup environment variables to perfectly work with windows terminal
- Open system properties
- Open environment variables
- Under system variables add new variable,
TRELLIS
, pointing to the location of thetrellis.exe
file, likeC:\trellis_1.0.0
- Edit path from system variables and add new named
%TRELLIS%
- Save the changes
Shell Integration
Autocompletes
Homebrew installs trellis-cli's shell completion automatically by default. If shell completions aren't working, or you installed manually not using Homebrew, you'll need to install the completions manually.
To use the trellis-cli's autocomplete via Homebrew's shell completion:
-
Follow Homebrew's install instructions https://docs.brew.sh/Shell-Completion
Note: For zsh, as the instructions mention, be sure compinit is autoloaded and called, either explicitly or via a framework like oh-my-zsh.
-
Then run:
brew reinstall trellis-cli
To install shell completions manually, run the following:
trellis --autocomplete-install
It should modify your .bash_profile
, .zshrc
or similar.
Virtualenv
trellis-cli uses Virtualenv to manage dependencies such as Ansible which it automatically activates and uses when running any trellis
command.
But there's still a lot of times you may want to run ansible-playbook
or pip
manually in your shell. To make this experience seamless, trellis-cli
offers shell integration which automatically activates the Virtualenv when you enter a Trellis project, and deactivates when you leave it.
To enable this integration, add the following to your shell profile:
Bash (~/.bash_profile
):
eval "$(trellis shell-init bash)"
Zsh (~/.zshrc
):
eval "$(trellis shell-init zsh)"
Usage
Run trellis
for the complete usage and help.
Supported commands so far:
Command | Description |
---|---|
alias |
Generate WP CLI aliases for remote environments |
check |
Checks if Trellis requirements are met |
db |
Commands for database management |
deploy |
Deploys a site to the specified environment |
dotenv |
Template .env files to local system |
down |
Stops the Vagrant machine by running vagrant halt |
droplet |
Commands for DigitalOcean Droplets |
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 |
new |
Creates a new Trellis project |
provision |
Provisions the specified environment |
rollback |
Rollsback the last deploy of the site on the specified environment |
ssh |
Connects to host via SSH |
up |
Starts and provisions the Vagrant environment by running vagrant up |
valet |
Commands for Laravel Valet |
vault |
Commands for Ansible Vault |
Development
trellis-cli requires Go >= 1.18 (brew install go
on macOS)
# Clone the repo
git clone https://github.com/roots/trellis-cli
cd trellis-cli
# Build the binary for your machine
go build
# Run tests (without integration tests)
go test -v -short ./...
# (Optional) Build the docker image for testing (requires `docker`)
make docker
# Alternatively, do not use cache when building the doccker image (requires `docker`)
make docker-no-cache
# Run all tests (requires `docker`)
make test
Releasing Docker Images
This section only intended for the maintainers
make docker-no-cache
# docker tag rootsdev/trellis-cli-dev:latest rootsdev/trellis-cli-dev:YYYY.MM.DD.N
# where N is a sequential integer, starting from 1.
docker tag rootsdev/trellis-cli-dev:latest rootsdev/trellis-cli-dev:2019.08.12.1
# docker push rootsdev/trellis-cli-dev:YYYY.MM.DD.N
docker push rootsdev/trellis-cli-dev:2019.08.12.1
docker push rootsdev/trellis-cli-dev:latest
Contributing
Contributions are welcome from everyone. We have contributing guidelines to help you get started.
Community
Keep track of development and community news.
- Join us on Discord by sponsoring us on GitHub
- Participate on the Roots Discourse
- Follow @rootswp on Twitter
- Read and subscribe to the Roots Blog
- Subscribe to the Roots Newsletter