> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/cli/for-devops-and-administrators/manage/custom-variables.md). # Use custom variables List, create, update, delete, and export the custom variables of a local workspace and its vaults with Devolutions CLI, from a terminal or a script. Custom variables are named values stored in your workspace or in one of its vaults. With Devolutions CLI, you can list them, set them from a script, and export them, without opening Devolutions Remote Desktop Manager. {% hint style="info" %} Custom variables work with a local Devolutions Remote Desktop Manager profile only. On Devolutions Cloud and Devolutions Server, these commands say the workspace doesn't support them. See [A command says the workspace doesn't support it](/cli/help/troubleshooting/not-supported.md). {% endhint %} These commands work on the current context. To use another local profile for one command, add `--context `. See [Switch between workspaces](/cli/guides/connect/switch-workspaces.md). ## Pick the right command
CHOOSEWHAT HAPPENSUSE IT WHEN
devo workspace variableLists, sets, or deletes the custom variables of the current workspace.The variable belongs to the whole workspace.
devo vault variableLists, sets, or deletes the custom variables of the current vault, or of the vault you name with --vault.The variable belongs to one vault.
devo variable exportWrites the custom variables of one scope to a JSON file.You want a copy of the variables, for example to review them or keep them with a script.
{% hint style="warning" %} Custom variables aren't secrets. `devo workspace variable list` and `devo vault variable list` show each value in plain text, the JSON output of these commands includes the values, and the exported file contains them. The exception: a variable whose name, or one of whose stored fields, contains `password`, `secret`, `token`, `encrypt`, `protected`, or `safevalue` comes back with an empty value and the status `redacted`. A variable whose value the profile stores in a hidden form comes back empty with the status `unavailable`. Keep passwords and keys in entries, and use them with [devo secret run](/cli/guides/secrets/run-with-secrets.md). {% endhint %} ## List variables ```bash devo workspace variable list devo vault variable list --vault "" ``` The table shows the name, value, scope, source, and description of each variable. To keep only some of them, add a name filter: `*` matches any text and `?` one character, and the case doesn't matter. ```bash devo workspace variable list "API_*" ``` Without `--vault`, `devo vault variable list` uses the current vault. To select the vault by ID, write `--vault id:` or add `--id`. ## Create or update a variable `set` creates the variable if it doesn't exist and updates it otherwise. The value comes from an environment variable (`--value-env`) or a file (`--value-file`), never from the command line, so it doesn't end up in your shell history. Use one of the two, not both. {% tabs %} {% tab title="Bash" %} ```bash export VARIABLE_VALUE='' devo workspace variable set API_REGION --value-env VARIABLE_VALUE --description "" --yes ``` {% endtab %} {% tab title="PowerShell" %} ```powershell $env:VARIABLE_VALUE = '' devo workspace variable set API_REGION --value-env VARIABLE_VALUE --description "" --yes ``` {% endtab %} {% endtabs %} For a vault variable, use `devo vault variable set` with the same options, plus `--vault ""` to pick a vault other than the current one. * **Name**: letters, digits, and underscores only. The `$` delimiters are optional: `API_REGION` and `$API_REGION$` are the same variable. Devolutions CLI saves the name in uppercase, between `$` signs. * **Value from a file**: the whole content of the file becomes the value, as is, including a final line break if the file ends with one. * **Value from a variable**: the environment variable must exist. Devolutions CLI stops if it isn't set. * **Confirmation**: without `--yes` (or `-y`, `--confirmed`), the command changes nothing and returns `confirmationRequired`. ## Delete variables {% hint style="danger" %} Deleting a custom variable can't be undone from Devolutions CLI. Export the variables first if you might need them again. {% endhint %} ```bash devo workspace variable delete API_REGION OLD_ENDPOINT --yes devo vault variable delete API_REGION --vault "" --yes ``` You can name several variables in one command. If one of them doesn't exist, or a name appears twice, the command fails and deletes nothing. Without `--yes`, nothing is deleted. ## Export variables to a file ```bash devo variable export --scope workspace --out-file variables.json devo variable export --scope vault --vault "" --out-file vault-variables.json ```
OPTIONWHAT IT DOES
--scopeRequired. Which variables to export: workspace, vault, user-vault, or option.
--out-fileRequired. The JSON file to write. Its folder must already exist.
--nameKeeps only the variables whose name matches. Accepts * and ?.
--vault, --idFor the vault and user-vault scopes, the vault to export. Without it, the current vault.
--forceReplaces the file if it already exists. Without it, the command stops.
The file lists each variable with its name, value, description, scope, and source. Exporting reads the variables only: it doesn't need `--yes`, and you can export every scope, even the ones you can't change from Devolutions CLI. {% hint style="warning" %} The exported file contains the values in plain text, except the redacted ones, and, unlike the file that `devo secret inject --out-file` writes, Devolutions CLI doesn't make it private. Don't commit it, and delete it when you no longer need it. {% endhint %} ## Good to know * `set` and `delete` change the `workspace` and `vault` scopes only. * Changes need an unencrypted local database. When the profile can't be changed safely, the command explains why and changes nothing. * Add `--output json` to read the result in a script. See [Read results as JSON](/cli/for-devops-and-administrators/automate/json-output.md). * A command refused on your workspace type: see [A command says the workspace doesn't support it](/cli/help/troubleshooting/not-supported.md). ## Next * [Manage vaults and entries](/cli/for-devops-and-administrators/manage/vaults-and-entries.md) * [Compare workspace types](/cli/guides/understand/workspace-types.md) * Every option of these commands: [Commands](/cli/reference/commands.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.devolutions.net/cli/for-devops-and-administrators/manage/custom-variables.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.