> 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/it/riferimento/secret-references.md).

# Sintassi dei riferimenti al segreto

Sintassi dei riferimenti devo, forme con nome e canoniche, sezioni, attributi, codifica, URI di provider di SecretSpec e come i riferimenti si trovano in un testo.

Un riferimento al segreto è l’indirizzo di un campo di una voce. Inizia con `devo://` e dice dove si trova il segreto, mai che cos’è. Ogni comando `devo secret`, i manifesti di avvio, i file `.env` e i modelli usano la stessa sintassi.

Per ottenere il riferimento di un campo senza digitarlo, esegua `devo entry references <entry>`. Consulti [Trovare il riferimento a un segreto](/cli/it/guide/secrets/find-a-reference.md).

## Riferimenti con nome

Un riferimento con nome usa i nomi dello spazio di lavoro, della cassaforte e della voce, quindi è facile da leggere:

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

<table><thead><tr><th width="190">SEGMENTO</th><th>CHE COS’È</th></tr></thead><tbody><tr><td><code>&#x3C;workspace></code></td><td>Lo spazio di lavoro che contiene la cassaforte.</td></tr><tr><td><code>&#x3C;vault></code></td><td>La cassaforte che contiene la voce.</td></tr><tr><td><code>&#x3C;entry></code></td><td>La voce che contiene il campo.</td></tr><tr><td><code>&#x3C;section></code></td><td>Facoltativo, solo profilo locale. La sezione della voce che contiene il campo, quando il campo è in una sezione. Devolutions Cloud e Devolutions Server rifiutano una sezione con <code>unsupportedSecretField</code>.</td></tr><tr><td><code>&#x3C;field></code></td><td>Il campo da leggere, per esempio <code>password</code>, <code>username</code>, <code>domain</code>, <code>host</code>, <code>otp</code> o <code>privatekey</code>.</td></tr></tbody></table>

Un riferimento con nome è risolto nello spazio di lavoro selezionato per il comando: il contesto corrente, o quello scelto con `--context` o `--source`. Consulti [Opzioni globali](/cli/it/riferimento/global-options.md).

## Riferimenti canonici

Un riferimento canonico usa gli ID invece dei nomi:

```
devo://ws/<workspace-id>/vault/<vault-id>/entry/<entry-id>/field/<field>
```

* Continua a funzionare quando la voce, la cassaforte o lo spazio di lavoro viene rinominato.
* Nomina lo spazio di lavoro che lo possiede, quindi è risolto in quello spazio di lavoro, qualunque sia il contesto corrente. Un `devo secret run` può mescolare riferimenti di un profilo locale, di Devolutions Cloud e di Devolutions Server.
* Non ha un segmento di sezione.
* Su Devolutions Server, `devo entry references` elenca solo riferimenti canonici. Un riferimento con nome che scrive lei funziona ancora.

## Attributi

Per impostazione predefinita, un riferimento restituisce il valore del campo. Aggiunga `?attribute=` (o la forma breve `?attr=`) per leggere informazioni sul campo invece del suo valore. I valori non distinguono le maiuscole.

<table><thead><tr><th width="190">ATTRIBUTO</th><th>CHE COSA RESTITUISCE</th><th width="150">SEGRETO</th></tr></thead><tbody><tr><td><code>value</code></td><td>Il valore del campo. È il valore predefinito e l’unico attributo che restituisce un segreto.</td><td>Sì</td></tr><tr><td><code>type</code></td><td>Il tipo di campo.</td><td>No</td></tr><tr><td><code>id</code></td><td>L’ID della voce.</td><td>No</td></tr><tr><td><code>title</code></td><td>Il nome della voce. Vuoto per un riferimento canonico su Devolutions Cloud e Devolutions Server.</td><td>No</td></tr><tr><td><code>purpose</code></td><td>Perché il valore è stato richiesto: <code>read</code>, <code>inject</code>, <code>run</code> o <code>mcp</code>. Vuoto su un profilo locale.</td><td>No</td></tr></tbody></table>

`type`, `id`, `title` e `purpose` restituiscono solo informazioni, mai il segreto, su ogni tipo di spazio di lavoro.

Per esempio, `devo://<workspace>/<vault>/<entry>/password?attribute=type` restituisce il tipo del campo `password`, non la password. `devo secret read` e `devo secret get` accettano anche `--attribute` al posto della query.

## Caratteri speciali

Ogni segmento tra due `/` è decodificato come URL. Se un nome contiene `/`, `?`, `#`, `%` o uno spazio, lo codifichi: per esempio, scriva `Web%2FProd` per una voce chiamata `Web/Prod` e `My%20vault` per `My vault`. Un `:` può restare com’è.

I riferimenti che Devolutions CLI stampa, per esempio con `devo entry references`, sono già codificati.

## Regole ed errori

Quando un riferimento non può essere letto, il comando fallisce con il codice di errore `invalidSecretReference` e uno di questi messaggi.

