Commands
Below is a list of Garden CLI commands and usage information.
The commands should be run in a Garden project, and are always scoped to that project.
Note: You can get a list of commands in the CLI by running
garden -h/--help
, and detailed help for each command using garden <command> -h/--help
The Outputs sections show the output structure when running the command with
--output yaml
. The same structure is used when --output json
is used and when querying through the REST API, but in JSON format.The following option flags can be used with any of the CLI commands:
Argument | Alias | Type | Description |
---|---|---|---|
--root | | path | Override project root directory (defaults to working directory). Can be absolute or relative to current directory. |
--env | | string | The environment (and optionally namespace) to work against. |
--force-refresh | | boolean | Force refresh of any caches, e.g. cached provider statuses. |
--var | | array:string | Set a specific variable value, using the format <key>=<value>, e.g. `--var some-key=custom-value`. This will override any value set in your project configuration. You can specify multiple variables by separating with a comma, e.g. `--var key-a=foo,key-b="value with quotes"`. |
--yes | | boolean | Automatically approve any yes/no prompts during execution, and allow running protected commands against production environments. |
--silent | | boolean | Suppress log output. Same as setting --logger-type=quiet. |
--logger-type | | quiet default basic json ink | Set logger type. default The default Garden logger, basic [DEPRECATED] Sames as the default Garden logger. This option will be removed in a future release, json same as default, but renders log lines as JSON, quiet suppresses all log output, same as --silent. |
--log-level | | error warn info verbose debug silly 0 1 2 3 4 5 | Set logger level. Values can be either string or numeric and are prioritized from 0 to 5 (highest to lowest) as follows: error: 0, warn: 1, info: 2, verbose: 3, debug: 4, silly: 5. From the verbose log level onward action execution logs are also printed (e.g. test or run live log outputs). |
--output | | json yaml | Output command result in specified format (note: disables progress logging and interactive functionality). |
--emoji | | boolean | Enable emoji in output (defaults to true if the environment supports it). |
--show-timestamps | | boolean | Show timestamps with log output. When enabled, Garden will use the basic logger. I.e., log status changes are rendered as new lines instead of being updated in-place. |
--version | | boolean | Show the current CLI version. |
--help | | boolean | Show help |
Perform your Builds.
Runs all or specified Builds, taking into account build dependency order. Optionally stays running and automatically builds when sources (or dependencies' sources) change.
Examples:
garden build # build everything in the project
garden build my-image # only build my-image
garden build image-a image-b # build image-a and image-b
garden build --force # force re-builds, even if builds had already been performed at current version
garden build -l 3 # build with verbose log level to see the live log output
garden build [names] [options]
Argument | Required | Description |
---|---|---|
names | No | Specify Builds to run. You may specify multiple names, separated by spaces. |
Argument | Alias | Type | Description |
---|---|---|---|
--force | | boolean | Force re-build. |
--with-dependants | | boolean | Also rebuild any Builds that depend on one of the Builds specified as CLI arguments (recursively). Note: This option has no effect unless a list of Build names is specified as CLI arguments (since otherwise, every Build in the project will be performed anyway). |
# Set to true if the command execution was aborted.
aborted:
# Set to false if the command execution was unsuccessful.
success:
# A map of all executed Builds (or Builds scheduled/attempted) and information about the them.
build:
<Build name>:
# The full log from the build.
buildLog:
# Set to true if the build was fetched from a remote registry.
fetched:
# Set to true if the build was performed, false if it was already built, or fetched from a registry
fresh:
# Additional information, specific to the provider.
details:
# Set to true if the action was not attempted, e.g. if a dependency failed.
aborted:
# The duration of the action's execution in msec, if applicable.
durationMsec:
# Whether the action was successfully executed.
success:
# An error message, if the action's execution failed.
error:
# The version of the task's inputs, before any resolution or execution happens. For action tasks, this will
# generally be the unresolved version.
inputVersion:
# Alias for `inputVersion`. The version of the task's inputs, before any resolution or execution happens. For
# action tasks, this will generally be the unresolved version.
version:
# A map of values output from the action's execution.
outputs:
<name>:
<Build name>:
# The full log from the build.
buildLog:
# Set to true if the build was fetched from a remote registry.
fetched:
# Set to true if the build was performed, false if it was already built, or fetched from a registry
fresh:
# Additional information, specific to the provider.
details:
# Set to true if the action was not attempted, e.g. if a dependency failed.
aborted:
# The duration of the action's execution in msec, if applicable.
durationMsec:
# Whether the action was successfully executed.
success:
# An error message, if the action's execution failed.
error:
# The version of the task's inputs, before any resolution or execution happens. For action tasks, this will
# generally be the unresolved version.
inputVersion:
# Alias for `inputVersion`. The version of the task's inputs, before any resolution or execution happens. For
# action tasks, this will generally be the unresolved version.
version:
# A map of values output from the action's execution.
outputs:
<name>:
# A map of all executed Deploys (or Deployments scheduled/attempted) and the Deploy status.
deploy:
<Deploy name>:
# When the service was first deployed by the provider.
createdAt:
# When the service was first deployed by the provider.
updatedAt:
# The mode the action is deployed in.
mode:
# The ID used for the service by the provider (if not the same as the service name).
externalId:
# The provider version of the deployed service (if different from the Garden module version.
externalVersion:
# A list of ports that can be forwarded to from the Garden agent by the provider.
forwardablePorts:
- # A descriptive name for the port. Should correspond to user-configured ports where applicable.
name:
# The preferred local port to use for forwarding.
preferredLocalPort:
# The protocol of the port.
protocol:
# The target name/hostname to forward to (defaults to the service name).
targetName:
# The target port on the service.
targetPort:
# The protocol to use for URLs pointing at the port. This can be any valid URI protocol.
urlProtocol:
# List of currently deployed ingress endpoints for the service.
ingresses:
- # The port number that the service is exposed on internally.
# This defaults to the first specified port for the service.
port:
# The ingress path that should be matched to route to this service.
path:
# The protocol to use for the ingress.
protocol:
# The hostname where the service can be accessed.
hostname:
# Latest status message of the service (if any).
lastMessage:
# Latest error status message of the service (if any).
lastError:
# How many replicas of the service are currently running.
runningReplicas:
# The current deployment status of the service.
state:
# Set to true if the action was not attempted, e.g. if a dependency failed.
aborted:
# The duration of the action's execution in msec, if applicable.
durationMsec:
# Whether the action was successfully executed.
success:
# An error message, if the action's execution failed.
error:
# The version of the task's inputs, before any resolution or execution happens. For action tasks, this will
# generally be the unresolved version.
inputVersion:
# Alias for `inputVersion`. The version of the task's inputs, before any resolution or execution happens. For
# action tasks, this will generally be the unresolved version.
version:
# A map of values output from the action's execution.
outputs:
<name>:
<Deploy name>:
# When the service was first deployed by the provider.
createdAt:
# When the service was first deployed by the provider.
updatedAt:
# The mode the action is deployed in.
mode:
# The ID used for the service by the provider (if not the same as the service name).
externalId:
# The provider version of the deployed service (if different from the Garden module version.
externalVersion:
# A list of ports that can be forwarded to from the Garden agent by the provider.
forwardablePorts:
- # A descriptive name for the port. Should correspond to user-configured ports where applicable.
name:
# The preferred local port to use for forwarding.
preferredLocalPort:
# The protocol of the port.
protocol:
# The target name/hostname to forward to (defaults to the service name).
targetName:
# The target port on the service.
targetPort:
# The protocol to use for URLs pointing at the port. This can be any valid URI protocol.
urlProtocol:
# List of currently deployed ingress endpoints for the service.
ingresses:
- # The port number that the service is exposed on internally.
# This defaults to the first specified port for the service.
port:
# The ingress path that should be matched to route to this service.
path:
# The protocol to use for the ingress.
protocol:
# The hostname where the service can be accessed.
hostname:
# Latest status message of the service (if any).
lastMessage:
# Latest error status message of the service (if any).
lastError:
# How many replicas of the service are currently running.
runningReplicas:
# The current deployment status of the service.
state:
# Set to true if the action was not attempted, e.g. if a dependency failed.
aborted:
# The duration of the action's execution in msec, if applicable.
durationMsec:
# Whether the action was successfully executed.
success:
# An error message, if the action's execution failed.
error:
# The version of the task's inputs, before any resolution or execution happens. For action tasks, this will
# generally be the unresolved version.
inputVersion:
# Alias for `inputVersion`. The version of the task's inputs, before any resolution or execution happens. For
# action tasks, this will generally be the unresolved version.
version:
# A map of values output from the action's execution.
outputs:
<name>:
# A map of all Tests that were executed (or scheduled/attempted) and the Test results.
test:
<Test name>:
# Whether the module was successfully run.
success:
# The exit code of the run (if applicable).
exitCode:
# When the module run was started.
startedAt:
# When the module run was completed.
completedAt:
# The output log from the run.
log:
<Test name>:
# Whether the module was successfully run.
success:
# The exit code of the run (if applicable).
exitCode:
# When the module run was started.
startedAt:
# When the module run was completed.
completedAt:
# The output log from the run.
log:
# A map of all Runs that were executed (or scheduled/attempted) and the Run results.
run:
<Run name>:
# Whether the module was successfully run.
success:
# The exit code of the run (if applicable).
exitCode:
# When the module run was started.
startedAt:
# When the module run was completed.
completedAt:
# The output log from the run.
log:
<Run name>:
# Whether the module was successfully run.
success:
# The exit code of the run (if applicable).
exitCode:
# When the module run was started.
startedAt:
# When the module run was completed.
completedAt:
# The output log from the run.
log:
List secrets defined in Garden Cloud.
List all secrets from Garden Cloud. Optionally filter on environment, user IDs, or secret names.
Examples: garden cloud secrets list # list all secrets garden cloud secrets list --filter-envs dev # list all secrets from the dev environment garden cloud secrets list --filter-envs dev --filter-names DB # list all secrets from the dev environment that have 'DB' in their name.
garden cloud secrets list [options]
Argument | Alias | Type | Description |
---|---|---|---|
--filter-envs | | array:string | Filter on environment. You may filter on multiple environments by setting this flag multiple times. Accepts glob patterns." |
--filter-user-ids | | array:string | Filter on user ID. You may filter on multiple user IDs by setting this flag multiple times. Accepts glob patterns. |
--filter-names | | array:string | Filter on secret name. You may filter on multiple secret names by setting this flag multiple times. Accepts glob patterns. |
Create secrets in Garden Cloud.
Create secrets in Garden Cloud. You can create project wide secrets or optionally scope them to an environment, or an environment and a user.
To scope secrets to a user, you will need the user's ID which you can get from the
garden cloud users list
command.You can optionally read the secrets from a file.
Examples: garden cloud secrets create DB_PASSWORD=my-pwd ACCESS_KEY=my-key # create two secrets garden cloud secrets create ACCESS_KEY=my-key --scope-to-env ci # create a secret and scope it to the ci environment garden cloud secrets create ACCESS_KEY=my-key --scope-to-env ci --scope-to-user 9 # create a secret and scope it to the ci environment and user with ID 9 garden cloud secrets create --from-file /path/to/secrets.txt # create secrets from the key value pairs in the secrets.txt file
garden cloud secrets create [secrets] [options]
Argument | Required | Description |
---|---|---|
secrets | No | The names and values of the secrets to create, separated by '='. You may specify multiple secret name/value pairs, separated by spaces. Note that you can also leave this empty and have Garden read the secrets from file. |
Argument | Alias | Type | Description |
---|---|---|---|
--scope-to-user-id | | number | Scope the secret to a user with the given ID. User scoped secrets must be scoped to an environment as well. |
--scope-to-env | | string | Scope the secret to an environment. Note that this does not default to the environment that the command runs in (i.e. the one set via the --env flag) and that you need to set this explicitly if you want to create an environment scoped secret. |
--from-file | | path | Read the secrets from the file at the given path. The file should have standard "dotenv" format, as defined by dotenv. |
Delete secrets from Garden Cloud.
Delete secrets in Garden Cloud. You will need the IDs of the secrets you want to delete, which you which you can get from the
garden cloud secrets list
command.Examples: garden cloud secrets delete <ID 1> <ID 2> <ID 3> # delete three secrets with the given IDs.
garden cloud secrets delete [ids]
Argument | Required | Description |
---|---|---|
ids | No | The ID(s) of the secrets to delete. |
List users defined in Garden Cloud.
List all users from Garden Cloud. Optionally filter on group names or user names.
Examples: garden cloud users list # list all users garden cloud users list --filter-names Gordon* # list all the Gordons in Garden Cloud. Useful if you have a lot of Gordons. garden cloud users list --filter-groups devs-* # list all users in groups that with names that start with 'dev-'
garden cloud users list [options]
Argument | Alias | Type | Description |
---|---|---|---|
--filter-names | | array:string | Filter on user name. You may filter on multiple names by setting this flag multiple times. Accepts glob patterns. |
--filter-groups | | array:string | Filter on the groups the user belongs to. You may filter on multiple groups by setting this flag multiple times. Accepts glob patterns. |
Create users in Garden Cloud.
Create users in Garden Cloud and optionally add the users to specific groups. You can get the group IDs from the
garden cloud users list
command.To create a user, you'll need their GitHub or GitLab username, depending on which one is your VCS provider, and the name they should have in Garden Cloud. Note that it must the their GitHub/GitLab username, not their email, as people can have several emails tied to their GitHub/GitLab accounts.
You can optionally read the users from a file. The file must have the format vcs-username="Actual Username". For example:
fatema_m="Fatema M" gordon99="Gordon G"
Examples: garden cloud users create fatema_m="Fatema M" gordon99="Gordon G" # create two users garden cloud users create fatema_m="Fatema M" --add-to-groups 1,2 # create a user and add two groups with IDs 1,2 garden cloud users create --from-file /path/to/users.txt # create users from the key value pairs in the users.txt file
garden cloud users create [users] [options]
Argument | Required | Description |
---|---|---|
users | No | The VCS usernames and the names of the users to create, separated by '='. You may specify multiple VCS username/name pairs, separated by spaces. Note that you can also leave this empty and have Garden read the users from file. |
Argument | Alias | Type | Description |
---|---|---|---|
--add-to-groups | | array:string | Add the user to the group with the given ID. You may add the user to multiple groups by setting this flag multiple times. |
--from-file | | path | Read the users from the file at the given path. The file should have standard "dotenv" format (as defined by dotenv) where the VCS username is the key and the name is the value. |
Delete users from Garden Cloud.
Delete users in Garden Cloud. You will need the IDs of the users you want to delete, which you which you can get from the
garden cloud users list
command. Use a comma- separated list to delete multiple users.Examples: garden cloud users delete <ID 1> <ID 2> <ID 3> # delete three users with the given IDs.
garden cloud users delete [ids]
Argument | Required | Description |
---|---|---|
ids | No | The IDs of the users to delete. |
List groups defined in Garden Cloud.
List all groups from Garden Cloud. This is useful for getting the group IDs when creating users via the
garden cloud users create
command.Examples: garden cloud groups list # list all groups garden cloud groups list --filter-names dev-* # list all groups that start with 'dev-'
garden cloud groups list [options]
Argument | Alias | Type | Description |
---|---|---|---|
--filter-names | | array:string | Filter on group name. You may filter on multiple names by setting this flag multiple times. Accepts glob patterns. |
Join our community Discord to chat with us!
Opens the Garden Community Discord invite link
garden community
Update your preferences regarding analytics.
To help us make Garden better, we collect some analytics data about its usage. We make sure all the data collected is anonymized and stripped of sensitive information. We collect data about which commands are run, what tasks they trigger, which API calls are made to your local Garden server, as well as some info about the environment in which Garden runs.
You will be asked if you want to opt out when running Garden for the first time and you can use this command to update your preferences later.
Examples:
garden config analytics-enabled true # enable analytics
garden config analytics-enabled false # disable analytics
garden config analytics-enabled [enable]
Argument | Required | Description |
---|---|---|
enable | No | Enable analytics. Defaults to "true" |
Create a new Garden project.
Creates a new Garden project configuration. The generated config includes some default values, as well as the schema of the config in the form of commented-out fields. Also creates a default (blank) .gardenignore file in the same path.
Examples:
garden create project # create a Garden project config in the current directory
garden create project --dir some-dir # create a Garden project config in the ./some-dir directory
garden create project --name my-project # set the project name to my-project
garden create project --interactive=false # don't prompt for user inputs when creating the config
garden create project [options]
Argument | Alias | Type | Description |
---|---|---|---|
--dir | | path | Directory to place the project in (defaults to current directory). |
--filename | | string | Filename to place the project config in (defaults to project.garden.yml). |
--interactive | | boolean | Set to false to disable interactive prompts. |
--name | | string | Name of the project (defaults to current directory name). |
Deletes a running namespace.
This will clean up everything deployed in the specified environment, and trigger providers to clear up any other resources and reset it. When you then run
garden deploy
after, the namespace will be reconfigured.This can be useful if you find the namespace to be in an inconsistent state, or need/want to free up resources.
garden cleanup namespace [options]
Argument | Alias | Type | Description |
---|---|---|---|
--dependants-first | | boolean | Clean up Deploy(s) (or services if using modules) in reverse dependency order. That is, if service-a has a dependency on service-b, service-a will be deleted before service-b when calling `garden cleanup namespace service-a,service-b --dependants-first`. |
When this flag is not used, all services in the project are cleaned up simultaneously.
# The status of each provider in the namespace.
providerStatuses:
# Description of an environment's status for a provider.
<name>:
# Set to true if the environment is fully configured for a provider.
ready:
# Use this to include additional information that is specific to the provider.
detail:
# Output variables that modules and other variables can reference.
outputs:
<name>:
# Set to true to disable caching of the status.
disableCache:
# The status of each deployment in the namespace.
deployStatuses:
<name>:
# The state of the action.
state:
# Structured outputs from the execution, as defined by individual action/module types, to be made available for
# dependencies and in templating.
outputs:
<name>:
# Set to true if the action handler is running a process persistently and attached to the Garden process after
# returning.
attached:
detail:
# When the service was first deployed by the provider.
createdAt:
# Additional detail, specific to the provider.
detail:
# The mode the action is deployed in.
mode:
# The ID used for the service by the provider (if not the same as the service name).
externalId:
# The provider version of the deployed service (if different from the Garden module version.
externalVersion:
# A list of ports that can be forwarded to from the Garden agent by the provider.
forwardablePorts:
- # A descriptive name for the port. Should correspond to user-configured ports where applicable.
name:
# The preferred local port to use for forwarding.
preferredLocalPort:
# The protocol of the port.
protocol:
# The target name/hostname to forward to (defaults to the service name).
targetName:
# The target port on the service.
targetPort:
# The protocol to use for URLs pointing at the port. This can be any valid URI protocol.
urlProtocol:
# List of currently deployed ingress endpoints for the service.
ingresses:
- # The port number that the service is exposed on internally.
# This defaults to the first specified port for the service.
port:
# The ingress path that should be matched to route to this service.
path:
# The protocol to use for the ingress.
protocol:
# The hostname where the service can be accessed.
hostname:
# Latest status message of the service (if any).
lastMessage:
# Latest error status message of the service (if any).
lastError:
# A map of values output from the deployment.
outputs:
<name>:
# How many replicas of the service are currently running.
runningReplicas:
# The current deployment status of the service.
state:
# When the service was last updated by the provider.
updatedAt:
# The Garden module version of the deployed service.
version:
Cleans up running deployments (or services if using modules).
Cleans up (i.e. un-deploys) the specified actions. Cleans up all deploys/services in the project if no arguments are provided. Note that this command does not take into account any deploys depending on the cleaned up actions, and might therefore leave the project in an unstable state. Running
garden deploy
after will re-deploy anything missing.Examples:
garden cleanup deploy my-service # deletes my-service
garden cleanup deploy # deletes all deployed services in the project
garden cleanup deploy [names] [options]
Argument | Required | Description |
---|---|---|
names | No | The name(s) of the deploy(s) (or services if using modules) to delete. You may specify multiple names, separated by spaces. |
Argument | Alias | Type | Description |
---|---|---|---|
--dependants-first | | boolean | Clean up Deploy(s) (or services if using modules) in reverse dependency order. That is, if service-a has a dependency on service-b, service-a will be deleted before service-b when calling `garden cleanup namespace service-a,service-b --dependants-first`. |
When this flag is not used, all services in the project are cleaned up simultaneously. |
--with-dependants
| | boolean | Also clean up deployments/services that have dependencies on one of the deployments/services specified as CLI arguments (recursively). When used, this option implies --dependants-first. Note: This option has no effect unless a list of names is specified as CLI arguments (since then, every deploy/service in the project will be deleted).<name>:
# The state of the action.
state:
# Structured outputs from the execution, as defined by individual action/module types, to be made available for
# dependencies and in templating.
outputs:
<name>:
# Set to true if the action handler is running a process persistently and attached to the Garden process after
# returning.
attached:
detail:
# When the service was first deployed by the provider.
createdAt:
# Additional detail, specific to the provider.
detail:
# The mode the action is deployed in.
mode:
# The ID used for the service by the provider (if not the same as the service name).
externalId:
# The provider version of the deployed service (if different from the Garden module version.
externalVersion:
# A list of ports that can be forwarded to from the Garden agent by the provider.
forwardablePorts:
- # A descriptive name for the port. Should correspond to user-configured ports where applicable.
name:
# The preferred local port to use for forwarding.
preferredLocalPort:
# The protocol of the port.
protocol:
# The target name/hostname to forward to (defaults to the service name).
targetName:
# The target port on the service.
targetPort:
# The protocol to use for URLs pointing at the port. This can be any valid URI protocol.
urlProtocol:
# List of currently deployed ingress endpoints for the service.
ingresses:
- # The port number that the service is exposed on internally.
# This defaults to the first specified port for the service.
port:
# The ingress path that should be matched to route to this service.
path:
# The protocol to use for the ingress.
protocol:
# The hostname where the service can be accessed.
hostname:
# Latest status message of the service (if any).
lastMessage:
# Latest error status message of the service (if any).
lastError:
# A map of values output from the deployment.