tools-1password-cli

name	tools-1password-cli
description	Comprehensive 1Password CLI (op) skill for secrets management, vault operations, environment injection, shell plugins, service accounts, and CI/CD integration. Use when working with credentials, API keys, environment variables, secure document storage, or automating secrets in development workflows.

1Password CLI (op) Skill

Master reference for the 1Password CLI (op command) covering secrets management, environment injection, shell plugins, service accounts, and CI/CD automation.

Decision Tree

┌─────────────────────────────────────────────────────────────────────────────────┐
│                        1PASSWORD CLI TASK ROUTER                                 │
└─────────────────────────────────────────────────────────────────────────────────┘
                                    │
         ┌──────────────┬───────────┼───────────┬──────────────┐
         │              │           │           │              │
    AUTHENTICATE    READ/WRITE   INJECT     AUTOMATE      PLUGINS
         │           SECRETS     SECRETS       │              │
         │              │           │           │              │
         ▼              ▼           ▼           ▼              ▼
    ┌─────────┐   ┌──────────┐ ┌─────────┐ ┌──────────┐ ┌──────────┐
    │Desktop  │   │op item   │ │op run   │ │Service   │ │Shell     │
    │App Int. │   │op read   │ │op inject│ │Account   │ │Plugins   │
    │or Token │   │op vault  │ │.env     │ │CI/CD     │ │CLI Auth  │
    └─────────┘   └──────────┘ └─────────┘ └──────────┘ └──────────┘

Prerequisites

# Verify installation
op --version

# Check authentication status
op whoami

# List available accounts
op account list

Authentication Methods

Method 1: Desktop App Integration (Recommended for Development)

Best for interactive use with biometric authentication.

# Enable in 1Password app:
# Settings > Developer > "Integrate with 1Password CLI"

# Verify integration
op vault list  # Prompts for biometric auth

Method 2: Service Account Token (CI/CD & Automation)

For non-interactive environments.

# Set environment variable
export OP_SERVICE_ACCOUNT_TOKEN="ops_..."

# Commands now work without prompts
op vault list
op item get "API Keys" --vault Production

Create Service Account:

# Create with vault access and permissions
op service-account create "ci-pipeline" \
  --vault Dev:read_items \
  --vault Staging:read_items,write_items \
  --expires-in 90d

# Token output (SAVE IMMEDIATELY - shown only once):
# ops_eyJhbGciOi...

Permission Options:

• read_items - Read secrets (default)
• write_items - Create/edit items (requires read_items)
• share_items - Share items (requires read_items)

Method 3: Manual Sign-In (Legacy)

# Interactive sign-in
eval $(op signin)

# Specific account
eval $(op signin --account my-team.1password.com)

# Get raw token (for scripts)
op signin --raw

Secret Reference Syntax

The op:// URI format for referencing secrets:

op://vault/item/[section/]field[?attribute=value]

Examples

# Simple field
op://Private/GitHub/password

# Field in section
op://Production/Database/Credentials/connection-string

# With query parameter (OTP)
"op://Private/Google/one-time password?attribute=otp"

# SSH key in OpenSSH format
"op://DevOps/SSH Key/private key?ssh-format=openssh"

Get Reference for Existing Item

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

Reading Secrets

Read Single Secret

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

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

# Save to file (SSH key, certificate)
op read --out-file ./key.pem "op://DevOps/Server/ssh-key"
op read --out-file ./cert.pem --file-mode 0600 "op://Production/SSL/certificate"

# No trailing newline (for scripts)
op read -n "op://Private/Token/value"

Get Item Details

# Full item as JSON
op item get "Database" --vault Production --format json

# Specific field
op item get "GitHub" --fields password

# Multiple fields
op item get "Database" --fields username,password

# Fields by type (all concealed fields)
op item get "Server" --fields type=concealed

# Get OTP
op item get "Google" --otp

# Get shareable link
op item get "API Key" --vault Shared --share-link

# Reveal concealed fields in output
op item get "Secrets" --reveal

Environment Injection

Using op run (Recommended)

Secrets exist only during command execution - never in shell history.

# Set reference in environment
export DB_PASSWORD="op://Production/Database/password"

# Run command with injected secrets
op run -- ./deploy.sh
op run -- npm start
op run -- docker-compose up

# Secrets are 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

# .env file with secret references
DATABASE_URL="op://Production/Postgres/connection-string"
API_KEY="op://Production/Stripe/secret-key"
JWT_SECRET="op://Production/Auth/jwt-secret"

# Run with env file
op run --env-file=.env -- npm start
op run --env-file=.env.production -- ./deploy.sh

# Multiple env files (last wins on conflicts)
op run --env-file=.env --env-file=.env.local -- npm run dev

Environment-Specific Switching

# .env with variable interpolation
DB_PASSWORD="op://$APP_ENV/database/password"
API_KEY="op://$APP_ENV/api/key"

# Switch environments via variable
APP_ENV=dev op run --env-file=.env -- npm start
APP_ENV=staging op run --env-file=.env -- npm test
APP_ENV=production op run --env-file=.env -- ./deploy.sh

Using op inject (Config Files)

For templating configuration files with secrets.

