1Password CLI — SKILL.md

---
name: "1Password CLI"
description: "Skill for 1Password CLI — auto-generated from documentation"
version: "1.0.0"
author: "skynet"
category: "ops"
agents: ["claude-code", "codex", "gemini"]
tags: ["1password-cli", "ops", "auto-generated"]
---

# 1Password CLI

---
name: "1Password CLI"
description: "Use when managing passwords, secrets, and secure items from the command line. Essential for automation, CI/CD pipelines, and secure secret retrieval in development workflows."
metadata:
  author: "skynet"
  version: "1.0.0"
category: "ops"
---

# 1Password CLI

## Installation & Authentication

```bash
# Install 1Password CLI
# macOS
brew install 1password-cli

# Linux
curl -sS https://downloads.1password.com/linux/keys/1password.asc | sudo gpg --dearmor --output /usr/share/keyrings/1password-archive-keyring.gpg
echo 'deb [arch=amd64 signed-by=/usr/share/keyrings/1password-archive-keyring.gpg] https://downloads.1password.com/linux/debian/amd64 stable main' | sudo tee /etc/apt/sources.list.d/1password.list
sudo apt update && sudo apt install 1password-cli

# Sign in to your account
op signin
op signin my.1password.com john.doe@example.com

# Use service accounts (for automation)
export OP_SERVICE_ACCOUNT_TOKEN="ops_ey..."
```

## Core Operations

### Managing Items

```bash
# List all items
op item list

# List items in specific vault
op item list --vault="Development"

# Get item details
op item get "GitHub Token"
op item get "uuid-of-item"

# Get specific field from item
op item get "GitHub Token" --field="password"
op item get "API Keys" --field="section.API Key"

# Create new item
op item create --category=login \
  --title="New Service" \
  --url="https://service.com" \
  username="user@example.com" \
  password="secure-password"

# Create API key item
op item create --category="api credential" \
  --title="Stripe API" \
  credential="sk_live_abc123..." \
  --vault="Production"
```

### Working with Secrets

```bash
# Retrieve password securely
PASSWORD=$(op item get "Database" --field="password")

# Use secret references (recommended for scripts)
op run -- curl -H "Authorization: Bearer op://vault/item/field" api.service.com

# Inject secrets into environment
op run --env-file=".env.op" -- npm start

# Read from secret references
echo "op://Development/API Keys/token" | op read
```

## Decision Trees

### Authentication Method Selection
```
Need CLI access?
├─ Interactive development
│  └─ Use: op signin (browser auth)
├─ CI/CD pipeline
│  └─ Use: Service Account Token
├─ Server automation
│  └─ Use: Service Account Token
└─ Local scripts
   └─ Use: op signin with session token
```

### Item Retrieval Strategy
```
Getting secrets?
├─ Single field needed
│  └─ Use: op item get "item" --field="field"
├─ Multiple fields from same item
│  └─ Use: op item get "item" --format=json | jq
├─ Inject into command
│  └─ Use: op run -- command
└─ Environment variables
   └─ Use: op run --env-file or export with $()
```

## Advanced Workflows

### Vault Management

```bash
# List all vaults
op vault list

# Get vault details
op vault get "Production"

# Create new vault
op vault create "Team Secrets" --description="Shared team credentials"

# Grant vault access
op vault user grant --vault="Development" --user="jane@company.com" --permissions="view_items"
```

### Bulk Operations

```bash
# Export vault (requires admin)
op item list --vault="Development" --format=json > dev-backup.json

# Batch field extraction
op item list --format=json | jq -r '.[] | select(.category=="LOGIN") | .title'

# Update multiple items
for item in $(op item list --tags="production" --format=json | jq -r '.[].id'); do
  op item edit "$item" --tags="production,verified"
done
```

### Integration Patterns

```bash
# Docker secrets
docker run -e "DB_PASSWORD=op://Production/Database/password" \
  $(op run -- printenv DB_PASSWORD)

# Kubernetes secrets
kubectl create secret generic api-keys \
  --from-literal=stripe="$(op item get 'Stripe' --field='key')" \
  --from-literal=github="$(op item get 'GitHub' --field='token')"

# Environment file generation
cat > .env << EOF
DATABASE_URL=op://Production/Database/connection_string
API_KEY=op://Production/API Keys/stripe
EOF
op run --env-file=.env -- env | grep -E "(DATABASE_URL|API_KEY)"
```

## Troubleshooting

### Common Authentication Issues

**Error**: `401 Unauthorized`
```bash
# Check authentication status
op whoami

# Re-authenticate
op signin --force

# For service accounts, verify token
echo $OP_SERVICE_ACCOUNT_TOKEN | cut -c1-10
```

**Error**: `item not found`
```bash
# List available items to verify name/ID
op item list --vault="vault-name"

# Use fuzzy search
op item list | grep -i "partial-name"

# Check vault access
op vault list
```

### Permission Problems

**Error**: `insufficient permissions`
```bash
# Check current user permissions
op user get --me

# Verify vault access
op vault list

# Request access (shows vault managers)
op vault get "vault-name" | jq '.vault_access'
```

### Session Management

```bash
# Check session validity
op user get --me

# Extend session
op signin --account="account.1password.com"

# Use session tokens in scripts
eval $(op signin account.1password.com)

# For automation, prefer service accounts
export OP_SERVICE_ACCOUNT_TOKEN="ops_..."
```

### Network and Sync Issues

**Error**: `network request failed`
```bash
# Test connectivity
op vault list --debug

# Check proxy settings
export HTTPS_PROXY="http://proxy:8080"
op vault list

# Force sync
op item list --cache=false
```

### Field Reference Errors

**Error**: `field not found`
```bash
# Inspect item structure
op item get "item-name" --format=json | jq '.fields'

# Check section names
op item get "item-name" --format=json | jq '.sections'

# Use correct field reference format
op item get "item" --field="section.fieldname"
# or
op item get "item" --field="fieldname"
```

## Security Best Practices

```bash
# Use secret references instead of storing in variables
# Good
op run -- curl -H "Authorization: op://vault/item/token" api.com

# Avoid
TOKEN=$(op item get "API" --field="token")
curl -H "Authorization: $TOKEN" api.com

# Clear session after use
trap 'op signout --forget' EXIT

# Use least-privilege service accounts
# Create read-only service accounts for CI/CD
op service-account create "CI Deploy" --vault="Production:read"
```