Introducing Garden Custom Commands

Jon Edvald

March 19, 2022

We’ve added Custom Commands to Garden, to give our users more control and to simplify day-to-day usage of Garden projects. You can now define your own commands in your projects, and run them in the same way that you run the default Garden commands.

You can think of them as a more powerful version of npm package scripts or Makefile targets, with the full capability of Garden's templating engine, and seamless integration with the Garden CLI.

A quick example

Imagine a group of developers. For their day-to-day work, they routinely update a git submodule, and then run a garden deploy --dev command with some extra arguments. Sometimes they forget to update the submodule first, or they spend time looking in their history for the correct deploy arguments.

With custom commands, you can define a project level .yaml file with kind: Command. These commands can be run just like any other Garden commands (in this example, garden api-dev).

Each custom command can include an exec block where you can run any system commands and a gardenCommand block where you can chain other Garden commands.

You can find detailed documentation on how to use custom commands in our documentation.

Some magic: Syntactic sugar for custom commands

One of our favorite parts about using custom commands is the syntax we have to easily use groups of shell arguments. Specifically, you can use:

${args.$all} - all arguments and options passed to garden.
${args.$rest} - all arguments and options that are not explicitly defined in the custom command.
${args["--"]} - to split off a specific group of commands. So for garden my-command -- foo --bar you would get an array containing foo and --bar.

Basically, you get all the power of the Garden templating you’re used to, wrapped up in the simplicity of short and intuitive commands.

You can also go beyond passing any and all arguments to the wrapped scripts and commands. Custom commands allow you to explicitly define your own arguments and/or custom option flags. You can easily template them into your wrapped scripts or Garden commands. These are validated when running the command, and also appear in help texts for the command, ultimately making your team's day-to-day even easier.

Once again, you can find more detailed examples in the docs.

What can you use custom commands for?

Pretty much anything! Internally we have found them useful in all kinds of situations, as they are super simple to run, but also very flexible and powerful to build. Here are some cases where you might find custom commands most useful:

Short codes: Instead of having to remember or document a long Garden command that your entire team uses, you can add a custom command and your entire team can have access to it by running a one-word, memorable command. Internally, we tend to run some commands in running containers when developing. For example we use garden exec to run a shell in the API service by calling garden exec api sh. Maybe not everyone in the team even knows that this is possible, but by wrapping it in a custom command with a friendlier name, you can allow your whole team to use more powerful tools. And beyond running a shell, you might have other commands that you frequently run in deployed containers, such as tests and other scripts. You can now easily codify those as custom commands.
Custom scripts: Many teams have shell scripts that wrap Garden commands. This works fine, but requires context switching between running a local script and running garden. Now you can wrap your scripts in custom commands for better consistency.
Recommended settings: Instead of recommending to your team which arguments and flags to run Garden with, you can wrap all your recommended settings into a custom command. And your team isn’t limited by this, as you can use the ${args.$all} shortcut as in the example above to allow them to add their own options to the preset defaults.
Tests, database migrations, and more: If you have tasks you regularly run, such as database migrations or tests, you can wrap these in custom commands but keep all of the power of Garden templating and arg parsing to ensure that developers are not limited by the defaults.

Because custom commands are treated like standard Garden commands, you can see them listed with a simple garden --help. They will appear after the built-in commands. You can also run garden <my-custom-command> --help to see how an individual command is used.

Feedback or requests?

Let us know what you are using custom commands for, and if you run into any limitations! We do still consider the API experimental so it's certainly open for improvement, and we are actively looking for feedback to improve them. But don't hesitate to adopt custom commands—we promise any improvements will be backwards compatible! By all means tell us what you think by opening a GitHub issue, or a discussion in our community forum.