1password CLI Skill

1Password CLI Skill

Use this skill when working with the 1Password CLI (op command) for secrets management, retrieving API keys, or injecting secrets into development environments.

Installation

# macOS
brew install 1password-cli

# Verify installation
op --version

Authentication Methods

1. Desktop App Integration (Interactive - Recommended for Development)

Enable biometric authentication (Touch ID/Windows Hello) through the 1Password desktop app:

1. Open 1Password app > Settings > Developer
2. Enable "Integrate with 1Password CLI"
3. Run any op command - you'll be prompted to authenticate

# This will prompt for biometric auth
op vault list

2. Service Account Token (Non-Interactive - CI/CD & Automation)

For automated environments without user interaction:

# Set the service account token as environment variable
export OP_SERVICE_ACCOUNT_TOKEN="ops_..."

# Now commands work without prompts
op vault list

Create service accounts in 1Password.com > Developer Tools > Service Accounts.

3. Manual Sign In (Legacy)

# Sign in and create a session
eval $(op signin)

# Or for a specific account
eval $(op signin --account my-team.1password.com)

Secret Reference Syntax

Secret references use the URI format: op://vault/item/[section/]field

op://vault-name/item-name/field-name           # Simple field
op://vault-name/item-name/section/field-name   # Field in a section
op://Private/GitHub/password                    # Example: GitHub password
op://dev/Stripe/publishable-key                # Example: Stripe key

Get Secret References

# Get reference for a specific field
op item get "GitHub" --vault Private --fields password --format json | jq -r '.reference'

# Output: op://Private/GitHub/password

Reading Secrets

Read a Single Secret

# Using secret reference
op read "op://vault-name/item-name/field-name"

# Examples
op read "op://Private/API Keys/openai-key"
op read "op://dev/Database/password"

Get Item Details

# Get full item as JSON
op item get "item-name" --vault "vault-name" --format json

# Get specific field
op item get "GitHub" --fields password

# Get multiple fields
op item get "Database" --fields username,password

List Items

# List all vaults
op vault list

# List items in a vault
op item list --vault "Private"

# Search for items
op item list --tags api-key

Injecting Secrets into Environment Variables

Using op run

The most secure way to use secrets - they exist only during command execution:

# Set secret reference in environment
export DB_PASSWORD="op://app-prod/database/password"

# Run command with secrets injected
op run -- ./my-script.sh

# Secrets are automatically masked in output
op run -- printenv DB_PASSWORD  # Shows: <concealed by 1Password>

# Disable masking if needed
op run --no-masking -- printenv DB_PASSWORD

Using .env Files

Create a .env file with secret references:

# .env file
DATABASE_URL="op://dev/postgres/connection-string"
API_KEY="op://dev/my-api/key"
SECRET_TOKEN="op://dev/app/secret-token"

Run with the env file:

op run --env-file=.env -- npm start
op run --env-file=.env -- python app.py

Environment-Specific Secrets

Use variables to switch between environments:

# .env file with variable
DB_PASSWORD="op://$APP_ENV/database/password"

# Switch environments
APP_ENV=dev op run --env-file=.env -- ./start.sh
APP_ENV=prod op run --env-file=.env -- ./start.sh

Common Use Cases

Retrieve API Keys for Development

# Get a single API key
OPENAI_KEY=$(op read "op://Private/OpenAI/api-key")

# Use in a command
curl -H "Authorization: Bearer $(op read 'op://Private/OpenAI/api-key')" ...

Populate Environment for Local Development

# Create .env.local with secret references
cat > .env.local << 'EOF'
SUPABASE_URL="op://dev/Supabase/url"
SUPABASE_KEY="op://dev/Supabase/service-role-key"
ANTHROPIC_API_KEY="op://dev/Anthropic/api-key"
EOF

# Start development server with secrets
op run --env-file=.env.local -- npm run dev

Export Secrets to Shell Session

# Export secrets for current shell session
export GITHUB_TOKEN=$(op read "op://Private/GitHub/token")
export NPM_TOKEN=$(op read "op://Private/npm/token")

Use in Scripts

#!/bin/bash
# deploy.sh - uses 1Password for secrets

# Ensure we have access
op whoami > /dev/null 2>&1 || eval $(op signin)

# Get deployment credentials
DEPLOY_KEY=$(op read "op://prod/deploy/ssh-key")
API_TOKEN=$(op read "op://prod/api/token")

# Use in deployment...

Creating and Managing Items

Create a New Item

# Create API key item
op item create \
  --category "API Credential" \
  --title "My API Key" \
  --vault "dev" \
  --fields "api-key=sk-abc123"

# Create login item
op item create \
  --category Login \
  --title "Service Account" \
  --vault Private \
  --fields "username=admin,password=secret123"

Update an Item

# Update a field
op item edit "My API Key" --vault dev "api-key=sk-newkey456"

Delete an Item

op item delete "Old API Key" --vault dev

Security Best Practices

1. Use Service Accounts for CI/CD: Never use personal credentials in automated environments

2. Limit Vault Access: Service accounts should only access vaults they need

3. Use op run Over Export: Secrets only exist during command execution, not in shell history

4. Avoid Logging Secrets: op run masks secrets by default - keep it enabled

5. Rotate Service Account Tokens: Regularly rotate tokens used in CI/CD pipelines

6. Use Secret References in Code: Store references, not secrets, in configuration files

7. Audit Access: Review service account usage reports in 1Password.com

Troubleshooting

"You are not currently signed in"

# Check current session
op whoami

# Sign in again
eval $(op signin)

# Or set service account token
export OP_SERVICE_ACCOUNT_TOKEN="ops_..."

"Item not found"

# List available vaults to verify access
op vault list

# Search for the item
op item list --vault "vault-name" | grep "item-name"

Desktop App Integration Not Working

1. Ensure 1Password app is running and unlocked
2. Check Settings > Developer > "Integrate with 1Password CLI" is enabled
3. Restart terminal after enabling integration

Quick Reference