/ ```

SEGMENT	WHAT IT IS
`<workspace>`	The workspace that holds the vault.
`<vault>`	The vault that holds the entry.
`<entry>`	The entry that holds the field.
`<section>`	Optional, local profile only. The section of the entry that holds the field, when the field is in a section. Devolutions Cloud and Devolutions Server refuse a section with `unsupportedSecretField`.
`<field>`	The field to read, such as `password`, `username`, `domain`, `host`, `otp`, or `privatekey`.

A named reference is resolved in the workspace selected for the command: the current context, or the one you choose with `--context` or `--source`. See [Global options](/cli/reference/global-options.md). ## Canonical references A canonical reference uses IDs instead of names: ``` devo://ws//vault//entry//field/ ``` * It keeps working when the entry, the vault, or the workspace is renamed. * It names the workspace that owns it, so it's resolved in that workspace whatever the current context is. One `devo secret run` can mix references from a local profile, Devolutions Cloud, and Devolutions Server. * It has no section segment. * On Devolutions Server, `devo entry references` lists canonical references only. A named reference that you write yourself still works. ## Attributes By default, a reference returns the value of the field. Add `?attribute=` (or the short form `?attr=`) to read information about the field instead of its value. Values aren't case-sensitive.

ATTRIBUTE	WHAT IT RETURNS	SECRET
`value`	The value of the field. This is the default, and the only attribute that returns a secret.	Yes
`type`	The kind of field.	No
`id`	The ID of the entry.	No
`title`	The name of the entry. Empty for a canonical reference on Devolutions Cloud and Devolutions Server.	No
`purpose`	Why the value was requested: `read`, `inject`, `run`, or `mcp`. Empty on a local profile.	No

`type`, `id`, `title`, and `purpose` return information only, never the secret, on every workspace type. For example, `devo://///password?attribute=type` returns the kind of the `password` field, not the password. `devo secret read` and `devo secret get` also accept `--attribute` instead of the query. ## Special characters Each segment between two `/` is URL-decoded. If a name contains `/`, `?`, `#`, `%`, or a space, encode it: for example, write `Web%2FProd` for an entry named `Web/Prod`, and `My%20vault` for `My vault`. A `:` can stay as is. References that Devolutions CLI prints, for example with `devo entry references`, are already encoded. ## Rules and errors When a reference can't be read, the command fails with the error code `invalidSecretReference` and one of these messages.

MESSAGE	WHAT TO CHECK
"Secret reference cannot be empty."	The reference is empty or only spaces.
"Secret reference must start with 'devo://'."	The prefix is missing or misspelled. The prefix isn't case-sensitive.
"Secret references do not support URI fragments."	The reference contains `#`. Encode it as `%23` if it's part of a name.
"Secret reference path cannot be empty."	Nothing follows `devo://`.
"Use devo://<workspace>/<vault>/<entry>/<field> or devo://<workspace>/<vault>/<entry>/<section>/<field>."	A named reference needs 4 or 5 segments. Check for a missing segment or an unencoded `/` in a name.
"Secret reference path segments cannot be empty."	Two `/` follow each other, or the reference ends with `/`.
"Canonical ID references must use devo://ws/<id>/vault/<id>/entry/<id>/field/<field>."	A reference that starts with `ws` and has 8 segments must use the words `vault`, `entry`, and `field` in that order.
"Canonical workspace, vault, and entry identifiers cannot be empty."	An ID is missing in a canonical reference.
"Canonical field segment cannot be empty."	The field is missing at the end of a canonical reference.

An unknown attribute fails with the code `unsupportedSecretAttribute` and the message "Unsupported secret reference attribute '\'." Other query parameters are ignored. When the reference is valid but doesn't lead to a field you can read, see [A secret reference doesn't resolve](/cli/help/troubleshooting/reference-does-not-resolve.md). ## References inside a text `devo secret inject` finds the references in a template and replaces each one with its value. It recognizes two forms:

FORM	WHERE IT ENDS
`{{ devo://… }}`	At the closing `}}`. The braces are replaced too, and spaces inside them are ignored. Use this form when the reference is next to other text.
`devo://…`	At the first space, line break, `"`, `'`, `<`, `>`, `)`, `]`, or `}`.

Text that starts with `devo://` but isn't a valid reference is left as is. In a template, a reference can also contain environment variables, which `devo secret inject` replaces before it reads the secret:

EXPRESSION	WHAT IT BECOMES
`$NAME` or `${NAME}`	The value of the environment variable `NAME`. If it's not set or empty, the command fails with `missingSecretReferenceVariable`.
`${NAME:-default}`	The value of `NAME`, or `default` when it's not set or empty.

For example, `{{ devo:///${VAULT:-Staging}//password }}` reads from the vault named in `VAULT`, or from `Staging`. {% hint style="warning" %} `devo secret inject` writes the values in plain text to its output. See [Fill a configuration file from a template](/cli/guides/secrets/fill-a-template.md). {% endhint %} ## SecretSpec provider URIs SecretSpec doesn't use secret references. In `secretspec.toml`, it uses a provider URI that tells it which workspace Devolutions CLI should read. Print the right one with `devo secretspec uri`. See [Use Devolutions CLI with SecretSpec](/cli/guides/secrets/secretspec.md).

PROVIDER URI	WORKSPACE
`devo://cloud[/<vault-id>][?context=<name>]`	Devolutions Cloud, through the context `<name>`, or the current Devolutions Cloud context without `?context=`.
`devo://server[/<vault-id>][?context=<name>]`	Devolutions Server, through the context `<name>`, or the current Devolutions Server context without `?context=`.
`devo://sqlite[/<vault-id>]?workspace=<workspace-id>`	A local Devolutions Remote Desktop Manager workspace. `?workspace=` is required, with a workspace ID such as `sqlite:Connections.db`. `devo workspace current` shows it.

`` is optional: it sets the default vault, and each secret can still name its own vault. --- # 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/reference/secret-references.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.