1Password CLI Guide

1Password CLI (op) enables command-line access to secrets, vaults, items, and credential management. It supports biometric authentication, service accounts for automation, and agentic autofill for AI agent workflows. This guide provides essential workflows and quick references for common 1Password operations.

Quick Start

# Check CLI version
op --version

# Authenticate interactively
op signin

# Check current session
op whoami

# List vaults
op vault list

# List items in a vault
op item list --vault Development

# Read a specific secret
op read "op://Development/Database/password"

Common Workflows

Workflow 1: Read Secrets and Inject into Environment

# Read a single secret
DB_PASSWORD=$(op read "op://Production/Database/password")

# Run a command with secrets injected from env vars
export DB_URL="op://Production/Database/connection-string"
op run -- ./start-server.sh

# Run with secrets from .env file
op run --env-file .env.tpl -- docker compose up -d

# Inject secrets into a config template
op inject --in-file config.yml.tpl --out-file config.yml

Workflow 2: Manage Items (CRUD)

# Create a login item
op item create \
  --category=login \
  --title="Staging API" \
  --vault=Development \
  --url="https://api.staging.example.com" \
  username="admin" \
  password="secret123"

# Create with auto-generated password
op item create \
  --category=login \
  --title="New Service" \
  --generate-password='32,letters,digits,symbols'

# Get item details
op item get "Staging API" --vault=Development

# Edit an item field
op item edit "Staging API" password="new-password" --vault=Development

# Delete an item (or archive)
op item delete "Staging API" --vault=Development
op item delete "Staging API" --vault=Development --archive

Workflow 3: Service Accounts for CI/CD

# Set up service account token (provided by admin)
export OP_SERVICE_ACCOUNT_TOKEN="ops_..."

# Verify service account access
op whoami

# Read secrets in CI pipeline
op read "op://CI-CD/Deploy-Key/private-key" --out-file deploy.pem
chmod 600 deploy.pem

# Inject secrets into deploy config
op run --env-file .env.production -- ./deploy.sh

# Multi-environment with variables
ENV=staging op run -- ./deploy.sh
# Resolves op://$ENV/Database/password -> op://staging/Database/password

Workflow 4: Document and SSH Key Management

# Upload a document
op document create ./cert.pem --title="TLS Certificate" --vault=Infrastructure

# Download a document
op document get "TLS Certificate" --vault=Infrastructure --out-file cert.pem

# Read SSH private key in OpenSSH format
op read "op://Development/SSH-Key/private-key?ssh-format=openssh" --out-file id_ed25519
chmod 600 id_ed25519

# Get OTP code
op read "op://Personal/GitHub/one-time-password?attribute=otp"

Workflow 5: Agentic Autofill Setup

# Prerequisites: 1Password desktop app + browser extension installed

# 1. Create login items for services the AI agent will access
op item create \
  --category=login \
  --title="Service Dashboard" \
  --vault="Agent-Credentials" \
  --url="https://dashboard.example.com" \
  username="agent@example.com" \
  password="secure-password"

# 2. For 1Password Business: admin enables the policy
# Settings > Policies > Sharing and permissions
# Enable "Allow AI Agents to autofill for users"

# 3. Pair with Browserbase Director at director.ai
# User authenticates with 1Password during pairing

# 4. Agent requests login via natural language
# "Log in to dashboard.example.com using 1Password"
# User approves via biometric prompt in 1Password desktop app

Decision Tree

When to use which command:

• To read a single secret: Use op read "op://vault/item/field"
• To inject secrets as env vars: Use op run --env-file .env -- command
• To template config files: Use op inject --in-file template --out-file output
• To manage stored credentials: Use op item (create, get, list, edit, delete)
• To manage files/certs: Use op document (create, get, list, edit, delete)
• To manage access control: Use op vault (create, list, user/group grant/revoke)
• To automate in CI/CD: Use service accounts with OP_SERVICE_ACCOUNT_TOKEN
• To enable AI agent login: Use agentic autofill via Browserbase Director
• For detailed command syntax: See Commands Reference
• For complex scenarios: See Common Patterns
• For troubleshooting: See Troubleshooting Guide

Common Patterns

Secret References Syntax

# Basic format
op://vault/item/field

# With section
op://vault/item/section/field

# Query parameters
op://vault/item/field?attribute=otp          # OTP code
op://vault/item/file.pdf                     # File attachment
op://vault/item/key?ssh-format=openssh       # SSH key format

# Environment variable in reference (multi-env)
op://${ENV}/Database/password

Vault and Access Management

# Create vault
op vault create "Production-Secrets" --description "Production credentials"

# Grant user access
op vault user grant --vault="Production-Secrets" --user="user@example.com" --permissions=allow_viewing

# Grant group access
op vault group grant --vault="Production-Secrets" --group="DevOps" --permissions=allow_viewing,allow_editing

# List vault members
op vault user list --vault="Production-Secrets"

Output Formatting

# JSON output (default)
op item get "Database" --format=json

# Specific fields with jq
op item get "Database" --format=json | jq '.fields[] | select(.label=="password") | .value'

# List items as table
op item list --vault=Development --format=json | jq -r '.[] | [.title, .category] | @tsv'

Agentic Autofill Security Model

# End-to-end encrypted channel (Noise framework with key rotation)
# Agent CANNOT: list items, modify credentials, access without approval
# Agent CAN: request autofill (user must approve via biometric)

# Per-request approval flow:
# 1. Agent requests login to a URL
# 2. 1Password shows approval dialog with item details
# 3. User authenticates (Touch ID / Windows Hello)
# 4. Credential injected into browser form (never exposed in plaintext)
# 5. Keys rotated after each autofill operation

Troubleshooting

Common Issues:

1. Session expired

   • Solution: Run op signin to re-authenticate
   • See: Session Issues

2. Service account token invalid

   • Quick fix: Verify OP_SERVICE_ACCOUNT_TOKEN is set and not expired
   • See: Service Account Issues

3. Secret reference not found

   • Quick fix: Verify vault/item/field names with op item get "ItemName" --vault=VaultName
   • See: Secret Reference Errors

4. Permission denied on vault

   • Quick fix: Check access with op vault list and op vault user list --vault=VaultName
   • See: Permission Issues

5. Agentic autofill not working

   • Quick fix: Verify desktop app is running, extension installed, and Browserbase paired
   • See: Agentic Autofill Issues

For detailed troubleshooting steps, see the Troubleshooting Guide.

Reference Files

Load as needed for detailed information:

• Commands Reference - Complete CLI command documentation with all flags, options, and subcommands. Use when you need exact syntax or flag details for any op command.

• Common Patterns - Real-world patterns and workflows for secrets injection, CI/CD automation, multi-environment setups, agentic autofill, and team administration. Use for implementing specific workflows or integrations.

• Troubleshooting Guide - Detailed error messages, diagnosis steps, and resolution strategies for authentication, service accounts, secret references, permissions, and agentic autofill. Use when encountering errors or unexpected behavior.

When to use each reference:

• Use Commands Reference when you need exact syntax, flag combinations, or comprehensive command documentation
• Use Common Patterns for implementing CI/CD secrets injection, multi-environment workflows, or agentic autofill integration
• Use Troubleshooting when authentication fails, secrets can't be read, or agentic autofill doesn't work

Resources

• Official Docs: https://developer.1password.com/docs/cli/
• Agentic Autofill: https://developer.1password.com/docs/agentic-autofill
• CLI Reference: https://developer.1password.com/docs/cli/reference/
• Service Accounts: https://developer.1password.com/docs/service-accounts/
• Shell Plugins: https://developer.1password.com/docs/cli/shell-plugins/