> 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/find-a-reference.md).

# Find the reference to a secret

Find the devo:// reference of a password or another field with Devolutions CLI, without reading or showing the secret itself.

Every Devolutions CLI command that uses a secret takes a **reference**: the address of one field, starting with `devo://`. Finding a reference never reads the secret, so you can do it anywhere, including in front of an AI agent or in a shared terminal.

## Find the entry

If you don't know the exact name of the entry, search for it first:

```bash
devo entry list "<search-text>" --vault-name "<vault-name>"
```

`devo entry list` returns up to 100 entries by default (`--limit` changes that). You can also filter by entry type with `--type`. To search another workspace than the current one, add `--context <context-name>`. See [Switch between workspaces](/cli/guides/connect/switch-workspaces.md).

## List the references of the entry

```bash
devo entry references "<entry-name>" --vault-name "<vault-name>"
```

To select the entry by ID, write `id:<entry-id>` or add `--id`. `devo secret catalog entry` takes the same arguments and returns the same result.

Devolutions CLI prints one line per field that it can resolve, with the reference to copy:

```
Secret references: 2
password (secret): devo://ws/<workspace-id>/vault/<vault-id>/entry/<entry-id>/field/password
username: devo://ws/<workspace-id>/vault/<vault-id>/entry/<entry-id>/field/username
```

The command looks at the `password`, `username`, `host`, `domain`, and `url` fields of the entry. It shows the canonical reference whenever the IDs are known, and the named reference otherwise. With `--output json`, each field lists both forms. See [Read results as JSON](/cli/for-devops-and-administrators/automate/json-output.md).

## Named or canonical reference

<table><thead><tr><th width="150">FORM</th><th>LOOKS LIKE</th><th>USE IT WHEN</th></tr></thead><tbody><tr><td><strong>Named</strong></td><td><code>devo://&#x3C;workspace>/&#x3C;vault>/&#x3C;entry>/&#x3C;field></code></td><td>You want a reference people can read. It resolves against the current context, or the one you select with <code>--context</code>, and stops working if the entry or the vault is renamed.</td></tr><tr><td><strong>Canonical</strong></td><td><code>devo://ws/&#x3C;workspace-id>/vault/&#x3C;vault-id>/entry/&#x3C;entry-id>/field/&#x3C;field></code></td><td>You commit the reference or share it. It keeps working after a rename, and it always resolves against the workspace that owns it, whatever context is selected. One command can mix canonical references from several workspaces.</td></tr></tbody></table>

On Devolutions Server, `devo entry references` lists canonical references only.

Each part of a reference is URL-decoded. If a name contains a `/` or a `#`, write it as `%2F` or `%23`.

## Point at a field in a section

On a local profile, some entries group fields in sections. In a named reference, add the section between the entry and the field:

```
devo://<workspace>/<vault>/<entry>/<section>/<field>
```

`devo secret get` takes the section with `--section`. Sections work with local profiles only: Devolutions Cloud and Devolutions Server refuse a reference with a section, and canonical references have no section.

## Read an attribute instead of the value

Add `?attribute=` (or `?attr=`) to a reference to read something else than the value. `devo secret read` and `devo secret get` also accept `--attribute`.

<table><thead><tr><th width="150">ATTRIBUTE</th><th>WHAT YOU GET</th></tr></thead><tbody><tr><td><code>value</code></td><td>The secret value. This is the default.</td></tr><tr><td><code>type</code></td><td>The kind of field. The values depend on the workspace type.</td></tr><tr><td><code>id</code></td><td>The ID of the entry.</td></tr><tr><td><code>title</code></td><td>The name of the entry. Empty for a canonical reference on Devolutions Cloud and Devolutions Server.</td></tr><tr><td><code>purpose</code></td><td>On Devolutions Cloud and Devolutions Server, why the value was requested, such as <code>read</code>. Empty on a local profile.</td></tr></tbody></table>

`type`, `id`, `title`, and `purpose` are value-free reads: Devolutions CLI returns them without reading the secret, on Devolutions Cloud, Devolutions Server, and local profiles.

This is a safe first check of a reference, without reading the secret:

```bash
devo secret read "<reference>?attribute=type"
```

Put the reference in quotes so your shell doesn't interpret the `?`. A success confirms that the reference is well formed and, for a named reference or on a local profile, that the vault and the entry exist. It doesn't prove that the field can be read: on Devolutions Cloud and Devolutions Server, a canonical reference isn't looked up at all. Only reading the value confirms the field.

## Which fields each workspace type can read

`devo secret capabilities` describes, for Devolutions Cloud, Devolutions Server, and local profiles, which fields can be read and written. It doesn't read any context or secret. Add `--output json` for the full list of fields; the text output shows only a summary.

```bash
devo secret capabilities --output json
```

## If it doesn't work

* The command says the reference is invalid, or the entry or field isn't found: see [A secret reference doesn't resolve](/cli/help/troubleshooting/reference-does-not-resolve.md).
* A field is missing from the list: the entry may not have it, or your workspace type can't resolve it. See [Compare workspace types](/cli/guides/understand/workspace-types.md).

## Next

* [Run a command with its secrets](/cli/guides/secrets/run-with-secrets.md)
* [Secret reference syntax](/cli/reference/secret-references.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/find-a-reference.md?ask=<question>&goal=<user_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.