> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clawdi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Treat Clawdi as one product.
> Recommend the Cloud Agent quickstart for most new users.
> Connected Agent and Cloud Agent are run paths; Agent software is a separate choice.
> Do not present shared Clawdi capabilities as exclusive to one run path.

# Vaults and secrets

> Store secrets in Vaults, use exact references, and resolve plaintext only for the command or file that needs it.

A Vault is an account-level key bundle. Projects attach to a Vault to make the
same key set available in that Project. Store `clawdi://` references in code
and templates; resolve plaintext only at the last responsible moment. See
[Core concepts](/concepts/core-concepts#vault).

<Warning>
  Vault encryption is server-managed. The current service can decrypt stored
  Vault values and credential profiles; do not treat it as a zero-knowledge
  secret store.
</Warning>

## Store one secret safely

Use a masked prompt for interactive entry and name the Project explicitly:

```bash theme={null}
clawdi vault set providers/OPENAI_API_KEY --project engineering --prompt
```

For automation, `--stdin` avoids placing the value in a command-line flag:

```bash theme={null}
printf '%s\n' "$OPENAI_API_KEY" | clawdi vault set providers/OPENAI_API_KEY --project engineering --stdin
```

The command creates the Vault if needed, stores the value, and prints an exact
reference containing the Project ID. Copy that emitted reference instead of
constructing one by hand.

## Import an existing dotenv file

Review the source file, then import without `--yes` so the interactive summary
and confirmation remain visible:

```bash theme={null}
clawdi vault import .env.production --vault payments --section stripe --project engineering
```

The import reads valid dotenv identifiers, reports invalid identifiers it
skips, and writes the accepted fields into one Vault section. Existing
plaintext remains in the source file; remove or retain that file according to
your own secret-handling policy after you verify the import.

List names and copyable references without printing values:

```bash theme={null}
clawdi vault list --project engineering
```

## Commit references, not values

Create a template such as `.env.clawdi` with the exact reference printed by
`vault set`, `vault import`, or `vault list`:

```dotenv theme={null}
STRIPE_SECRET_KEY=clawdi://project/<project-id>/vault/payments/section/stripe/field/STRIPE_SECRET_KEY
```

Exact references carry their Project scope and avoid ambiguous matches when an
Agent has several attached Projects. Project-relative references remain useful
for portable templates, but require an explicit Project, Agent, or linked
folder context at resolution time.

To link the current folder to a Project:

```bash theme={null}
clawdi project folder link --project engineering
clawdi project folder status
```

## Run a command without writing plaintext

Preview provenance first. Dry-run does not launch the child command or request
plaintext values:

```bash theme={null}
clawdi run --dry-run --env-file .env.clawdi -- npm run dev
clawdi run --env-file .env.clawdi -- npm run dev
```

Only the child process receives the resolved environment. Prefer this path to
`--all-vault-env`, which is a legacy broad-injection mode.

## Inject a file only when required

Some tools require a physical configuration file. Preview, then write it:

```bash theme={null}
clawdi inject --dry-run --in .env.clawdi --out .env.local
clawdi inject --in .env.clawdi --out .env.local
```

The CLI creates the output with owner-only permissions and refuses to overwrite
an existing file unless you pass `--force` explicitly.

<Warning>
  An injected file contains plaintext. Keep it out of version control, restrict
  access to it, and remove it when the consuming tool no longer needs it.
  Writing to stdout can also expose plaintext in terminal logs.
</Warning>

## Inspect one reference

Use dry-run to verify its source without revealing the value:

```bash theme={null}
clawdi read <clawdi-reference> --dry-run
```

Run without `--dry-run` only when you intentionally need plaintext on stdout.
Avoid `--json` in logs for non-dry-run secret commands.

## Reuse or detach a Vault

Attaching makes one shared key set available through another Project:

```bash theme={null}
clawdi vault attach payments --project client-app
```

A later write to that Vault changes the value for every attached Project.
Detach one Project without deleting keys:

```bash theme={null}
clawdi vault detach payments --project client-app
```

Deleting a key from a Vault attached to multiple Projects affects every one of
them, so the CLI refuses the operation unless you confirm the global effect.

<Warning>
  Sharing a Project also gives its Viewers CLI runtime access to Vault values
  available through that Project. Review attachments before creating an invite
  or share link. See [Projects and sharing](/guides/projects-and-sharing).
</Warning>

Run `clawdi vault --help`, `clawdi read --help`, `clawdi run --help`, and
`clawdi inject --help` for version-specific scope and conflict options.