> 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/secretspec.md).

# Use Devolutions CLI with SecretSpec

Register Devolutions CLI as a SecretSpec provider so projects that use secretspec.toml read their secrets from your Devolutions vault.

[SecretSpec](https://secretspec.dev) lets a project declare the secrets it needs in a `secretspec.toml` file, and fetches them from a provider. Devolutions CLI can be that provider: once it's registered, SecretSpec starts `devo` to read secrets from Devolutions Cloud, Devolutions Server, or a local Devolutions Remote Desktop Manager profile, using your existing contexts.

{% hint style="warning" %}
Devolutions CLI returns the secret values to SecretSpec, which hands them to your application. Masking doesn't apply. See [What stays hidden, and what doesn't](/cli/guides/understand/security-model.md).
{% endhint %}

{% stepper %}
{% step %}

### Register Devolutions CLI as the provider

```bash
devo secretspec register
```

This writes a small claim file, `devo.secretspec.json`, that tells SecretSpec which `devo` executable to start for `devo://` provider URIs. Add `--dry-run` to see the claim without writing it.

<table><thead><tr><th width="200">OPTION</th><th>WHAT IT DOES</th></tr></thead><tbody><tr><td><code>--system</code></td><td>Writes the claim for every user of the computer instead of only for you. This usually needs administrator rights.</td></tr><tr><td><code>--executable &#x3C;path></code></td><td>Registers another <code>devo</code> executable. The path must be absolute. By default, the <code>devo</code> you're running is registered.</td></tr><tr><td><code>--environment &#x3C;name></code>, <code>--env</code></td><td>Lets SecretSpec pass an extra environment variable to <code>devo</code>, by exact name or by prefix such as <code>DEVO_*</code>. Repeat for several. <code>RDM_CONFIG_PATH</code> and <code>DEVO_CLI_CONFIG_HOME</code> are always included.</td></tr><tr><td><code>--force</code></td><td>Replaces a claim that points at another executable for the <code>devo</code> scheme.</td></tr></tbody></table>
{% endstep %}

{% step %}

### Get the provider URI

Select the workspace with `--context` (or use the current context), then ask for its provider URI:

```bash
devo secretspec uri --context <context-name> --vault-id <vault-id>
```

Put the URI it prints in your `secretspec.toml` as the provider. `--vault-id` is optional: it sets the default vault, and a secret can still name its own vault.
{% endstep %}

{% step %}

### Check the registration

```bash
devo secretspec status
```

The status shows the claim for your user and for the computer, and for each one whether it's registered, points at the `devo` you're running, points at another one, or points at an executable that no longer exists.
{% endstep %}
{% endstepper %}

## Provider URI forms

<table><thead><tr><th width="200">WORKSPACE</th><th>PROVIDER URI</th></tr></thead><tbody><tr><td><strong>Devolutions Cloud</strong></td><td><code>devo://cloud/&#x3C;vault-id>?context=&#x3C;context-name></code></td></tr><tr><td><strong>Devolutions Server</strong></td><td><code>devo://server/&#x3C;vault-id>?context=&#x3C;context-name></code></td></tr><tr><td><strong>Local profile</strong></td><td><code>devo://sqlite/&#x3C;vault-id>?workspace=sqlite:&#x3C;file-name>.db</code></td></tr></tbody></table>

* The vault ID is optional in every form. Without it, every secret must name its own `vault`, or Devolutions CLI refuses it.
* For Devolutions Cloud and Devolutions Server, `?context=` is optional. Without it, the provider uses the current context.
* For a local profile, the workspace is required. Pass it to `devo secretspec uri` with `--workspace-id`, for example `--workspace-id sqlite:Connections.db`.

These provider URIs select a workspace for SecretSpec. They aren't secret references: you can't use them with `devo secret run`.

## How secrets are addressed

Devolutions CLI accepts native SecretSpec addresses only: each secret names the **entry ID** (`item`), the **field** (required), and optionally a **vault** that replaces the one in the provider URI. SecretSpec's convention-based addresses (project, profile, and key) are refused, because they can't point at one entry for sure. Sections aren't supported.

<table><thead><tr><th width="200">WORKSPACE</th><th>READ</th><th>WRITE</th></tr></thead><tbody><tr><td><strong>Devolutions Server</strong></td><td>Any data property of the entry.</td><td>Any data property of the entry.</td></tr><tr><td><strong>Devolutions Cloud</strong></td><td><code>domain</code>, <code>host</code>, <code>password</code>, <code>port</code>, <code>privatekey</code>, <code>url</code>, <code>username</code>.</td><td><code>password</code> only, on an entry that holds its own credentials.</td></tr><tr><td><strong>Local profile</strong></td><td>Yes.</td><td><code>password</code> only, with the workspace passphrase.</td></tr></tbody></table>

## Stop using Devolutions CLI as the provider

```bash
devo secretspec unregister
```

Add `--system` to remove the claim for the whole computer, and `--dry-run` to see which claim would be removed.

## Where the claim file goes

| SYSTEM      | FOR YOUR USER                                                                                                                                          | WITH `--system`                                                      |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
| **Windows** | `SecretSpec\providers.d` in your roaming application data folder                                                                                       | `SecretSpec\providers.d` in the machine-wide application data folder |
| **macOS**   | `~/Library/Application Support/SecretSpec/providers.d`                                                                                                 | `/Library/Application Support/SecretSpec/providers.d`                |
| **Linux**   | `$XDG_CONFIG_HOME/secretspec/providers.d`, or `~/.config/secretspec/providers.d` when `XDG_CONFIG_HOME` isn't set, is empty, or isn't an absolute path | `/etc/secretspec/providers.d`                                        |

## Good to know

* SecretSpec starts `devo` itself. You don't need to run `devo secretspec provider`.
* Add with `--environment` any other variable your contexts depend on, so SecretSpec can pass it to `devo`.

## Next

* [Switch between workspaces](/cli/guides/connect/switch-workspaces.md)
* Every option of `devo secretspec`: [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/secretspec.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.