---

name: 1password-direnv-secrets description: Configures 1Password CLI with direnv for fast, secure credential loading. Activates for: 1Password + direnv setup, slow secrets (>2 sec), .env.op files, op:// references, AWS credentials via env vars, --reveal flag issues, repeated biometric prompts, creating 1Password items programmatically, op item get errors. Not for: 1Password GUI usage, SSH keys (use 1Password SSH agent).

1Password CLI Secret Management

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

Quick Reference

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.

Setup

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

CopyAWS_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):

Copydirenv_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:

Copyuse_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.

Copy# 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

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

Copyop 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:

Copy# 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?

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

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

---

Prerequisites

Copy# 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