nsheaps/op

op - 1Password CLI

The 1Password CLI (op) lets you manage 1Password vaults, items, and secrets from the terminal. It integrates with shell environments to securely inject secrets without exposing them in plaintext.

Quick Reference

Authentication

# Check sign-in status
op whoami

# Sign in (interactive)
op signin

# Sign in with service account token (CI/automation)
export OP_SERVICE_ACCOUNT_TOKEN="your-token"
op whoami

# List accounts
op account list

Core Commands

| Command | Description | | ----------------- | ----------------------------------- | | op item list | List items in a vault | | op item get | Get item details | | op item create | Create a new item | | op item edit | Edit an existing item | | op item delete | Delete an item | | op vault list | List vaults | | op vault get | Get vault details | | op read | Read a secret reference | | op inject | Inject secrets into a template | | op run | Run a command with secrets injected | | op whoami | Show current user/account | | op document get | Download a document |

Secret References

1Password secret references use the format: op://vault-name/item-name/field-name

# Read a single secret
op read "op://Private/My API Key/credential"

# Read a password
op read "op://Private/My Login/password"

# Read a specific section field
op read "op://Private/Server Config/database/connection_string"

Injecting Secrets

Into Environment Variables

# Run a command with secrets injected from env template
export DB_PASSWORD="op://Private/Database/password"
export API_KEY="op://Private/API Key/credential"
op run -- my-command

# Run with env file
op run --env-file .env -- my-command

Into Config Files

# Inject secrets into a template file
op inject -i config.template.yaml -o config.yaml

# Template syntax in files:
# database:
#   password: {{ op://Private/Database/password }}

Item Management

Listing Items

# List all items
op item list

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

# List with format
op item list --format json

# Filter by category
op item list --categories "Login"
op item list --categories "API Credential"
op item list --categories "Secure Note"

# Filter by tag
op item list --tags "production"

Getting Items

# Get full item details
op item get "My Login" --vault "Private"

# Get specific field
op item get "My Login" --fields "password"

# Get as JSON
op item get "My Login" --format json

# Get by UUID
op item get "abc123def456"

# Get OTP code
op item get "My Login" --otp

Creating Items

# Create a login
op item create --category login \
  --title "New Service" \
  --vault "Private" \
  --url "https://example.com" \
  username="admin" \
  password="secret123"

# Create an API credential
op item create --category "API Credential" \
  --title "Service API Key" \
  --vault "Private" \
  credential="sk-abc123"

# Create a secure note
op item create --category "Secure Note" \
  --title "Important Note" \
  --vault "Private" \
  notesPlain="This is the note content"

# Generate a random password for new item
op item create --category login \
  --title "New Account" \
  --generate-password="20,letters,digits,symbols"

Editing Items

# Edit a field
op item edit "My Login" --vault "Private" \
  password="new-password"

# Add a tag
op item edit "My Login" --tags "production,critical"

Vault Management

# List vaults
op vault list

# Get vault details
op vault get "Private"

# Create a vault
op vault create "Team Secrets"

# List vault permissions
op vault user list "Private"

Service Accounts

Service accounts are used for CI/CD and automation:

# Set the token
export OP_SERVICE_ACCOUNT_TOKEN="ops_..."

# Use op normally — it auto-authenticates
op read "op://vault/item/field"
op run -- my-command

Service account limitations:

• Can only access vaults explicitly granted
• Cannot create/delete vaults
• Cannot manage users or groups
• Read-only by default (write access must be granted)

Common Workflows

Inject Secrets into Environment

# .env file with secret references
# DATABASE_URL=op://Private/DB/connection_string
# API_KEY=op://Private/API/credential

op run --env-file .env -- docker compose up

Use in Scripts

#!/bin/bash
DB_PASS=$(op read "op://Private/Database/password")
API_KEY=$(op read "op://Private/API Key/credential")

curl -H "Authorization: Bearer $API_KEY" https://api.example.com

Generate Passwords

# Generate a random password
op item create --category password --generate-password

# Custom password recipe
op item create --category password \
  --generate-password="30,letters,digits,symbols"

Plugin Settings

This plugin supports configuration via plugins.settings.yaml:

1pass:
  enabled: true
  autoInstall: false # Download op if not on PATH
  installToProject: true # Install to $project/bin/.local
  backgroundInstall: false # Install in background
  opVersion: "latest" # Specific op version or "latest"
  installOpExec: false # Also install op-exec
  opExecVersion: "latest" # Specific op-exec version

  # Expose entire 1Password items as environment variables
  opExec:
    items:
      - "op://MyVault/ENVIRONMENT"
    targets:
      - sessionStartBashEnv # → CLAUDE_ENV_FILE (session-scoped, bash only)
      - userSettings # → ~/.claude/settings.local.json (persistent, all tools)
    # Note: recursive resolution of op:// references is always on (op-exec built-in)

Place in:

• $CLAUDE_PROJECT_DIR/.claude/plugins.settings.yaml (project-level)
• ~/.claude/plugins.settings.yaml (user-level)

Output Targets for op-exec

The opExec.targets array controls where resolved env vars are written:

| Target | Where | Scope | Persistence | | --------------------- | -------------------------------------- | ------------------------------- | ----------------------------------- | | sessionStartBashEnv | CLAUDE_ENV_FILE | Bash tools only | Session only | | envLocal | $AGENT_HOME_DIR/.env.local | All consumers sourcing the file | Across sessions (idempotent upsert) | | userSettings | ~/.claude/settings.local.json .env | All Claude Code tools | Across sessions |

sessionStartBashEnv + userSettings are enabled by default. envLocal is opt-in and is intended for agent-home setups where a repo-templated .env sources .env.local so direnv and other consumers can pick up the vars. See the op-exec skill for details on configuring envLocal.path and envLocal.sourceChain.

Environment Variables

| Variable | Description | | -------------------------- | ---------------------------------------- | | OP_SERVICE_ACCOUNT_TOKEN | Service account token for authentication | | OP_CONNECT_HOST | 1Password Connect server URL | | OP_CONNECT_TOKEN | 1Password Connect API token | | OP_ACCOUNT | Default account shorthand | | OP_VAULT | Default vault |

Troubleshooting

"op: command not found"

Ensure op is installed. This plugin auto-installs to $CLAUDE_PROJECT_DIR/bin/.local/op when autoInstall: true. Alternatively, install via mise:

# mise.toml
[tools]
"vfox:mise-plugins/vfox-1password" = "latest"

Authentication errors

# Verify sign-in
op whoami

# Re-authenticate
op signin

# Check service account token
echo $OP_SERVICE_ACCOUNT_TOKEN | head -c 10

"You are not currently signed in"

In CI/web sessions, use a service account token:

export OP_SERVICE_ACCOUNT_TOKEN="ops_..."