<table><thead><tr><th width="320">MESSAGGIO</th><th>CHE COSA VERIFICARE</th></tr></thead><tbody><tr><td>"Secret reference cannot be empty."</td><td>Il riferimento è vuoto o contiene solo spazi.</td></tr><tr><td>"Secret reference must start with 'devo://'."</td><td>Il prefisso manca o è scritto male. Il prefisso non distingue maiuscole e minuscole.</td></tr><tr><td>"Secret references do not support URI fragments."</td><td>Il riferimento contiene <code>#</code>. Lo codifichi come <code>%23</code> se fa parte di un nome.</td></tr><tr><td>"Secret reference path cannot be empty."</td><td>Nulla segue <code>devo://</code>.</td></tr><tr><td>"Use devo://&#x3C;workspace>/&#x3C;vault>/&#x3C;entry>/&#x3C;field> or devo://&#x3C;workspace>/&#x3C;vault>/&#x3C;entry>/&#x3C;section>/&#x3C;field>."</td><td>Un riferimento con nome ha bisogno di 4 o 5 segmenti. Controlli se manca un segmento o se c’è un <code>/</code> non codificato in un nome.</td></tr><tr><td>"Secret reference path segments cannot be empty."</td><td>Due <code>/</code> si seguono, oppure il riferimento termina con <code>/</code>.</td></tr><tr><td>"Canonical ID references must use devo://ws/&#x3C;id>/vault/&#x3C;id>/entry/&#x3C;id>/field/&#x3C;field>."</td><td>Un riferimento che inizia con <code>ws</code> e ha 8 segmenti deve usare le parole <code>vault</code>, <code>entry</code> e <code>field</code> in quest’ordine.</td></tr><tr><td>"Canonical workspace, vault, and entry identifiers cannot be empty."</td><td>Manca un ID in un riferimento canonico.</td></tr><tr><td>"Canonical field segment cannot be empty."</td><td>Il campo manca alla fine di un riferimento canonico.</td></tr></tbody></table>

Un attributo sconosciuto non riesce con il codice `unsupportedSecretAttribute` e il messaggio «Unsupported secret reference attribute '\<value>'.». Gli altri parametri di query sono ignorati.

Quando il riferimento è valido ma non porta a un campo che può leggere, consulti [Un riferimento al segreto non si risolve](/cli/it/aiuto/troubleshooting/reference-does-not-resolve.md).

## Riferimenti all’interno di un testo

`devo secret inject` trova i riferimenti in un modello e sostituisce ciascuno con il suo valore. Riconosce due forme:

<table><thead><tr><th width="250">FORMA</th><th>DOVE FINISCE</th></tr></thead><tbody><tr><td><code>{{ devo://… }}</code></td><td>Alla <code>}}</code> di chiusura. Anche le parentesi graffe vengono sostituite, e gli spazi al loro interno sono ignorati. Usi questa forma quando il riferimento è accanto ad altro testo.</td></tr><tr><td><code>devo://…</code></td><td>Al primo spazio, a capo, <code>"</code>, <code>'</code>, <code>&#x3C;</code>, <code>></code>, <code>)</code>, <code>]</code> o <code>}</code>.</td></tr></tbody></table>

Un testo che inizia con `devo://` ma non è un riferimento valido viene lasciato così com’è.

In un modello, un riferimento può anche contenere variabili d’ambiente, che `devo secret inject` sostituisce prima di leggere il segreto:

<table><thead><tr><th width="250">ESPRESSIONE</th><th>CHE COSA DIVENTA</th></tr></thead><tbody><tr><td><code>$NAME</code> or <code>${NAME}</code></td><td>Il valore della variabile d’ambiente <code>NAME</code>. Se non è impostata o è vuota, il comando non riesce con <code>missingSecretReferenceVariable</code>.</td></tr><tr><td><code>${NAME:-default}</code></td><td>Il valore di <code>NAME</code>, oppure <code>default</code> quando non è impostato o è vuoto.</td></tr></tbody></table>

Per esempio, `{{ devo://<workspace>/${VAULT:-Staging}/<entry>/password }}` legge dalla cassaforte nominata in `VAULT`, oppure da `Staging`.

{% hint style="warning" %}
`devo secret inject` scrive i valori in testo normale nel suo output. Consulti [Compilare un file di configurazione da un modello](/cli/it/guide/secrets/fill-a-template.md).
{% endhint %}

## URI del provider SecretSpec

SecretSpec non usa riferimenti a segreti. In `secretspec.toml` usa un URI del provider che indica quale spazio di lavoro Devolutions CLI deve leggere. Stampi quello giusto con `devo secretspec uri`. Consulti [Usare Devolutions CLI con SecretSpec](/cli/it/guide/secrets/secretspec.md).

<table><thead><tr><th width="330">URI DEL PROVIDER</th><th>SPAZIO DI LAVORO</th></tr></thead><tbody><tr><td><code>devo://cloud[/&#x3C;vault-id>][?context=&#x3C;name>]</code></td><td>Devolutions Cloud, tramite il contesto <code>&#x3C;name></code>, oppure il contesto Devolutions Cloud corrente senza <code>?context=</code>.</td></tr><tr><td><code>devo://server[/&#x3C;vault-id>][?context=&#x3C;name>]</code></td><td>Devolutions Server, tramite il contesto <code>&#x3C;name></code>, oppure il contesto Devolutions Server corrente senza <code>?context=</code>.</td></tr><tr><td><code>devo://sqlite[/&#x3C;vault-id>]?workspace=&#x3C;workspace-id></code></td><td>Uno spazio di lavoro locale di Devolutions Remote Desktop Manager. <code>?workspace=</code> è obbligatorio, con un ID di spazio di lavoro come <code>sqlite:Connections.db</code>. <code>devo workspace current</code> lo mostra.</td></tr></tbody></table>

`<vault-id>` è facoltativo: imposta la cassaforte predefinita, e ogni segreto può ancora indicare la propria cassaforte.


---

# 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/it/riferimento/secret-references.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.