Using the CLI

Search…

Using the CLI

Here, we'll describe at a high level the common day-to-day usage of the Garden CLI, with specific examples.
CLI introduction
The garden CLI is how you work with Garden in most scenarios, during development and in CI pipelines. It features a fairly large number of commands, so we'll list the most common ones below. You can run garden --help to list them, and use garden <command> --help to learn more about individual commands, arguments, option flags, usage examples etc. You can also find a full reference here.
If you've not installed the CLI yet, please check out the installation guide.
Most of the examples below assume that you've already defined a Garden project.
The garden dev command, as well as the build, deploy and test commands (when run with the --watch flag) all start a web dashboard that you can open in a browser. See the dashboard section for more on that.
It is currently not advisable to run multiple dev, build, deploy or test commands in parallel, especially with --watch because they may interfere with each other. It is fine, however, to run one of those and then run other commands to the side, such as garden logs. We plan on improving this in the future.
Common option flags
Every Garden command supports a common set of option flags. The full reference can be found here, but here are the most important ones:
--env sets the environment (and optionally namespace) that the command should act on. Most Garden commands only act on a specific environment, so in most cases you'll specify this, unless you're working on the default environment for the project. See here for more about environments and namespaces.
--log-level / -l sets the log level. Use e.g. -l=debug to get debug logs for the command.
--logger-type=basic disables the fancy log output (with spinners etc.) and just prints a simple line-by-line output. Setting GARDEN_LOGGER_TYPE=basic does the same thing. You should set that environment variable in CI and other automated environments.
--output / -o sets the output format. Use this to get structured output from the commands. --output=json outputs JSON, and --output=yaml outputs YAML. The structure of the outputs is documented in the reference for most commands.
All option flags can be specified with a space or a = between the flag and the value.
Services
Deploying all services in a project
This deploys all your services to the default environment and namespace.
1
garden deploy
Copied!
Deploying all services in a project to a non-default environment and namespace
This deploys your services to my-namespace in the dev environment.
1
garden deploy --env my-namespace.dev
Copied!
Deploying a single service
1
garden deploy my-service
Copied!
Deploying more than one specific service
When arguments accept one or more services, modules etc. we comma-separate the names.
1
garden deploy service-a,service-b
Copied!
Deploying a service and watching for changes
1
garden deploy my-service --watch  # or -w for short
Copied!
Deploying a service in hot-reload mode
See the Hot reload guide for more information on how to configure and use hot reloading for rapid iteration on services. Enabling --hot-reload implicitly sets --watch=true.
1
garden deploy my-service --hot-reload=*  # or --hot for short
Copied!
Running a single ad-hoc service and attaching
1
garden run service my-service --interactive  # or -i for short
Copied!
Executing a command in a running service container
1
garden exec my-service <command>
Copied!
Executing an interactive shell in a running service container
Note: This assumes that sh is available in the container.
1
garden exec my-service -i sh
Copied!
Getting the status of your services
1
garden get status
Copied!
Getting the status of your services in JSON format
This is suitable for parsing with e.g. the jq utility.
1
garden get status --output=json  # or `-o json` for short
Copied!
Stopping all running services
This removes all running services in my-namespace in the dev environment.
1
garden delete env --env=my-namespace.dev
Copied!
Stopping a single running service
1
garden delete service my-service
Copied!
Tests
Running all tests in a project
1
garden test
Copied!
Running all tests for a specific module, and watching for changes
1
garden test my-module --watch
Copied!
Running a specific test for a module, and watching for changes
This runs the integ test, defined in my-module, and watches for changes (including changes in modules and services that the test depends on).
1
garden test my-module --name integ -w
Copied!
Running a specific test and attaching
This is handy for running a single test and streaming the log outputs (garden test, in comparison, is more meant to run multiple ones or watch for changes, and is less suitable for getting log output).
1
garden run test my-module my-test -i
Copied!
Tasks
Running a specific task
1
garden run task my-task
Copied!
Building
Building all modules
1
garden build
Copied!
Building all modules, forcing a rebuild
1
garden build --force  # or -f for short
Copied!
Building a specific module
1
garden build my-module
Copied!
Building a specific module, and wathcing for changes
1
garden build my-module -w
Copied!
This will start a dashboard as well.
Workflows
Running a workflow
Runs my-workflow in my-namespace in the dev environment.
1
garden run workflow my-workflow --env=my-namespace.dev
Copied!
Logs
Retrieving the latest logs for all services
1
garden logs
Copied!
Retrieving the latest logs for a service
1
garden logs my-service
Copied!
Stream logs for a service
1
garden logs my-service --follow  # or -f for short
Copied!
garden dev
The garden dev command builds, deploys and tests all parts of your project, and also runs any tasks that are listed as dependencies for your services and tests. It then waits for any code changes, and automatically re-builds, re-deploys and re-runs any parts affected by your code changes.
This is handy for small projects, and when your code changes don't tend to trigger a lot of heavy operations, but may be too "busy" to run for large projects or when you're making big changes to your code.
Running garden dev
1
garden dev
Copied!
Running garden dev but skipping tests
1
garden dev --skip-tests
Copied!
Running garden dev with hot reloading enabled for all supported services
See the Hot reload guide for more information on how to configure and use hot reloading for rapid iteration on services.
1
garden dev --hot-reload=*
Copied!
Running garden dev with hot reloading enabled for a specific service
1
garden dev --hot-reload=my-service
Copied!
The dashboard
The garden dev command, as well as the build, deploy and test commands when run with the --watch flag all start a web dashboard that you can open in a browser. See the dashboard section for more on that.
The CLI will print a URL which you can copy or click (or Cmd/Ctrl-click, depending on your terminal). The dashboard stays open while the command is running.
The Stack Graph, shown in the Garden dashboard
The dashboard gives you:
An overview of all the parts of your project, including links to any configured ingresses on your services.
A visualization of your Stack Graph, where you can see the status of each node, and click them to get the most recent status or logs.
A log viewer, which you can use to fetch the latest logs for your services.
Hot reloading
For rapid iteration on a running service, you can use an advanced feature called hot reloading. See the Hot reload guide for details on how to configure and use that feature.
Project outputs
​Project outputs are a handy way to extract generated values from your project.
Printing project outputs
1
garden get outputs
Copied!
Getting project outputs in JSON format
This you can use to parse in scripts, e.g. using jq.
1
garden get outputs --output=json  # or `-o json` for short
Copied!
You can also output in YAML with --output=yaml.
Creating new configs
Creating a new project
This bootstraps a boilerplate garden.yml with a project definition in the current directory, and a .gardenignore file.
1
garden create project
Copied!
Creating a module
This bootstraps a boilerplate garden.yml with a module definition in the current directory. You'll get an interactive menu to select a module type. You may get suggestions for appropriate module types, depending on which files are found in the directory (such as a container module when a Dockerfile is found).
1
garden create module
Copied!
Remote sources
Remote sources are a mechanism to connect multiple git repositories in a single Garden project. See the remote sources guide for more information, including how to use the CLI to manage these sources.
Plugin commands
Individual plugins (currently referred to as providers in your project configuration) may include specific commands that help with their usage and operation. The available commands will depend on which providers are configured in your project.
You can run garden plugins without arguments to list the available commands.
Initializing a Kubernetes cluster for in-cluster building
When using a remote Kubernetes cluster and in-cluster building, the cluster needs to be set up with some shared services when you first start using it, when you update the provider configuration, or sometimes when you update to a new Garden version. See the remote kubernetes guide for more information.
Here we initialize the cluster configured for the dev environment:
1
garden plugins kubernetes cluster-init --env=dev
Copied!
Cleaning up the in-cluster builder and registry
When you use in-cluster building, the image caches build up over time and need to be cleaned up periodically. Use this command for that:
1
garden plugins kubernetes cleanup-cluster-registry --env=dev
Copied!
Planning and applying Terraform stacks
The terraform provider includes several commands that facilitate interaction with the Terraform stacks in your project. See the Terraform guide for more information.
Plugin tools
Garden plugins generally define their external tool dependencies, such that Garden can automatically fetch them ahead of use. The garden tools command exposes these tools, so that you can use them without having to install them separately. You can also use these to ensure that you're using the exact same versions as the Garden plugins.
Note that this command currently only works when run within a Garden project root.
If you use this frequently, we recommend defining the following helper function for quick access:
1
# Note: This is made to work in bash and zsh, other shells may need a different syntax
2
function gt() {
3
  garden tools $1 -- "${@:2}"
4
}
Copied!
You can then type e.g. gt docker build . to run docker build . using the Garden-provided version of the docker CLI.
Run garden tools to get a full list of available tools, and garden tools --help for more usage information.
Running a plugin tool
Note that the -- is necessary to distinguish between Garden options, and kubectl arguments. See above for a shorthand function you can put in your shell profile.
1
garden tools kubectl -- <args>
Copied!
Getting the path of a plugin tool
This prints the absolute path to the kubectl binary defined by the kubernetes provider, downloading it first if necessary.
1
garden tools kubectl --get-path
Copied!
Next Steps
Take a look at our Guides section for in-depth guides on specific use cases and setups, or keep exploring other sections under Using Garden to learn more about Garden concepts and configuration.