> 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/understand/how-it-works.md).

# How Devolutions CLI works

Devolutions CLI replaces secret values with devo:// references and resolves them from your workspace only when a command starts.

Devolutions CLI doesn't store your secrets. It **points at them**. Your scripts, `.env` files and agent instructions hold a `devo://` reference, and Devolutions CLI fetches the value from your workspace only at the moment a command needs it. Understanding this one idea explains almost everything else: what you can safely commit, why you sign in once, and which commands keep a secret hidden.

## Four building blocks

<table><thead><tr><th width="190">BUILDING BLOCK</th><th>WHAT IT IS</th><th>EXAMPLE</th></tr></thead><tbody><tr><td><strong>Workspace</strong></td><td>Where your secrets live: Devolutions Cloud, Devolutions Server, or a local Devolutions Remote Desktop Manager profile. Inside it, secrets sit in fields of entries, grouped in vaults.</td><td>The <code>password</code> field of the <em>Production database</em> entry, in the <em>Operations</em> vault.</td></tr><tr><td><strong>Context</strong></td><td>A saved connection to one workspace, with a name you choose. You create it once with <code>devo login</code>, and every command after that uses the current context.</td><td><code>my-cloud</code>, <code>work-server</code>, <code>my-local</code></td></tr><tr><td><strong>Reference</strong></td><td>The address of one field, starting with <code>devo://</code>. It says where the secret is, never what it is.</td><td><code>devo://&#x3C;workspace>/&#x3C;vault>/&#x3C;entry>/password</code></td></tr><tr><td><strong>Command</strong></td><td>The program that needs the secret. <code>devo secret run</code> resolves the references, gives the values to that program only, and starts it.</td><td>A deployment script, a database client, an AI agent.</td></tr></tbody></table>

## What this means for you

**References are safe to share.** A reference contains names or IDs, not a value. You can commit it, paste it in a ticket, or give it to an AI agent. Without access to the vault, it opens nothing. See [Secret reference syntax](/cli/reference/secret-references.md).

**You sign in once, then work.** `devo login` saves the context and makes it current, so later commands don't ask again. To use another workspace for a single command, add `--context <name>`. See [Switch between workspaces](/cli/guides/connect/switch-workspaces.md).

**The same commands work everywhere.** Reading a secret or running a command looks the same on Devolutions Cloud, Devolutions Server, and a local profile. When a workspace can't do something, the command says so instead of failing silently. See [Compare workspace types](/cli/guides/understand/workspace-types.md).

**A secret reaches only the command you start.** `devo secret run` puts the values in the environment of that one program, not in your shell. Devolutions CLI refuses references written as command arguments, and hides resolved values in what the program prints. See [Run a command with its secrets](/cli/guides/secrets/run-with-secrets.md).

**Some commands hand the value over on purpose.** Reading a secret to the terminal, filling a template file, loading secrets in your current shell, or letting an AI client read an entry gives you, or the model, the actual value. Pick the command that matches how much you want to expose. See [What stays hidden, and what doesn't](/cli/guides/understand/security-model.md).

## The background process

To stay fast, `devo` starts a background process the first time a command needs your workspace, and reuses it afterward. It's the same `devo` file running in the background, under your user account, and it talks to `devo` over a local channel on your computer. You don't need to install a service or start anything yourself.

If you'd rather control it, the `--daemon` option accepts `auto` (the default: start it when needed), `require` (use one that's already running), or `never`. The `devo daemon` commands show its status, stop it, or restart it. See [The background process won't start](/cli/help/troubleshooting/daemon-wont-start.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/understand/how-it-works.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.