buildkite-agent env
The Buildkite Agent's env subcommands provide the ability to inspect environment variables.
With the job-api experiment enabled, jobs can inspect and modify their environment variables using the get, set, and unset sub-commands. These provide an alternative to using shell commands to inspect and modify environment variables. To enable the job-api experiment, include the --experiment=job-api flag when starting the agents.
Printing env
This command is used internally by the agent and isn't recommended for use in your builds.
Usage
buildkite-agent env dump [options]
Description
Prints out the environment of the current process as a JSON object, easily parsable by other programs. Used when executing hooks to discover changes that hooks make to the environment.
Example
$ buildkite-agent env dump --format json-pretty
Options
--format value #
|
Output format; json or json-pretty (default: "json") |
|---|---|
--no-color #
|
Don't show colors in logging |
--debug #
|
Enable debug mode. Synonym for `--log-level debug`. Takes precedence over `--log-level` |
--log-level value #
|
Set the log level for the agent, making logging more or less verbose. Defaults to notice. Allowed values are: debug, info, error, warn, fatal (default: "notice") |
--experiment value #
|
Enable experimental features within the buildkite-agent |
--profile value #
|
Enable a profiling mode, either cpu, memory, mutex or block |
Getting a job's environment variables
Usage
buildkite-agent env get [variables]
Description
Retrieves environment variables and their current values from the current job execution environment.
Note that this subcommand is only available from within the job executor with
the job-api experiment enabled.
Changes to the job environment only apply to the environments of subsequent
phases of the job. However, env get can be used to inspect the changes made
with env set and env unset.
Examples
Getting all variables in key=value format:
$ buildkite-agent env get
ALPACA=Geronimo the Incredible
BUILDKITE=true
LLAMA=Kuzco
...
Getting the value of one variable:
$ buildkite-agent env get LLAMA
Kuzco
Getting multiple specific variables:
$ buildkite-agent env get LLAMA ALPACA
ALPACA=Geronimo the Incredible
LLAMA=Kuzco
Getting variables as a JSON object:
$ buildkite-agent env get --format=json-pretty
{
"ALPACA": "Geronimo the Incredible",
"BUILDKITE": "true",
"LLAMA": "Kuzco",
...
}
Options
--format value #
|
Output format: plain, json, or json-pretty (default: "plain") |
|---|---|
--no-color #
|
Don't show colors in logging |
--debug #
|
Enable debug mode. Synonym for `--log-level debug`. Takes precedence over `--log-level` |
--log-level value #
|
Set the log level for the agent, making logging more or less verbose. Defaults to notice. Allowed values are: debug, info, error, warn, fatal (default: "notice") |
--experiment value #
|
Enable experimental features within the buildkite-agent |
--profile value #
|
Enable a profiling mode, either cpu, memory, mutex or block |
Setting a job's environment variables
Usage
buildkite-agent env set [variable]
Description
Sets environment variables in the current job execution environment. Changes to the job environment variables only apply to subsequent phases of the job. This command cannot unset Buildkite read-only variables.
To read the new values of variables from within the current phase, use env get.
Note that this subcommand is only available from within the job executor with the job-api experiment enabled.
Examples
Setting the variables LLAMA and ALPACA:
$ buildkite-agent env set LLAMA=Kuzco "ALPACA=Geronimo the Incredible"
Added:
+ LLAMA
Updated:
~ ALPACA
Setting the variables LLAMA and ALPACA using a JSON object supplied over standard input:
$ echo '{"ALPACA":"Geronimo the Incredible","LLAMA":"Kuzco"}' | \
buildkite-agent env set --input-format=json --output-format=quiet -
Options
--input-format value #
|
Input format: plain or json (default: "plain") |
|---|---|
--output-format value #
|
Output format: quiet (no output), plain, json, or json-pretty (default: "plain") |
--no-color #
|
Don't show colors in logging |
--debug #
|
Enable debug mode. Synonym for `--log-level debug`. Takes precedence over `--log-level` |
--log-level value #
|
Set the log level for the agent, making logging more or less verbose. Defaults to notice. Allowed values are: debug, info, error, warn, fatal (default: "notice") |
--experiment value #
|
Enable experimental features within the buildkite-agent |
--profile value #
|
Enable a profiling mode, either cpu, memory, mutex or block |
Removing environment variables from a job
Usage
buildkite-agent env unset [variables]
Description
Unsets environment variables in the current job execution environment. Changes to the job environment variables only apply to subsequent phases of the job. This command cannot unset Buildkite read-only variables.
To read the new values of variables from within the current phase, use env get.
Note that this subcommand is only available from within the job executor with the job-api experiment enabled.
Examples
Unsetting the variables LLAMA and ALPACA:
$ buildkite-agent env unset LLAMA ALPACA
Unset:
- ALPACA
- LLAMA
Unsetting the variables LLAMA and ALPACA with a JSON list supplied over standard input
$ echo '["LLAMA","ALPACA"]' | \
buildkite-agent env unset --input-format=json --output-format=quiet -
Options
--input-format value #
|
Input format: plain or json (default: "plain") |
|---|---|
--output-format value #
|
Output format: quiet (no output), plain, json, or json-pretty (default: "plain") |
--no-color #
|
Don't show colors in logging |
--debug #
|
Enable debug mode. Synonym for `--log-level debug`. Takes precedence over `--log-level` |
--log-level value #
|
Set the log level for the agent, making logging more or less verbose. Defaults to notice. Allowed values are: debug, info, error, warn, fatal (default: "notice") |
--experiment value #
|
Enable experimental features within the buildkite-agent |
--profile value #
|
Enable a profiling mode, either cpu, memory, mutex or block |