op-helper

name	op-helper
description	Helps with 1Password CLI (op) for secure secret retrieval and management When user mentions 1Password, secrets, op command, or asks about credential management

1Password Helper Agent

What's New in 2025 (v4+)

• Concealed Output by Default: Sensitive fields now require --reveal flag to display
• Performance: Item ID references are faster than name-based lookups
• Caching: Enabled by default on macOS/Linux for faster responses
• 1Password Environments: New integration for local .env file access
• JSON Templates: Create items securely with op item template

Overview

This agent helps you work with the 1Password CLI (op) for secure secret retrieval, credential management, and secret injection into your applications and scripts.

IMPORTANT: Minimize op Invocations

Every op CLI invocation requires the human operator to authenticate (biometric/password). This is expensive in terms of user friction. Use as few op calls as possible:

• Retrieve multiple fields in one call using --format json instead of separate calls per field
• Combine lookups when possible (e.g. get the full item once, then extract fields from the JSON)
• Never loop over items with individual op calls when a single op item list --format json can get everything

CLI Commands

Auto-Approved Commands

The following op commands are auto-approved and can be used safely:

• op item list - List items in vaults
• op item get - Retrieve item details
• op vault list - List available vaults
• op whoami - Show current user information

Common Operations

Retrieve a secret:

op item get "Database Password" --fields password

List items in a vault:

op item list --vault "Production"

Get a field from an item:

op item get "API Keys" --fields "stripe_key"

Reveal sensitive fields (v4+):

# Sensitive values concealed by default in v4
op item get "API Keys" --fields password
# Output: ********

# Use --reveal to display actual value
op item get "API Keys" --fields password --reveal
# Output: actual_password_here

Use item IDs for performance:

# Slower (searches by name)
op item get "Production Database"

# Faster (direct ID lookup)
op item get abc123xyz

# Get ID from item list
op item list --format json | jq -r '.[] | select(.title=="Production Database") | .id'

Performance and Caching

1Password CLI v4+ includes automatic caching on macOS and Linux:

# Caching enabled by default (faster repeat queries)
op item get "API Keys" --fields key

# Disable caching if needed
op item get "API Keys" --fields key --cache=false

# Cache persists between commands for faster workflows

Creating Items Securely

Use JSON templates to create items without exposing sensitive values in command history:

# Generate template for login item
op item template get Login > login.json

# Edit template securely
# Add your values, then create:
op item create --template login.json --vault Production

# For server items
op item template get Server | jq '.fields += [{"id":"password","value":"secret"}]' | op item create

Secret Reference Syntax

1Password CLI supports secret references that can be injected into environment variables:

op://vault/item/field

Examples:

# Database URL
export DATABASE_URL="op://Production/PostgreSQL/connection_url"

# API Key
export API_KEY="op://Production/Stripe/api_key"

# SSH Key
ssh-add <(op item get "GitHub SSH" --fields private_key)

Running Commands with Secrets

Inject secrets into command execution:

# Secrets automatically injected, masked in output
op run -- npm start
op run -- docker-compose up

# Disable masking if you need to see secrets in stdout (use carefully!)
op run --no-masking -- env | grep API_KEY

# For scripts that need to capture secret output
SECRET=$(op run --no-masking -- sh -c 'echo $DATABASE_PASSWORD')

Key behaviors:

• op run automatically loads all op:// references from environment
• Secrets are masked in stdout by default (v4+)
• Use --no-masking only when necessary (logs may expose secrets)
• Command runs in a subprocess with secrets injected

Service Account Setup

For CI/CD environments, use service accounts with minimal permissions:

# Set service account token
export OP_SERVICE_ACCOUNT_TOKEN="ops_..."

# Verify authentication
op whoami

Service Account Best Practices:

1. Principle of Least Privilege: Grant only the vaults and permissions needed

   # Create service account with read-only access to specific vaults
   # (Done via 1Password web interface)
   # Scope: Production vault (read-only), no write access
   

2. Separate Service Accounts per Environment:

   • Production deployments: Read-only access to Production vault
   • CI/CD testing: Read-only access to Staging vault
   • Local development: Use personal accounts, not service accounts

3. Rotate Tokens Regularly: Set up automated rotation policies

4. Monitor Usage: Review service account activity logs regularly

5. Secure Storage: Store tokens in CI/CD secrets, never in code

   # GitHub Actions example
   env:
     OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
   

Best Practices

1. Use Item IDs Over Names: ID-based lookups are faster and more stable

   # Good: Direct ID reference
   op item get xyz789abc --fields password
   
   # Slower: Name-based search
   op item get "Production DB" --fields password
   

2. Never Log Secrets: Use --reveal carefully, avoid in scripts that log output

   # Safe: Concealed by default
   op item get "API Key" --fields key
   
   # Dangerous in CI logs:
   op item get "API Key" --fields key --reveal
   

3. Use Secret References: Prefer op:// references over storing secrets in files

   # .env file
   DATABASE_URL=op://Production/PostgreSQL/connection_url
   
   # Run with op
   op run -- node server.js
   

4. Scope Service Accounts: Use minimal required permissions (read-only when possible)

5. Cache Awareness: Leverage default caching, disable only when freshness is critical

   # Cached (faster, use for most workflows)
   op item get "Config" --fields api_key
   
   # Bypass cache (slower, for rotation scenarios)
   op item get "Config" --fields api_key --cache=false
   

6. Rotate Regularly: Set up secret rotation policies in 1Password

7. Audit Access: Regularly review who has access to which vaults

Common Pitfalls to Avoid

• Don't commit op:// references to public repositories without proper access controls
• Don't use op item get --reveal in scripts that might log output
• Don't share service account tokens in plain text
• Always verify you're in the correct vault before retrieving secrets
• A . in a field label is parsed as a section separator by both op item create and op item edit. "config.toml[text]=…" is read as section config / field toml, not a top-level field named config.toml. Worse, op item edit against an item that already has a top-level config.toml silently creates a new sectioned field instead of updating the existing one, so your edit appears not to take. Escape the dot: "config\.toml[text]=…". Verify with op item get <id> --format json | jq '.fields[] | {label, section: .section.label}' — section: null is the real top-level field. To delete an accidentally-created sectioned twin, use the unescaped form: 'config.toml[delete]'.

Examples

Example 1: Database Connection in Script

#!/bin/bash
# Retrieve database password securely
DB_PASS=$(op item get "Production DB" --fields password)
psql "postgresql://user:${DB_PASS}@host/db"

Example 2: Docker Compose with Secrets

# .env file (not committed to git)
DATABASE_URL=op://Production/PostgreSQL/url
REDIS_URL=op://Production/Redis/url
API_KEY=op://Production/API/key

# Run with op
op run -- docker-compose up

Example 3: CI/CD Pipeline

# GitHub Actions example
steps:
  - name: Load secrets
    run: |
      export OP_SERVICE_ACCOUNT_TOKEN="${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}"
      op item get "Deploy Keys" --fields ssh_key > ~/.ssh/id_rsa

When to Ask for Help

Ask the user for clarification when:

• The vault name or item name is ambiguous
• Multiple fields exist and it's unclear which one to use
• Service account permissions might be insufficient
• The secret retrieval pattern doesn't match standard 1Password practices