1password-direnv-secrets

1Password CLI Secret Management

Secure credential management using 1Password CLI with zero plaintext secrets on disk.

Quick Reference

Use Case	Approach	Details
All secrets (AWS, DB, APIs)	direnv + op run	Core Pattern
CI/CD automation	Service account token	Session Management
Creating items for users	op item create	Programmatic Creation

Key insight: Secrets load once on cd and all subprocesses inherit them (standard Unix fork() behavior). One op call, no re-fetching.

---

Core Pattern: direnv + op run

Use op run --env-file NOT multiple op read calls.

Approach	CLI Invocations	Load Time
Multiple op read	N per secret	~5 seconds
Single op run	1	~1 second

Setup

1. .env.op (safe to commit - contains only op:// references):

AWS_ACCESS_KEY_ID="op://Vault/Item/Access Key ID"
AWS_SECRET_ACCESS_KEY="op://Vault/Item/Secret Access Key"
DB_PASSWORD="op://Vault/Item/password"

2. .envrc (safe to commit - no secrets, just loader command):

direnv_load op run --env-file=.env.op --no-masking \
  --account=yourcompany.1password.com -- direnv dump

3. Enable: direnv allow

Global Helper

Add to ~/.config/direnv/direnvrc:

use_1password() {
  local env_file="${1:-.env.op}" account="${2:-yourcompany.1password.com}"
  [[ -f "$env_file" ]] && direnv_load op run --env-file="$env_file" \
    --no-masking --account="$account" -- direnv dump
}

Then .envrc becomes: use 1password

---

Critical: The --reveal Flag

Concealed fields require --reveal to get actual values.

# WRONG - returns placeholder text, NOT the secret!
op item get "Item" --fields "Secret Access Key"
# Output: [use 'op item get xxx --reveal' to reveal]

# CORRECT - returns actual secret value
op item get "Item" --fields "Secret Access Key" --reveal

Common symptom: SignatureDoesNotMatch errors from AWS indicate the secret wasn't retrieved properly.

---

Reducing Biometric Prompts

Scenario	Solution	Prompts
Dev entering project	direnv + op run	1 on directory entry
CI/CD pipeline	OP_SERVICE_ACCOUNT_TOKEN	0

Key insight: Sessions last 10 minutes with auto-refresh on each use. Keep 1Password desktop app unlocked and integrated with CLI.

Detailed strategies: references/session-management.md

---

Discovery Commands

op account list                                    # Find accounts
op vault list --account mycompany.1password.com    # Find vaults
op item list --account mycompany.1password.com     # Find items

Full reference: references/discovery-commands.md - field inspection, search patterns, debugging

---

Creating Items Programmatically

For Claude Code workflows where Claude sets up infrastructure without handling raw secrets:

# Create item with placeholder values
op item create --category "API Credential" \
  --title "AWS Service-Name" \
  --vault "Private" \
  --account mycompany.1password.com \
  "Access Key ID[text]=REPLACE_ME" \
  "Secret Access Key[concealed]=REPLACE_ME"

User populates via 1Password app, then Claude continues with configuration.

Full pattern: references/programmatic-item-creation.md

---

What's Safe to Commit?

File	Safe?	Why
.env.op	Yes	Contains only op:// pointers
.envrc	Yes	No secrets - just loader command delegating to .env.op
.env	Never	Contains actual secrets

The account name (e.g., yourcompany.1password.com) isn't sensitive - it's just an identifier. For team projects, everyone uses the same account anyway.

---

Troubleshooting

Error	Fix
SignatureDoesNotMatch (AWS)	Add --reveal for concealed fields
op: command not found	brew install --cask 1password-cli
could not find item	Names are case-sensitive; verify exact name

Full troubleshooting: references/session-management.md#troubleshooting-excessive-prompts

---

Prerequisites

# Install 1Password CLI (v2.18.0+ for service accounts)
brew install --cask 1password-cli

# Install direnv (for env var approach)
brew install direnv
echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc

# Sign in and integrate with desktop app
op signin --account=yourcompany.1password.com

# Verify integration
op whoami

Required: 1Password desktop app with CLI integration enabled (Settings → Developer → CLI Integration).

---

Detailed References

• Session Management - Minimizing prompts, service accounts, CI/CD
• Discovery Commands - Finding accounts, vaults, items, fields
• Programmatic Item Creation - Claude Code workflow patterns