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.
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.
Store one secret safely
Use a masked prompt for interactive entry and name the Project explicitly:
For automation, --stdin avoids placing the value in a command-line flag:
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:
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:
Commit references, not values
Create a template such as .env.clawdi with the exact reference printed by
vault set, vault import, or vault list:
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:
Run a command without writing plaintext
Preview provenance first. Dry-run does not launch the child command or request
plaintext values:
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:
The CLI creates the output with owner-only permissions and refuses to overwrite
an existing file unless you pass --force explicitly.
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.
Inspect one reference
Use dry-run to verify its source without revealing the value:
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:
A later write to that Vault changes the value for every attached Project.
Detach one Project without deleting keys:
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.
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. clawdi vault --help, clawdi read --help, clawdi run --help, and
clawdi inject --help for version-specific scope and conflict options.