Variables

Variable commands enable you to manage variables in your Knock account from the CLI.

Variables are account-wide. A variable has a default value and can have an override for each environment. Variable commands do not take a --branch flag, and knock variable pull and knock variable push read and write the whole variable catalog. Pushing a variable saves it right away, and Knock does not create a commit for it.

Variable commands are separate from knock pull and knock push, which do not include variables.

When variables are pulled from Knock, they are stored together in a single variables.json file. The file is a JSON object where each property name is a variable key. Knock CLI looks for the file in the directory set by your knock.json file or the --knock-dir flag, and falls back to the current working directory.

.knock/
└── variables.json

Each entry describes one variable:

• type. public or secret. The type cannot change after the variable is created.
• description. Optional context about what the variable is for.
• value. The default value. Public variables only.
• environment_values. Optional environment overrides, keyed by environment slug. Public variables only.
• value_set. Whether a secret variable has a default value. Secret variables only.
• environment_values_set. Whether a secret variable has an override in each environment. Secret variables only.

Knock never returns the value of a secret variable, so the CLI never writes one to your local file system. Pulled secret entries record only whether a value is set. To set the value of a secret variable, use knock variable set with --value-stdin or --value-file.

A variable key must start with a letter or underscore and contain only letters, numbers, and underscores. This is the format you use to reference the variable in a template as vars.<key>.

When you push, a null or omitted value is skipped and leaves the existing value unchanged. An empty string clears the value.

Display all variables in your account. By default, the command shows each variable's default value and its environment overrides. Secret values are never shown. The command reports whether a secret value is set or unset.

Use an --environment flag to show only the value that applies in that environment, which is the override when one is set and the default otherwise.

Flags

Display a single variable, including its default value and every environment override. Secret values are never shown.

Flags

Add a new variable entry to your local variables.json file.

The command writes to the variables.json file in the directory set by your knock.json file or the --knock-dir flag, and falls back to the current working directory. If the file does not exist, the command asks you to confirm before creating it. The command exits with an error if the key is already in the file.

The command does not accept --value for a secret variable. After you push the entry, set the secret value with knock variable set.

Flags

Create or update a variable in Knock directly, without editing a local file. Pass --type when creating a variable. When the variable already exists, --type is optional, and it must match the existing type.

You can only pass one of --value, --value-file, --value-stdin, or --unset-value. A value is required to create a variable.

Secret values are never accepted as command-line arguments, because they would end up in your shell history. For a secret variable, pass the value with --value-stdin or --value-file. The same applies to environment overrides: use --environment-value-file rather than --environment-value.

Flags

Pull variables from Knock into your local variables.json file. The command always pulls the whole variable catalog, including every environment override, so it does not take an --environment flag.

Pass a key to update a single entry. If the variable does not exist in Knock, the command offers to remove that entry from your local file. Without a key, the command replaces the whole file, and any entry that no longer exists in Knock is removed.

By default, this command resolves the variables.json file through your knock.json file or the --knock-dir flag. When neither is set, it uses the current working directory.

Note: Knock CLI asks you to confirm before it writes to the local file system, unless you pass --force.

See the Variable file structure section for details on how the file is organized.

Flags

Push variables from your local variables.json file to Knock. Knock updates an existing variable by the matching key, or creates a new variable if it does not exist yet. Pass a key to push a single entry, or omit it to push every entry in the file.

Note:

• Pushing does not delete variables from Knock that are missing from your file.
• A new variable needs a string value. For a secret variable, create it with knock variable set so that you can supply the value without writing it to the file.
• You cannot change the type of an existing variable.
• After a successful push, the command updates your local file to match what Knock stored. For a secret variable, the file records only whether a value is set.
• Variables are saved right away, so this command does not have a --commit flag.

See the Variable file structure section for details on how the file is organized.

Flags

Delete a variable, or clear a single environment override.

Without an --environment flag, the command deletes the variable and every environment override.

With an --environment flag, the command clears only that environment's override and keeps the variable. The default value then applies in that environment.

Flags