1password-cli

1Password CLI Integration

Use the 1Password CLI (op) to securely retrieve secrets from the user's 1Password vault without ever exposing secret values in conversation output.

CRITICAL SECURITY RULES

The Bash tool captures command output and includes it in conversation history. Running op read alone exposes the secret. Always consume secrets inline.

Recommended Workflow

Ask for the secret reference first. When a user needs a secret from 1Password:

1. Ask the user to provide the secret reference directly (e.g., op://Private/MyService/password)
2. Only search for items if the user explicitly asks you to find/search for a secret
3. Read the secret using the provided reference with inline consumption

This approach is faster, avoids unnecessary API calls, and ensures the user knows exactly which secret is being accessed.

Example prompt to user:

"Please provide the 1Password secret reference (e.g., op://VaultName/ItemName/field), or ask me to search for it if you're unsure."

Mandatory Patterns

What NOT to Do

# ❌ WRONG - secret appears in Bash tool output
op read "op://vault/item/password"

# ❌ WRONG - echo displays the secret
PASSWORD=$(op read "op://vault/item/password")
echo "Password is: $PASSWORD"

# ✅ CORRECT - secret consumed immediately, only confirmation shown
export DB_PASS=$(op read "op://vault/item/password") && echo "Secret loaded successfully"

Additional Rules

1. Use --no-newline when writing to files where trailing newlines cause issues
2. Report success generically - Never mention the secret's content, length, or characteristics

Secret Reference Syntax

op://vault/item/field

• vault: The name or ID of the vault containing the item
• item: The name or ID of the item
• field: The field name (e.g., password, username, credential, or custom field names)

Common Field Names

Core Commands

Find Items (only when user asks to search)

Use these commands only when the user explicitly asks to find or search for a secret:

# List vaults
op vault list --format=json

# List items in a vault
op item list --vault="VaultName" --format=json

# Search by title
op item list --format=json | jq -r '.[] | select(.title | test("search_term"; "i")) | "\(.id) | \(.title)"'

# Get item field structure
op item get "ItemName" --format=json | jq '.fields[] | {label, type}'

Read Secrets (always consume inline)

# Environment variable
export DB_PASSWORD=$(op read "op://Private/Database/password")

# Write to file
op read "op://Private/SSHKey/private key" > ~/.ssh/id_rsa && chmod 600 ~/.ssh/id_rsa

# Inline in command
curl -u "user:$(op read 'op://Private/API/credential')" https://api.example.com

Check Authentication

op whoami --format=json 2>/dev/null && echo "Authenticated" || echo "Not signed in - run: op signin"

Categories

Common item categories for --categories filter: Login, Password, API Credential, Secure Note, SSH Key, Database, Server, Document.

Additional Resources

See examples.md in this skill folder for detailed workflow examples, query parameters, and advanced patterns like op run and op inject.

For comprehensive documentation: 1Password CLI Reference