For the complete documentation index, see llms.txt. This page is also available as Markdown.

Secret reference syntax

A secret reference is the address of one field of an entry. It starts with devo:// and says where the secret is, never what it is. Every devo secret command, launch manifests, .env files and templates use the same syntax.

To get the reference of a field without typing it, run devo entry references <entry>. See Find the reference to a secret.

Named references

A named reference uses the names of the workspace, the vault, and the entry, so it's easy to read:

devo://<workspace>/<vault>/<entry>/<field>
devo://<workspace>/<vault>/<entry>/<section>/<field>
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.

Canonical references

A canonical reference uses IDs instead of names:

devo://ws/<workspace-id>/vault/<vault-id>/entry/<entry-id>/field/<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://<workspace>/<vault>/<entry>/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 '<value>'." 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.

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://<workspace>/${VAULT:-Staging}/<entry>/password }} reads from the vault named in VAULT, or from Staging.

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.

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.

<vault-id> is optional: it sets the default vault, and each secret can still name its own vault.

Last updated

Was this helpful?