> 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/guides/secrets/run-with-secrets.md). # Run a command with its secrets Start a program with secrets from your vault in its environment or standard input, with devo secret run: no value in your shell, files, or terminal. `devo secret run` is the safest way to give a secret to a program. Devolutions CLI reads the values from your vault, puts them in the environment of that one program, starts it, and hides the values in everything it prints. Your shell never holds the value, and nothing is written to disk. ```bash devo secret run --env-ref DB_PASSWORD= -- ``` Everything after `--` is the program and its arguments. To find ``, see [Find the reference to a secret](/cli/guides/secrets/find-a-reference.md). ## Pick the right way to pass references
CHOOSEWHAT HAPPENSUSE IT WHEN
--env-ref NAME=<reference>Sets the environment variable NAME to the value. Repeat the option for each secret.You launch a command by hand or from a script.
A variable that already holds a referenceAny environment variable of your shell whose value is a devo:// reference is replaced by the value for the program.Your shell profile or CI pipeline already sets variables such as DB_PASSWORD=devo://….
--env-file <file>Reads KEY=value lines and resolves the references they contain.Your project already has a .env file. See Take the passwords out of a .env file.
--stdin-reference <reference>Writes the value, exactly, to the standard input of the program, then closes it.The program reads a password from standard input, like docker login --password-stdin.
--manifest <file>Reads the command, its arguments, and its references from a JSON file.You want one launch file to review and reuse, for example for an AI agent.
## Pass several secrets Repeat `--env-ref` for each variable. Names use letters, digits, and underscores, and can't start with a digit. {% tabs %} {% tab title="Bash" %} ```bash devo secret run \ --env-ref DB_USER= \ --env-ref DB_PASSWORD= \ -- ./migrate.sh ``` {% endtab %} {% tab title="PowerShell" %} ```powershell devo secret run ` --env-ref DB_USER= ` --env-ref DB_PASSWORD= ` -- pwsh -NoProfile -File ./migrate.ps1 ``` {% endtab %} {% endtabs %} The program receives the rest of your environment as usual. Each variable name can be defined only once across all sources: if the same name comes from `--env-ref` and from a variable of your shell that holds a reference, the command stops with a conflict instead of choosing for you. ## Use the references already in your environment If a variable of your current shell holds a `devo://` reference, `devo secret run` resolves it for the program without any option: ```bash export DB_PASSWORD='' devo secret run -- ./migrate.sh ``` The variable in your shell keeps the reference. Only the program sees the value. This doesn't apply with `--manifest`, where the manifest lists every reference: with a manifest, such a variable reaches the program as the plain reference text, not the value. ## Send a secret to standard input ```bash devo secret run --stdin-reference -- docker login --username --password-stdin ``` Devolutions CLI writes the value with no trailing newline, then closes the standard input of the program. ## Keep references out of the command line Devolutions CLI refuses an argument of the program that is a reference, like `-- psql --password devo://…`. References are resolved only through `--env-ref`, `--stdin-reference`, an environment file, or a manifest. A reference inside a longer argument, like `--password=devo://…`, isn't refused but isn't resolved either: the program receives the reference text. ## Check before you run Two options let you test a launch without starting the program:
OPTIONWHAT IT CHECKS
--dry-runBuilds the launch plan and shows a summary: the command, the number of references, the timeout, and whether masking is on. With --output json, the plan lists each variable with its reference. It doesn't contact your workspace and doesn't look for the program.
--checkAlso makes sure the program exists in the current folder or on your PATH, and runs a value-free read of each reference. That confirms the syntax and, for a named reference or on a local profile, the vault and the entry. It doesn't prove the field can be read: on Devolutions Cloud and Devolutions Server, a canonical reference isn't looked up. References from an environment file are checked as written, before ${NAME} is replaced.
You can use one or the other, not both. Both accept `--output json`. ## Limit how long the program runs ```bash devo secret run --timeout-seconds 300 --env-ref API_TOKEN= -- ./deploy.sh ``` When the time is up, Devolutions CLI stops the program and everything it started, and exits with code `124`. If you cancel with Ctrl+C, it stops the program and exits with `130`. Otherwise, `devo secret run` exits with the exit code of your program. ## Keep a record of the launch Add `--receipt-file ` to write a JSON receipt after the program ends: the launch plan, the variable names, the exit code, the duration, and whether the program timed out or was cancelled. The receipt contains no secret value. The file must not exist yet. Devolutions CLI creates it with private permissions: on macOS and Linux, only your user account can read it; on Windows, your account, the system account, and administrators. {% hint style="warning" %} If the receipt can't be written, `devo secret run` exits with code `1`, even if your program succeeded. {% endhint %} ## Use a launch manifest A manifest is a JSON file that describes the whole launch. With `--manifest`, you can't add `--env-ref`, `--env-file`, `--stdin-reference`, `--timeout-seconds`, or a command after `--`. ```json { "schemaVersion": 1, "command": "./deploy.sh", "arguments": ["--target", "staging"], "environment": { "API_TOKEN": "" }, "stdinReference": "", "timeoutSeconds": 300, "workingDirectory": "" } ``` ```bash devo secret run --manifest launch.json ``` * `command` is required. `schemaVersion` is optional; if you set it, it must be `1`. The other properties are optional. * Each value in `environment` must be a single `devo://` reference. * `workingDirectory` must be an absolute path to a folder that exists. * A property or a variable name can't appear twice. ## About masking Devolutions CLI watches what the program prints on its standard output and standard error, and replaces each resolved value with ``. If a tool needs to print a value, for example to pipe it to another program, add `--no-masking`. {% hint style="warning" %} Masking protects what the program prints, not what it does. A program that receives a secret can still write it to a file or send it over the network. Only run programs you trust with your secrets. See [What stays hidden, and what doesn't](/cli/guides/understand/security-model.md). {% endhint %} ## Good to know * References resolve through the current context. Add `--context ` to use another workspace for one command. Canonical references always resolve against the workspace that owns them. * An invalid launch, such as a malformed `--env-ref`, exits with code `2` before anything is read. See [Exit codes and errors](/cli/reference/exit-codes-and-errors.md). * A reference that doesn't resolve stops the launch before the program starts. See [A secret reference doesn't resolve](/cli/help/troubleshooting/reference-does-not-resolve.md). ## Next * [Give an agent a credential without exposing it](/cli/guides/ai-agents/run-an-agent.md) * [Take the passwords out of a .env file](/cli/guides/secrets/replace-env-files.md) * Every option of `devo secret run`: [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/guides/secrets/run-with-secrets.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.