# Template file (config.yml.tpl)
database:
  host: {{ op://Production/DB/host }}
  user: {{ op://Production/DB/username }}
  pass: {{ op://Production/DB/password }}

# Inject secrets and output to file
op inject -i config.yml.tpl -o config.yml

# From stdin
echo "key: {{ op://Private/API/key }}" | op inject

# Multiple secrets concatenated
echo "postgres://{{ op://db/user }}:{{ op://db/pass }}@{{ op://db/host }}/mydb" | op inject

# With environment variable switching
echo "secret: {{ op://$ENV/app/secret }}" | ENV=prod op inject

Vault Operations

List & Search

# List all vaults
op vault list
op vault list --format json

# Get vault details
op vault get "Production"
op vault get "Production" --format json

Create & Manage

# Create vault with icon
op vault create "API Keys" --icon vault-door --description "Third-party API credentials"

# Available icons:
# airplane, application, bankers-box, buildings, castle, coffee, document,
# gears, globe, heart-with-monitor, house, id-card, plant, puzzle, shop,
# treasure-chest, vault-door, vehicle, wallet, wrench

# Edit vault
op vault edit "API Keys" --name "External APIs" --icon globe

# Delete vault
op vault delete "Old Vault"

Vault Access Management

# Grant user access
op vault user grant --vault "Production" --user [e-mail] --permissions manage_vault

# Grant group access
op vault group grant --vault "Production" --group "DevOps" --permissions manage_vault

# Revoke access
op vault user revoke --vault "Production" --user [e-mail]

Item Operations

List Items

# List all items
op item list

# Filter by vault
op item list --vault Production

# Filter by category
op item list --categories Login,Password

# Filter by tags
op item list --tags api-key,production

# Include archived items
op item list --include-archive

# Detailed list
op item list --long

# Combine filters
op item list --vault Dev --categories "API Credential" --tags active --format json

Create Items

# Login item with generated password
op item create --category Login \
  --title "Service Account" \
  --vault Production \
  --url "https://api.example.com" \
  --generate-password='letters,digits,symbols,32' \
  username=[e-mail]

# API credential
op item create --category "API Credential" \
  --title "OpenAI API" \
  --vault "API Keys" \
  api-key=sk-xxx... \
  --tags "ai,production"

# With custom section
op item create --category "Secure Note" \
  --title "Database Credentials" \
  --vault Production \
  "Connection.host=db.example.com" \
  "Connection.port=5432" \
  "Connection.database=myapp" \
  "Credentials.username=admin" \
  "Credentials.password[password]=secret123"

# SSH key (generate new)
op item create --category "SSH Key" \
  --title "Deploy Key" \
  --vault DevOps \
  --ssh-generate-key ed25519

# From JSON template
op item template get Login --out-file login.json
# Edit login.json
op item create --template login.json --vault Private

# Duplicate from another vault
op item get "Template Item" --format json | op item create --vault Production -

Edit Items

# Update field value
op item edit "GitHub" --vault Private password="new-password"

# Generate new password
op item edit "Service" --generate-password='letters,digits,32'

# Update multiple fields
op item edit "Database" \
  username="newuser" \
  password="newpass" \
  "Connection.host=newhost.example.com"

# Change field type
op item edit "Config" "api-key[password]"

# Delete custom field
op item edit "Item" "old-field[delete]"

# Update tags
op item edit "API Key" --tags "production,active,v2"

# Dry run (preview changes)
op item edit "Item" --dry-run password="test"

Delete & Archive

# Delete item
op item delete "Old API Key" --vault Archive

# Archive instead of delete
op item delete "Deprecated Key" --archive

Share Items

# Generate shareable link (expires in 7 days by default)
op item share "Shared Secret" --vault Shared

# Share with specific people
op item share "Credentials" --emails "[e-mail],[e-mail]"

# Single-view link
op item share "One-time Password" --view-once

# Custom expiration
op item share "Temp Access" --expires-in 24h

Move Items

# Move between vaults
op item move "API Key" --from-vault Dev --to-vault Production

Document Operations

# Upload document
op document create ./config.json --title "Production Config" --vault Secrets

# From stdin
cat sensitive.log | op document create - --title "Debug Log" --file-name "debug.log"

# Download document
op document get "Production Config" --vault Secrets --out-file ./config.json

# List documents
op document list --vault Secrets

# Edit document metadata
op document edit "Config" --title "New Title" --tags "config,production"

# Delete document
op document delete "Old Config" --vault Archive

Shell Plugins

Authenticate third-party CLIs securely through 1Password.

Available Plugins

# List all available plugins
op plugin list

# Common plugins:
# aws, gh (GitHub), glab (GitLab), heroku, docker, kubectl
# vercel, netlify, fly, railway, supabase
# openai, anthropic, stripe, twilio

Configure Plugin

# Initialize plugin (interactive)
op plugin init aws
op plugin init gh

# After setup, add to shell profile:
# source ~/.op/plugins.sh

# Inspect current configurations
op plugin inspect

# Clear plugin config
op plugin clear aws

Using Plugins

# After plugin setup, CLIs authenticate automatically
aws s3 ls                    # Uses 1Password for AWS credentials
gh repo list                 # Uses 1Password for GitHub token
kubectl get pods             # Uses 1Password for kubeconfig

# Run single command with plugin credentials
op plugin run -- aws s3 ls

CI/CD Integration

GitHub Actions

name: Deploy
on: push

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install 1Password CLI
        uses: 1password/install-cli-action@v1
        
      - name: Load secrets and deploy
        env:
          OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
        run: |
          op run --env-file=.env.ci -- ./deploy.sh

GitLab CI

deploy:
  image: 1password/op:2
  variables:
    OP_SERVICE_ACCOUNT_TOKEN: $OP_TOKEN
  script:
    - op run --env-file=.env.ci -- ./deploy.sh

Docker