Claude Code

Goal

Install the dotsecenv plugin for Claude Code so your AI coding assistant can list, retrieve, store, share, and revoke GPG-encrypted secrets.

Prerequisites

dotsecenv installed and available on your PATH
A GPG key with your passphrase cached in gpg-agent (or macOS Keychain)
Claude Code installed (CLI, desktop app, or IDE extension)

Steps

Add the dotsecenv marketplace

In Claude Code, run:
```
/plugin marketplace add dotsecenv/dotsecenv
```
Install the plugin
```
/plugin install dotsecenv@dotsecenv
```
This registers two skills:
- /dotsecenv:secrets — manages secrets via the dotsecenv CLI (store, get, share, revoke)
- /dotsecenv:secenv — interprets .secenv files, resolves vault references, and debugs loading issues
Verify GPG is ready

The plugin checks your GPG configuration on first use. If your passphrase is not cached, Claude will ask you to warm the cache:
Terminal window
```
! gpg --sign --local-user YOUR_FINGERPRINT </dev/null
```
The ! prefix runs the command in your terminal so pinentry can prompt for your passphrase.
Use it

Ask Claude to work with your secrets naturally:
- “List my secrets” — lists secret keys without decrypting values
- “Show me the value of myapp::API_KEY” — decrypts a specific secret
- “Store a new secret called myapp::DB_PASSWORD” — encrypts and stores a value
- “Share myapp::API_KEY with fingerprint ABC123” — re-encrypts for another team member
- “Create a .secenv file for this project” — generates a .secenv with the right references
- “Why isn’t my secret loading?” — debugs vault paths and .secenv references

Expected Result

After installation, Claude can manage your dotsecenv secrets through natural language. The plugin enforces a security model that prevents Claude from decrypting secrets unless you explicitly ask.

You: list my secrets

Claude: Running dotsecenv secret get...

  myapp::API_KEY
  myapp::DB_PASSWORD
  staging::JWT_SECRET

You have 3 secrets across 1 vault.

Included Skills

The plugin provides two skills:

`/dotsecenv:secrets` — CLI Operations

Teaches Claude how to use the dotsecenv CLI safely:

Which commands are safe — listing secrets, describing vaults, and running health checks never trigger GPG decryption
When to ask first — decryption and mutation require your explicit request
How to detect problems — if your GPG pinentry is terminal-based or your passphrase is not cached, Claude warns you upfront instead of failing silently

`/dotsecenv:secenv` — File Interpretation

Teaches Claude how to work with .secenv files:

Parse .secenv syntax — plain variables (KEY=value), secret references (KEY={dotsecenv}, KEY={dotsecenv/prod::SECRET}), and quoted values
Resolve vault paths — reads your dotsecenv config to find vaults, understanding that relative paths like .dotsecenv/vault resolve relative to the .secenv file’s directory
Debug loading issues — checks if referenced secrets exist in reachable vaults, verifies file ownership/permissions, and explains ancestor loading behavior
Create .secenv files — generates files with the correct syntax after verifying secrets exist

GPG Pinentry Compatibility

Claude Code runs shell commands without a terminal, which affects how GPG passphrase prompts work:

Pinentry Program	Works with Claude Code?	Notes
`pinentry-mac`	Yes	GUI-based. Passphrase returned silently from Keychain or gpg-agent cache.
`pinentry-gnome3`	Yes	GUI-based. Needs a display server.
`pinentry-qt`	Yes	GUI-based. Needs a display server.
`pinentry-tty`	No	Requires terminal input that Claude cannot provide.
`pinentry-curses`	No	Requires terminal input that Claude cannot provide.

If you use a terminal-based pinentry, you have two options:

Switch to a GUI pinentry — set pinentry-program in ~/.gnupg/gpg-agent.conf
Pre-cache your passphrase before asking Claude to decrypt:
Terminal window
```
! gpg --sign --local-user YOUR_FINGERPRINT </dev/null
```

Security Model

The plugin enforces four tiers of operations:

Tier	Operations	Behavior
Safe	List secrets, describe vaults, validate, health checks	Claude runs freely
Decrypt	Retrieve a secret value	Only when you explicitly ask
Mutate	Store, share, revoke, forget	Claude confirms before executing
Prohibited	Keychain extraction, exfiltration, init/login	Never executed

Variations

Local Development (without marketplace)

If you are developing dotsecenv locally, you can load the plugin directly from a checkout:

claude --plugin-dir /path/to/dotsecenv

Uninstalling

/plugin uninstall dotsecenv@dotsecenv
/plugin marketplace remove dotsecenv

Next Steps

Threat Model — AI Agent Security — understand the security implications
Your First Secret — get started with dotsecenv
Shell Plugins — auto-load secrets when entering directories