1password

1Password

Overview

This skill provides comprehensive guidance for working with 1Password's secrets management ecosystem. It covers the op CLI for local development, service accounts for automation, Developer Environments for project secrets, and Kubernetes integrations including the native 1Password Operator and External Secrets Operator.

Quick Reference

Command Structure

1Password CLI uses a noun-verb structure: op <noun> <verb> [flags]

# Authentication
op signin                    # Sign in to account
op signout                   # Sign out
op whoami                    # Show signed-in account info

# Secret retrieval
op read "op://vault/item/field"              # Read single secret
op run -- <command>                          # Inject secrets as env vars
op inject -i template.env -o .env            # Inject secrets into file

# Item management
op item list                                 # List all items
op item get <item>                           # Get item details
op item create --category login              # Create new item
op item edit <item> field=value              # Edit item
op item delete <item>                        # Delete item

# Vault management
op vault list                                # List vaults
op vault get <vault>                         # Get vault info
op vault create <name>                       # Create vault

# Document management
op document list                             # List documents
op document get <document>                   # Download document
op document create <file> --vault <vault>    # Upload document

Workflow Decision Tree

What do you need to do?
├── Retrieve a secret for local development?
│   └── Use: op read, op run, or op inject
├── Manage project environment variables?
│   └── See: Developer Environments (below)
├── Manage items/vaults in 1Password?
│   └── Use: op item, op vault, op document commands
├── Automate secrets in CI/CD?
│   └── Use: Service Accounts with OP_SERVICE_ACCOUNT_TOKEN
├── Sync secrets to Kubernetes?
│   ├── Using External Secrets Operator?
│   │   └── See: External Secrets Operator Integration
│   └── Using native 1Password Operator?
│       └── See: 1Password Kubernetes Operator
└── Configure shell plugins for CLI tools?
    └── Use: op plugin commands

Developer Environments

Developer Environments provide a dedicated location to store, organize, and manage project secrets as environment variables. CLI tools are available in both TypeScript/Bun and Python SDK variants.

Feature Overview

CLI Tools Setup (TypeScript)

Tools are written in TypeScript and require Bun runtime:

# Navigate to tools directory
cd tools

# Run any tool with bun
bun run src/op-env-create.ts --help
bun run src/op-env-list.ts --help

# Or use npm scripts
bun run create -- --help
bun run list -- --help

CLI Tools Setup (Python SDK)

Python tools use the official onepassword-sdk package and require uv:

# Navigate to tools-python directory
cd tools-python

# Install dependencies
uv sync

# Run any tool
uv run op-env-create --help
uv run op-env-list --help

Requirements: Python 3.9+, OP_SERVICE_ACCOUNT_TOKEN environment variable.

When to Use SDK vs CLI

SecretsManager (Python SDK)

For Python applications that need runtime secret resolution:

from op_env.secrets_manager import SecretsManager

async def main():
    sm = await SecretsManager.create()

    # Single secret (with caching)
    api_key = await sm.get("op://Production/API/key")

    # Batch resolve
    secrets = await sm.get_many([
        "op://Production/DB/password",
        "op://Production/DB/host",
    ])

    # Load all vars from an environment item
    env = await sm.resolve_environment("my-app-prod", "Production")

See references/python-sdk.md for full SDK reference and integration patterns.

Environment Workflow

1. Create Environment

# From inline variables
bun run src/op-env-create.ts my-app-dev Personal \
    API_KEY=secret \
    DB_HOST=localhost \
    DB_PORT=5432

# From .env file
bun run src/op-env-create.ts my-app-prod Production --from-file .env.prod

# Combine file + inline (inline overrides file)
bun run src/op-env-create.ts azure-config Shared --from-file .env EXTRA_KEY=value

# With custom tags
bun run src/op-env-create.ts secrets DevOps --tags "env,production,api" KEY=value

2. List Environments

# List all environments (tagged with 'environment')
bun run src/op-env-list.ts

# Filter by vault
bun run src/op-env-list.ts --vault Personal

# Filter by tags
bun run src/op-env-list.ts --tags "production"

# JSON output
bun run src/op-env-list.ts --json

3. Show Environment Details

# Show with masked values (default)
bun run src/op-env-show.ts my-app-dev Personal

# Show with revealed values
bun run src/op-env-show.ts my-app-dev Personal --reveal

# JSON output
bun run src/op-env-show.ts my-app-dev Personal --json

# Show only variable names
bun run src/op-env-show.ts my-app-dev Personal --keys

4. Update Environment

# Update/add single variable
bun run src/op-env-update.ts my-app-dev Personal API_KEY=new-key

# Merge from .env file
bun run src/op-env-update.ts my-app-dev Personal --from-file .env.local

# Remove variables
bun run src/op-env-update.ts my-app-dev Personal --remove OLD_KEY,DEPRECATED

# Update and remove in one command
bun run src/op-env-update.ts my-app-dev Personal NEW_KEY=value --remove OLD_KEY

5. Export Environment

# Export to .env file (standard format)
bun run src/op-env-export.ts my-app-dev Personal > .env

# Docker-compatible format (quoted values)
bun run src/op-env-export.ts my-app-dev Personal --format docker > .env

# op:// references template (for op run/inject)
bun run src/op-env-export.ts my-app-dev Personal --format op-refs > .env.tpl

# JSON format
bun run src/op-env-export.ts my-app-dev Personal --format json

# Add prefix to all variables
bun run src/op-env-export.ts azure-config Shared --prefix AZURE_ > .env

6. Delete Environment

# Interactive deletion (asks for confirmation)
bun run src/op-env-delete.ts my-app-dev Personal

# Force delete without confirmation
bun run src/op-env-delete.ts my-app-dev Personal --force

# Archive instead of permanent delete
bun run src/op-env-delete.ts my-app-dev Personal --archive

Environment Secret Reference

Access individual variables using the secret reference format:

op://<vault>/<environment>/variables/<key>

Example:

# Read single variable
op read "op://Personal/my-app-dev/variables/API_KEY"

# Use in template file (.env.tpl)
API_KEY=op://Personal/my-app-dev/variables/API_KEY
DB_HOST=op://Personal/my-app-dev/variables/DB_HOST

Integration Patterns

With op run (recommended)

# 1. Export environment as op:// template
bun run src/op-env-export.ts my-app-dev Personal --format op-refs > .env.tpl

# 2. Run command with injected secrets
op run --env-file .env.tpl -- ./deploy.sh
op run --env-file .env.tpl -- docker compose up
op run --env-file .env.tpl -- npm start
op run --env-file .env.tpl -- python app.py

With op inject

# 1. Create template with op:// references
bun run src/op-env-export.ts my-app-dev Personal --format op-refs > config.tpl

# 2. Inject secrets into file
op inject -i config.tpl -o .env

# 3. Use the generated .env file
source .env && ./app

With Docker Compose

# 1. Export environment
bun run src/op-env-export.ts my-app-dev Personal --format op-refs > .env.tpl

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

In CI/CD (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
        uses: 1password/load-secrets-action@v2
        with:
          export-env: true
        env:
          OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
          API_KEY: op://CI-CD/my-app-prod/variables/API_KEY
          DB_PASSWORD: op://CI-CD/my-app-prod/variables/DB_PASSWORD

      - name: Deploy
        run: ./deploy.sh

Current Environments (Barbosa Account)

See references/environments/inventory.md for detailed documentation.

Secret Retrieval

Secret Reference Format

The standard format for referencing secrets:

op://<vault>/<item>/<field>

Examples:

• op://Development/AWS/access_key_id
• op://Production/Database/password
• op://Shared/API Keys/github_token

Reading Secrets Directly

# Read a specific field
op read "op://Development/AWS/access_key_id"

# Read with JSON output
op item get "AWS" --vault Development --format json

# Read specific field from item
op item get "AWS" --vault Development --fields access_key_id

Injecting Secrets into Commands

The op run command injects secrets as environment variables:

# Run command with secrets
op run --env-file=.env.tpl -- ./deploy.sh

# Example .env.tpl file:
# AWS_ACCESS_KEY_ID=op://Development/AWS/access_key_id
# AWS_SECRET_ACCESS_KEY=op://Development/AWS/secret_access_key

Injecting Secrets into Files

The op inject command replaces secret references in template files:

# Inject secrets from template to output file
op inject -i config.tpl.yaml -o config.yaml

# Example config.tpl.yaml:
# database:
#   host: localhost
#   password: op://Production/Database/password

Item Management

Creating Items

# Create a login item
op item create --category login \
  --title "My Service" \
  --vault Development \
  username=admin \
  password=secretpassword

# Create with generated password
op item create --category login \
  --title "New Account" \
  --generate-password

# Create from JSON template
op item create --template item.json

Item Template (JSON)

{
  "title": "my-service-credentials",
  "vault": {"id": "vault-uuid-or-name"},
  "category": "LOGIN",
  "fields": [
    {"label": "username", "value": "admin", "type": "STRING"},
    {"label": "password", "value": "secret", "type": "CONCEALED"},
    {"label": "api_key", "value": "key123", "type": "CONCEALED"}
  ]
}

Editing Items

# Edit a field
op item edit "My Service" password=newpassword

# Add a new field
op item edit "My Service" api_key=newkey

# Edit with specific vault
op item edit "My Service" --vault Development password=newpassword

Service Accounts

Service accounts enable automation without personal credentials.

Prerequisites

• 1Password CLI version 2.18.0 or later
• Active 1Password subscription
• Admin permissions to create service accounts

Creating Service Accounts

Via CLI:

# Create with read-only access
op service-account create "CI/CD Pipeline" \
  --vault Production:read_items

# Create with write access
op service-account create "Deployment Bot" \
  --vault Production:read_items,write_items

# Create with vault creation permission
op service-account create "Provisioning Bot" \
  --vault Production:read_items,write_items \
  --can-create-vaults

Using Service Accounts

Export the service account token:

export OP_SERVICE_ACCOUNT_TOKEN="ops_..."

Then use normal CLI commands - they automatically authenticate with the service account.

Service Account Limitations

• Cannot access Personal, Private, Employee, or default Shared vaults
• Permissions cannot be modified after creation
• Limited to 100 service accounts per account
• Subject to rate limits

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
        uses: 1password/load-secrets-action@v2
        with:
          export-env: true
        env:
          OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
          AWS_ACCESS_KEY_ID: op://CI-CD/AWS/access_key_id
          AWS_SECRET_ACCESS_KEY: op://CI-CD/AWS/secret_access_key

      - name: Deploy
        run: ./deploy.sh

GitLab CI

deploy:
  image: 1password/op:2
  variables:
    OP_SERVICE_ACCOUNT_TOKEN: $OP_SERVICE_ACCOUNT_TOKEN
  script:
    - export AWS_ACCESS_KEY_ID=$(op read "op://CI-CD/AWS/access_key_id")
    - export AWS_SECRET_ACCESS_KEY=$(op read "op://CI-CD/AWS/secret_access_key")
    - ./deploy.sh

CircleCI

version: 2.1
orbs:
  onepassword: onepassword/secrets@1

jobs:
  deploy:
    docker:
      - image: cimg/base:stable
    steps:
      - checkout
      - onepassword/exec:
          command: ./deploy.sh
          env:
            AWS_ACCESS_KEY_ID: op://CI-CD/AWS/access_key_id
            AWS_SECRET_ACCESS_KEY: op://CI-CD/AWS/secret_access_key

External Secrets Operator Integration

External Secrets Operator (ESO) syncs secrets from 1Password to Kubernetes.

Prerequisites

1. 1Password Connect Server (v1.5.6+) 2. Credentials file (1password-credentials.json) 3. Access token for authentication 4. External Secrets Operator installed in cluster

Connect Server Setup

# Create automation environment and get credentials
# This generates 1password-credentials.json and an access token

# Create Kubernetes secret for Connect Server credentials
kubectl create secret generic onepassword-credentials \
  --from-file=1password-credentials.json

# Create secret for access token
kubectl create secret generic onepassword-token \
  --from-literal=token=your-access-token

Deploy Connect Server

apiVersion: apps/v1
kind: Deployment
metadata:
  name: onepassword-connect
spec:
  replicas: 1
  selector:
    matchLabels:
      app: onepassword-connect
  template:
    metadata:
      labels:
        app: onepassword-connect
    spec:
      containers:
        - name: connect-api
          image: 1password/connect-api:latest
          ports:
            - containerPort: 8080
          volumeMounts:
            - name: credentials
              mountPath: /home/opuser/.op/1password-credentials.json
              subPath: 1password-credentials.json
      volumes:
        - name: credentials
          secret:
            secretName: onepassword-credentials
---
apiVersion: v1
kind: Service
metadata:
  name: onepassword-connect
spec:
  selector:
    app: onepassword-connect
  ports:
    - port: 8080
      targetPort: 8080

ClusterSecretStore Configuration

apiVersion: external-secrets.io/v1
kind: ClusterSecretStore
metadata:
  name: onepassword
spec:
  provider:
    onepassword:
      connectHost: http://onepassword-connect:8080
      vaults:
        production: 1
        staging: 2
      auth:
        secretRef:
          connectTokenSecretRef:
            name: onepassword-token
            namespace: external-secrets
            key: token

ExternalSecret Examples

Basic secret retrieval:

apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: database-credentials
spec:
  refreshInterval: 1h
  secretStoreRef:
    kind: ClusterSecretStore
    name: onepassword
  target:
    name: database-credentials
    creationPolicy: Owner
  data:
    - secretKey: username
      remoteRef:
        key: Database             # Item title in 1Password
        property: username        # Field label
    - secretKey: password
      remoteRef:
        key: Database
        property: password

Using dataFrom with regex:

apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: env-config
spec:
  refreshInterval: 1h
  secretStoreRef:
    kind: ClusterSecretStore
    name: onepassword
  target:
    name: app-env
  dataFrom:
    - find:
        path: app-config          # Item title
        name:
          regexp: "^[A-Z_]+$"     # Match all uppercase env vars

PushSecret (Kubernetes to 1Password)

apiVersion: external-secrets.io/v1alpha1
kind: PushSecret
metadata:
  name: push-generated-secret
spec:
  refreshInterval: 1h
  secretStoreRefs:
    - name: onepassword
      kind: ClusterSecretStore
  selector:
    secret:
      name: generated-credentials
  data:
    - match:
        secretKey: api-key
        remoteRef:
          remoteKey: generated-api-key
          property: password
      metadata:
        apiVersion: kubernetes.external-secrets.io/v1alpha1
        kind: PushSecretMetadata
        spec:
          vault: production
          tags:
            - generated
            - kubernetes

1Password Kubernetes Operator

The native 1Password Operator provides direct integration without External Secrets Operator.

Installation via Helm

helm repo add 1password https://1password.github.io/connect-helm-charts
helm install connect 1password/connect \
  --set-file connect.credentials=1password-credentials.json \
  --set operator.create=true \
  --set operator.token.value=your-access-token

OnePasswordItem CRD

apiVersion: onepassword.com/v1
kind: OnePasswordItem
metadata:
  name: database-secret
spec:
  itemPath: "vaults/Production/items/Database"

This creates a Kubernetes Secret named database-secret with all fields from the 1Password item.

Auto-Restart Configuration

Enable automatic deployment restarts when secrets change:

# Operator-level (environment variable)
AUTO_RESTART=true

# Namespace-level (annotation)
apiVersion: v1
kind: Namespace
metadata:
  name: production
  annotations:
    operator.1password.io/auto-restart: "true"

# Deployment-level (annotation)
apiVersion: apps/v1
kind: Deployment
metadata:
  annotations:
    operator.1password.io/auto-restart: "true"

Shell Plugins

Shell plugins enable automatic authentication for third-party CLIs.

Available Plugins

# List available plugins
op plugin list

# Common plugins: aws, gh, stripe, vercel, fly, etc.

Plugin Setup

# Initialize AWS plugin
op plugin init aws

# This configures shell aliases to use 1Password for AWS credentials
# Add to your shell profile as instructed

Git Workflow with 1Password

Use 1Password to manage GitHub authentication for git operations (push, pull, clone).

Quick Setup

Run the setup script to configure everything:

./scripts/setup-gh-plugin.sh

Manual Setup

Step 1: Initialize the gh plugin

# Sign in to 1Password
op signin

# Initialize gh plugin (interactive - select your GitHub token)
op plugin init gh

Step 2: Configure git credential helper

# Remove any broken credential helpers
git config --global --unset-all credential.https://github.com.helper 2>/dev/null

# Set gh as the credential helper for GitHub
git config --global credential.https://github.com.helper '!/opt/homebrew/bin/gh auth git-credential'
git config --global credential.https://gist.github.com.helper '!/opt/homebrew/bin/gh auth git-credential'

Step 3: Add shell integration

Add to your ~/.zshrc or ~/.bashrc:

# 1Password CLI plugins
source ~/.config/op/plugins.sh

How It Works

┌─────────────────────────────────────────────────────────────────┐
│                        Git Push Workflow                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   git push                                                       │
│      │                                                           │
│      ▼                                                           │
│   Git credential helper                                          │
│      │                                                           │
│      ▼                                                           │
│   gh auth git-credential                                         │
│      │                                                           │
│      ▼                                                           │
│   1Password plugin (via op wrapper)                              │
│      │                                                           │
│      ▼                                                           │
│   1Password (biometric/password unlock)                          │
│      │                                                           │
│      ▼                                                           │
│   Token retrieved and passed to git                              │
│      │                                                           │
│      ▼                                                           │
│   Push completes successfully                                    │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Multiple GitHub Accounts

If you work with multiple GitHub accounts, you can configure per-repo credentials:

# For a specific repo, use a different 1Password item
cd /path/to/work-repo
git config credential.https://github.com.helper '!/opt/homebrew/bin/gh auth git-credential'

# Or use includeIf in ~/.gitconfig for path-based selection
[includeIf "gitdir:~/work/"]
    path = ~/.gitconfig-work

Fixing Common Issues

"Item not found in vault" error

This means the 1Password plugin is pointing to a deleted token:

# Remove the broken plugin configuration
rm ~/.config/op/plugins/used_items/gh.json

# Re-initialize
op plugin init gh

gh aliased to op plugin run

If gh is aliased to run through 1Password but failing:

# Check the alias
which gh  # Shows: gh: aliased to op plugin run -- gh

# Run gh directly to bypass the alias
/opt/homebrew/bin/gh auth status

Git prompting for username/password

Verify the credential helper is configured:

git config --list | grep credential

Should show:

credential.https://github.com.helper=!/opt/homebrew/bin/gh auth git-credential

Troubleshooting

Common Issues

Authentication fails:

# Check current session
op whoami

# Sign in again
op signin

# For service accounts, verify token
echo $OP_SERVICE_ACCOUNT_TOKEN | head -c 10

Item not found:

# List items in vault to verify name
op item list --vault "Vault Name"

# Use item ID instead of name for reliability
op item get --vault Development dh7fjsh3kd8fjs

Permission denied in CI/CD:

# Verify service account has access to vault
op vault list  # Should show accessible vaults

# Check rate limits
op service-account ratelimit

External Secrets not syncing:

# Check ExternalSecret status
kubectl describe externalsecret <name>

# Check Connect Server logs
kubectl logs -l app=onepassword-connect

# Verify SecretStore connection
kubectl describe secretstore <name>

Best Practices

1. Use secret references (op://) instead of hardcoding vault/item names in scripts 2. Prefer service accounts over personal accounts for automation 3. Scope permissions minimally - grant only necessary vault access 4. Use item IDs in scripts for stability (names can change) 5. Rotate service account tokens when sign-in addresses change 6. Enable auto-restart in Kubernetes for seamless secret rotation 7. Use separate vaults per environment (dev, staging, prod) 8. Tag items for organization and filtering

Resources

References

• references/cli-commands.md - Complete CLI command reference
• references/kubernetes-examples.md - Kubernetes manifest examples
• references/python-sdk.md - Python SDK reference and integration guide
• references/environments/README.md - Developer Environments guide
• references/environments/inventory.md - Current environments inventory

Tools

Environment management CLI tools in TypeScript and Python:

TypeScript requirements: Bun runtime Python requirements: Python 3.9+, uv, OP_SERVICE_ACCOUNT_TOKEN

# TypeScript tools
cd tools && bun run src/op-env-list.ts --help

# Python SDK tools
cd tools-python && uv sync && uv run op-env-list --help

Templates

Environment and integration templates (in templates/):

Scripts

• scripts/setup-gh-plugin.sh - Setup GitHub CLI with 1Password integration
• scripts/setup-service-account.sh - Create and configure a service account
• scripts/sync-check.sh - Verify External Secrets synchronization

External Documentation

• 1Password CLI Documentation
• Service Accounts Guide
• Developer Environments
• Local .env Files
• Kubernetes Operator
• External Secrets Provider

---

Gotchas

• Service Account vs Connect Server vs CLI auth modes differ in rate limits, vault visibility, and cred shape — a script using op interactively won't necessarily work as a service-account token.
• `op inject` evaluates `op://...` refs at render time — templates checked into git are safe; rendered output never goes near git.
• CLI biometric prompt unless `OP_DEVICE` is set — CI containers without that env var fail silently as if there were no secrets.
• Shell plugin (`op plugin init`) sources at shell start — plugin updates don't apply until you open a new shell.
• `op read op://vault/item/field` returns the FIRST match across duplicates — items with the same field name resolve by lexicographic order, not creation date.

1Password CLI Command Reference

Complete reference for all op CLI commands and their options.

Authentication Commands

op signin

Sign in to a 1Password account.

op signin [account-shorthand]
op signin --raw                    # Output session token only
op signin --force                  # Force re-authentication

op signout

Sign out of a 1Password account.

op signout                         # Sign out of current account
op signout --all                   # Sign out of all accounts
op signout --forget                # Remove account from local config

op whoami

Display information about the signed-in account.

op whoami                          # Show account info
op whoami --format json            # JSON output

Secret Operations

op read

Read a secret using a secret reference.

op read "op://vault/item/field"
op read "op://vault/item/field" --no-newline    # No trailing newline
op read "op://vault/item/field" --force         # Skip confirmation prompts

op run

Run a command with secrets injected as environment variables.

op run -- command [args]
op run --env-file .env.tpl -- command
op run --no-masking -- command      # Don't mask secrets in output

op inject

Inject secrets into a template file.

op inject -i template.env -o output.env
op inject -i template.yaml          # Output to stdout
op inject --in-file template --out-file output
op inject --force                   # Overwrite existing output

Item Commands

op item list

List items in vaults.

op item list
op item list --vault "Vault Name"
op item list --categories login,password
op item list --tags "production,api"
op item list --format json
op item list --favorite              # Only favorites
op item list --include-archive       # Include archived items

op item get

Get details of a specific item.

op item get "Item Name"
op item get "Item Name" --vault "Vault Name"
op item get "Item Name" --fields label=password
op item get "Item Name" --fields password,username
op item get "Item Name" --format json
op item get "Item Name" --reveal     # Show concealed fields
op item get itemid                   # By ID (more reliable)

op item create

Create a new item.

# Basic login
op item create --category login --title "My Service" \
  --vault "Development" \
  username=admin password=secret

# With generated password
op item create --category login --title "New Account" \
  --generate-password

# With specific password recipe
op item create --category login --title "Secure Service" \
  --generate-password="letters,digits,symbols,32"

# From template file
op item create --template item.json

# Categories: login, password, identity, credit_card, secure_note,
#            document, bank_account, database, email_account,
#            wireless_router, server, software_license, api_credential

op item edit

Edit an existing item.

op item edit "Item Name" field=newvalue
op item edit "Item Name" --vault "Vault" password=newsecret
op item edit "Item Name" "section.field=value"
op item edit "Item Name" --title "New Title"
op item edit "Item Name" --generate-password
op item edit "Item Name" --favorite
op item edit "Item Name" --tags "tag1,tag2"

op item delete

Delete an item.

op item delete "Item Name"
op item delete "Item Name" --vault "Vault"
op item delete "Item Name" --archive    # Archive instead of delete

op item share

Share an item.

op item share "Item Name"                       # Generate share link
op item share "Item Name" --expiry 1h           # 1 hour expiry
op item share "Item Name" --expiry 7d           # 7 days expiry
op item share "Item Name" --view-once           # Single view only
op item share "Item Name" --emails user@example.com

op item move

Move an item between vaults.

op item move "Item Name" --current-vault "Source" --destination-vault "Dest"

Vault Commands

op vault list

List accessible vaults.

op vault list
op vault list --format json
op vault list --group "Group Name"

op vault get

Get details of a vault.

op vault get "Vault Name"
op vault get "Vault Name" --format json

op vault create

Create a new vault.

op vault create "New Vault"
op vault create "New Vault" --description "Description"
op vault create "New Vault" --icon "airplane"
op vault create "New Vault" --allow-admins-to-manage false

op vault edit

Edit a vault.

op vault edit "Vault Name" --name "New Name"
op vault edit "Vault Name" --description "New description"
op vault edit "Vault Name" --icon "key"

op vault delete

Delete a vault.

op vault delete "Vault Name"

Document Commands

op document list

List documents.

op document list
op document list --vault "Vault Name"
op document list --format json

op document get

Download a document.

op document get "Document Name"              # To stdout
op document get "Document Name" --out-file path/to/file
op document get "Document Name" --vault "Vault"

op document create

Upload a document.

op document create path/to/file --vault "Vault"
op document create path/to/file --title "Custom Title" --vault "Vault"
op document create path/to/file --tags "tag1,tag2"

op document edit

Replace a document.

op document edit "Document Name" --vault "Vault" path/to/newfile
op document edit "Document Name" --title "New Title"

op document delete

Delete a document.

op document delete "Document Name"
op document delete "Document Name" --vault "Vault"
op document delete "Document Name" --archive

Account Management

op account list

List configured accounts.

op account list
op account list --format json

op account get

Get account details.

op account get
op account get --format json

op account add

Add an account.

op account add --address example.1password.com
op account add --address example.1password.com --email user@example.com

op account forget

Remove an account from local configuration.

op account forget example

Service Account Commands

op service-account create

Create a service account.

# Read-only access
op service-account create "CI Pipeline" \
  --vault Production:read_items

# Read and write access
op service-account create "Deploy Bot" \
  --vault Production:read_items,write_items \
  --vault Staging:read_items,write_items

# With vault creation permission
op service-account create "Provisioner" \
  --vault Production:read_items,write_items \
  --can-create-vaults

# Permissions: read_items, write_items, share_items

op service-account ratelimit

Check service account rate limits.

op service-account ratelimit

User Commands

op user list

List users in account.

op user list
op user list --group "Group Name"
op user list --vault "Vault Name"
op user list --format json

op user get

Get user details.

op user get user@example.com
op user get --me

op user provision

Provision a new user.

op user provision --email user@example.com --name "User Name"

op user edit

Edit a user.

op user edit user@example.com --name "New Name"
op user edit user@example.com --travel-mode on

op user delete

Delete/suspend a user.

op user delete user@example.com
op user suspend user@example.com

Group Commands

op group list

List groups.

op group list
op group list --vault "Vault Name"
op group list --format json

op group get

Get group details.

op group get "Group Name"
op group get "Group Name" --format json

op group create

Create a group.

op group create "New Group"
op group create "New Group" --description "Description"

op group edit

Edit a group.

op group edit "Group Name" --name "New Name"
op group edit "Group Name" --description "New description"

op group delete

Delete a group.

op group delete "Group Name"

op group user

Manage group membership.

op group user grant --group "Group" --user user@example.com
op group user revoke --group "Group" --user user@example.com
op group user list --group "Group"

Connect Server Commands

op connect server list

List Connect servers.

op connect server list

op connect server get

Get Connect server details.

op connect server get "Server Name"

op connect server create

Create a Connect server.

op connect server create "Server Name" --vault "Vault1" --vault "Vault2"

op connect server edit

Edit a Connect server.

op connect server edit "Server Name" --name "New Name"

op connect server delete

Delete a Connect server.

op connect server delete "Server Name"

op connect token create

Create a Connect token.

op connect token create "Token Name" --server "Server Name" --vault "Vault"

op connect token list

List Connect tokens.

op connect token list --server "Server Name"

op connect token delete

Delete a Connect token.

op connect token delete "Token Name" --server "Server Name"

Shell Plugin Commands

op plugin list

List available plugins.

op plugin list

op plugin init

Initialize a plugin.

op plugin init aws
op plugin init gh
op plugin init stripe

op plugin run

Run a command with plugin credentials.

op plugin run -- aws s3 ls

Utility Commands

op completion

Generate shell completion scripts.

op completion bash
op completion zsh
op completion fish
op completion powershell

op update

Check for and apply updates.

op update
op update --check        # Check only, don't install

op --version

Display version information.

op --version

Global Flags

These flags work with most commands:

--account         # Specify account shorthand
--cache           # Enable/disable caching
--config          # Config directory path
--debug           # Enable debug output
--encoding        # Output encoding (utf-8, shift_jis)
--format          # Output format (json, human-readable)
--iso-timestamps  # Use ISO 8601 timestamps
--no-color        # Disable color output
--session         # Session token to use

Environment Variables

OP_SERVICE_ACCOUNT_TOKEN    # Service account authentication
OP_CONNECT_TOKEN            # Connect server token
OP_CONNECT_HOST             # Connect server URL
OP_SESSION_*                # Session tokens per account
OP_BIOMETRIC_UNLOCK_ENABLED # Enable biometric unlock
OP_DEVICE                   # Device UUID
OP_CONFIG_DIR               # Config directory location
OP_CACHE_DIR                # Cache directory location
OP_LOG_LEVEL                # Logging level (debug, info, warn, error)

Secret Reference Format

The canonical format for referencing secrets:

op://<vault>/<item>[/<section>]/<field>

Components:

• vault - Vault name or ID
• item - Item name or ID
• section - Optional section name
• field - Field label or ID

Examples:

op://Development/AWS/access_key_id
op://Production/Database/credentials/password
op://Shared/API Keys/github_token
op://vault-uuid/item-uuid/field-uuid

Item Categories

Available categories for op item create --category:

Field Types

Available field types when creating items:

1Password Developer Environments Inventory

Overview

This document tracks all Developer Environments configured in 1Password under the Barbosa account.

Account: Barbosa Last Updated: 2026-02-19 Vault: hypera (service account access)

Current Environments

Environment Categories

Azure Environments

• hypera-azure-rg-hypera-cafehyna-web-dev - Development Azure resources
• hypera-azure-rg-hypera-cafehyna-web - Production Azure resources
• hypera-azure-devops-team-az-cli-pim - Azure CLI with PIM integration
• Azure OpenAI-finops - Azure OpenAI service configuration
• devops-team-azure-quota-automation - Azure quota automation

Kubernetes / Infrastructure

• rg-hypera-aks-python-infra-dev - AKS Python infrastructure dev

GitHub Environments

• hypera-github-python-devops - Python DevOps automation
• repos-github-zsh - ZSH dotfiles repository

Team Environments

• devops-team-pim - DevOps team PIM credentials
• hypera-azure-devops-team-az-cli-pim - Azure DevOps AZ CLI PIM

General

• hypera - General infrastructure credentials
• .dotfiles - Dotfiles configuration
• devops-team-azure-quota-automation - Quota automation

CLI Management

All environments were created via CLI using op item create with:

• Category: API Credential
• Tag: environment
• Vault: hypera
• Initial variable: PLACEHOLDER=initialized (replace with real values)

Populate Variables

Add real variables to replace the placeholder:

# Edit environment to add real variables
op item edit "<env-name>" --vault hypera \
  variables.MY_KEY[concealed]=my-value \
  variables.PLACEHOLDER[delete]

Access via CLI Tools

cd ~/.claude/skills/1password-skill/tools
# OR
cd .claude/skills/1password-skill/tools

# List all environments
bun run list --vault hypera

# Show environment details
bun run show "hypera" hypera

# Export to .env file
bun run export "hypera-azure-rg-hypera-cafehyna-web-dev" hypera > .env

# Create op:// reference
op read "op://hypera/<env-name>/variables/<KEY>"

Direct CLI Access

# Read specific variable
op read "op://hypera/hypera/variables/API_KEY"

# Use with op run
op run --env-file .env.tpl -- ./deploy.sh

# List all environment items
op item list --vault hypera --tags environment --format json | jq '.[].title'

Secret References Format

All variables use the format:

op://hypera/<env-name>/variables/<KEY>

Examples:

• op://hypera/hypera/variables/API_KEY
• op://hypera/devops-team-pim/variables/AZURE_CLIENT_ID
• op://hypera/Azure OpenAI-finops/variables/OPENAI_API_KEY

Notes

• All environments created 2026-02-19 via CLI (service account access to hypera vault)
• Initial PLACEHOLDER=initialized variable should be replaced with real values
• Developer Environments is a beta feature in 1Password (GUI-native type different from CLI API Credential items)
• CLI items use API Credential category + environment tag as the programmatic equivalent
• Use op-env-update to add variables once values are known

Developer Environments Reference

Overview

1Password Developer Environments provide a dedicated location to store, organize, and manage project secrets as environment variables. This reference covers both the native GUI feature and CLI tools.

Feature Status

CLI Tools

Tools are written in TypeScript and require Bun runtime.

Setup

# Navigate to tools directory
cd tools

# Run any tool
bun run src/op-env-list.ts --help

Available Tools

Quick Start

Create Environment

cd tools

# From inline variables
bun run src/op-env-create.ts my-app-dev Personal \
    API_KEY=secret123 \
    DB_HOST=localhost \
    DB_PORT=5432

# From .env file
bun run src/op-env-create.ts my-app-prod Production \
    --from-file .env.production

Update Environment

# Update single variable
bun run src/op-env-update.ts my-app-dev Personal API_KEY=new-key

# Merge from file
bun run src/op-env-update.ts my-app-dev Personal --from-file .env.local

# Remove variables
bun run src/op-env-update.ts my-app-dev Personal --remove OLD_KEY,DEPRECATED

View & Export

# List all environments
bun run src/op-env-list.ts

# Show details (masked)
bun run src/op-env-show.ts my-app-dev Personal

# Show with values
bun run src/op-env-show.ts my-app-dev Personal --reveal

# Export to .env
bun run src/op-env-export.ts my-app-dev Personal > .env

# Export as template
bun run src/op-env-export.ts my-app-dev Personal --format op-refs > .env.tpl

Delete Environment

# Interactive
bun run src/op-env-delete.ts old-app Personal

# Force delete
bun run src/op-env-delete.ts old-app Personal --force

# Archive instead
bun run src/op-env-delete.ts old-app Personal --archive

Storage Model

CLI tools store environments as API Credential items with:

• Category: API Credential
• Tags: environment (configurable)
• Section: variables (contains all env vars)
• Field Type: CONCEALED (for all values)

Secret Reference Format

op://<vault>/<environment-name>/variables/<key>

Example:

op://Personal/my-app-dev/variables/API_KEY

Integration Patterns

With op run

# Create template
bun run src/op-env-export.ts my-app Production --format op-refs > .env.tpl

# Run command with injected secrets
op run --env-file .env.tpl -- ./deploy.sh

With op inject

# Create template
bun run src/op-env-export.ts my-app Production --format op-refs > config.tpl

# Inject secrets into file
op inject -i config.tpl -o config.env

In CI/CD

# GitHub Actions example
- name: Load secrets
  run: |
    bun run src/op-env-export.ts ci-secrets CI-CD > .env
  env:
    OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}

Best Practices

1. Naming Convention: Use project-environment format (e.g., myapp-dev, myapp-prod) 2. Tagging: Always use environment tag for discoverability 3. Vault Organization: Separate vaults per environment or team 4. Access Control: Use 1Password groups for team access 5. Templates: Use --format op-refs for CI/CD pipelines

Limitations

1. GUI-Only Features:

• Local .env file mounting (requires desktop app)
• AWS Secrets Manager sync

2. CLI Workarounds:

• Tools use API Credential category (not native Environment type)
• No direct mapping to GUI Environments view
• Manual sync between GUI environments and CLI items

Related Documentation

• inventory.md - Current environments inventory
• cli-commands.md - Full CLI reference
• 1Password Environments Docs

1Password Kubernetes Integration Examples

Complete Kubernetes manifest examples for integrating 1Password with Kubernetes using either External Secrets Operator or the native 1Password Kubernetes Operator.

External Secrets Operator Integration

Connect Server Deployment

Deploy the 1Password Connect Server that ESO will communicate with.

apiVersion: v1
kind: Namespace
metadata:
  name: onepassword-system
---
apiVersion: v1
kind: Secret
metadata:
  name: onepassword-credentials
  namespace: onepassword-system
type: Opaque
data:
  # Base64 encoded 1password-credentials.json
  1password-credentials.json: <base64-encoded-credentials>
---
apiVersion: v1
kind: Secret
metadata:
  name: onepassword-token
  namespace: onepassword-system
type: Opaque
stringData:
  token: <your-connect-access-token>
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: onepassword-connect
  namespace: onepassword-system
spec:
  replicas: 1
  selector:
    matchLabels:
      app: onepassword-connect
  template:
    metadata:
      labels:
        app: onepassword-connect
    spec:
      containers:
        - name: connect-api
          image: 1password/connect-api:1.7.2
          ports:
            - containerPort: 8080
              name: http
          env:
            - name: OP_SESSION
              valueFrom:
                secretKeyRef:
                  name: onepassword-credentials
                  key: 1password-credentials.json
          resources:
            requests:
              memory: "64Mi"
              cpu: "100m"
            limits:
              memory: "256Mi"
              cpu: "500m"
          livenessProbe:
            httpGet:
              path: /heartbeat
              port: http
            initialDelaySeconds: 15
            periodSeconds: 30
          readinessProbe:
            httpGet:
              path: /health
              port: http
            initialDelaySeconds: 15
        - name: connect-sync
          image: 1password/connect-sync:1.7.2
          env:
            - name: OP_SESSION
              valueFrom:
                secretKeyRef:
                  name: onepassword-credentials
                  key: 1password-credentials.json
          resources:
            requests:
              memory: "64Mi"
              cpu: "100m"
            limits:
              memory: "256Mi"
              cpu: "500m"
---
apiVersion: v1
kind: Service
metadata:
  name: onepassword-connect
  namespace: onepassword-system
spec:
  selector:
    app: onepassword-connect
  ports:
    - port: 8080
      targetPort: 8080
      name: http

ClusterSecretStore Configuration

Define cluster-wide access to 1Password vaults.

apiVersion: external-secrets.io/v1
kind: ClusterSecretStore
metadata:
  name: onepassword
spec:
  provider:
    onepassword:
      connectHost: http://onepassword-connect.onepassword-system:8080
      vaults:
        production: 1    # Priority ordering
        staging: 2
        development: 3
      auth:
        secretRef:
          connectTokenSecretRef:
            name: onepassword-token
            namespace: onepassword-system
            key: token

Namespace-Scoped SecretStore

For namespace-specific vault access.

apiVersion: external-secrets.io/v1
kind: SecretStore
metadata:
  name: onepassword-staging
  namespace: staging
spec:
  provider:
    onepassword:
      connectHost: http://onepassword-connect.onepassword-system:8080
      vaults:
        staging: 1
      auth:
        secretRef:
          connectTokenSecretRef:
            name: onepassword-token
            key: token

ExternalSecret Examples

Basic Secret Retrieval

apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: database-credentials
  namespace: production
spec:
  refreshInterval: 1h
  secretStoreRef:
    kind: ClusterSecretStore
    name: onepassword
  target:
    name: database-credentials
    creationPolicy: Owner
    deletionPolicy: Retain
  data:
    - secretKey: DB_HOST
      remoteRef:
        key: production-database    # Item title in 1Password
        property: host              # Field label
    - secretKey: DB_PORT
      remoteRef:
        key: production-database
        property: port
    - secretKey: DB_USERNAME
      remoteRef:
        key: production-database
        property: username
    - secretKey: DB_PASSWORD
      remoteRef:
        key: production-database
        property: password

TLS Certificate Secret

apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: tls-certificate
  namespace: production
spec:
  refreshInterval: 24h
  secretStoreRef:
    kind: ClusterSecretStore
    name: onepassword
  target:
    name: app-tls
    creationPolicy: Owner
    template:
      type: kubernetes.io/tls
  data:
    - secretKey: tls.crt
      remoteRef:
        key: wildcard-certificate
        property: certificate
    - secretKey: tls.key
      remoteRef:
        key: wildcard-certificate
        property: private-key

Docker Registry Secret

apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: registry-credentials
  namespace: production
spec:
  refreshInterval: 1h
  secretStoreRef:
    kind: ClusterSecretStore
    name: onepassword
  target:
    name: registry-secret
    creationPolicy: Owner
    template:
      type: kubernetes.io/dockerconfigjson
      data:
        .dockerconfigjson: |
          {
            "auths": {
              "{{ .registry }}": {
                "username": "{{ .username }}",
                "password": "{{ .password }}",
                "auth": "{{ printf "%s:%s" .username .password | b64enc }}"
              }
            }
          }
  data:
    - secretKey: registry
      remoteRef:
        key: docker-registry
        property: registry
    - secretKey: username
      remoteRef:
        key: docker-registry
        property: username
    - secretKey: password
      remoteRef:
        key: docker-registry
        property: password

SSH Key Secret

apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: git-ssh-key
  namespace: argocd
spec:
  refreshInterval: 24h
  secretStoreRef:
    kind: ClusterSecretStore
    name: onepassword
  target:
    name: repo-ssh-key
    creationPolicy: Owner
    template:
      type: kubernetes.io/ssh-auth
  data:
    - secretKey: ssh-privatekey
      remoteRef:
        key: git-deploy-key
        property: private-key

Bulk Environment Variables with dataFrom

apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: app-environment
  namespace: production
spec:
  refreshInterval: 30m
  secretStoreRef:
    kind: ClusterSecretStore
    name: onepassword
  target:
    name: app-env
    creationPolicy: Owner
  dataFrom:
    - find:
        path: app-config              # Item title
        name:
          regexp: "^[A-Z][A-Z0-9_]*$" # Match uppercase env vars

Multiple Items with dataFrom

apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: combined-secrets
  namespace: production
spec:
  refreshInterval: 1h
  secretStoreRef:
    kind: ClusterSecretStore
    name: onepassword
  target:
    name: combined-secrets
  dataFrom:
    - extract:
        key: database-credentials
    - extract:
        key: cache-credentials
    - extract:
        key: api-keys

PushSecret Examples

Push Kubernetes secrets to 1Password.

Basic PushSecret

apiVersion: external-secrets.io/v1alpha1
kind: PushSecret
metadata:
  name: push-cert-manager-certs
  namespace: cert-manager
spec:
  refreshInterval: 1h
  secretStoreRefs:
    - name: onepassword
      kind: ClusterSecretStore
  selector:
    secret:
      name: letsencrypt-certificate
  data:
    - match:
        secretKey: tls.crt
        remoteRef:
          remoteKey: kubernetes-certificates
          property: certificate
      metadata:
        apiVersion: kubernetes.external-secrets.io/v1alpha1
        kind: PushSecretMetadata
        spec:
          vault: production
          tags:
            - kubernetes
            - certificate
    - match:
        secretKey: tls.key
        remoteRef:
          remoteKey: kubernetes-certificates
          property: private-key
      metadata:
        apiVersion: kubernetes.external-secrets.io/v1alpha1
        kind: PushSecretMetadata
        spec:
          vault: production
          tags:
            - kubernetes
            - certificate

PushSecret with Delete Policy

apiVersion: external-secrets.io/v1alpha1
kind: PushSecret
metadata:
  name: push-dynamic-secret
spec:
  deletionPolicy: Delete    # Delete from 1Password when PushSecret is deleted
  refreshInterval: 30m
  secretStoreRefs:
    - name: onepassword
      kind: ClusterSecretStore
  selector:
    secret:
      name: generated-api-key
  data:
    - match:
        secretKey: api-key
        remoteRef:
          remoteKey: k8s-generated-api-key
          property: password
      metadata:
        apiVersion: kubernetes.external-secrets.io/v1alpha1
        kind: PushSecretMetadata
        spec:
          vault: staging

Native 1Password Kubernetes Operator

Helm Installation Values

# values.yaml for 1password/connect chart
connect:
  create: true
  credentials: ""  # Set via --set-file

operator:
  create: true
  watchNamespace: []  # Empty = all namespaces
  autoRestart: true
  pollingInterval: 600

# Resource limits
resources:
  requests:
    cpu: 100m
    memory: 128Mi
  limits:
    cpu: 500m
    memory: 512Mi

Install command:

helm install connect 1password/connect \
  --namespace onepassword-system \
  --create-namespace \
  --set-file connect.credentials=1password-credentials.json \
  --set operator.token.value=<access-token> \
  -f values.yaml

OnePasswordItem Examples

Basic Item

apiVersion: onepassword.com/v1
kind: OnePasswordItem
metadata:
  name: database-secret
  namespace: production
spec:
  itemPath: "vaults/Production/items/Database Credentials"

Creates a Kubernetes Secret with all fields from the 1Password item.

Item with Specific Vault ID

apiVersion: onepassword.com/v1
kind: OnePasswordItem
metadata:
  name: api-keys
  namespace: production
spec:
  itemPath: "vaults/abcd1234efgh5678/items/API Keys"

Auto-Restart Configuration

Namespace-Level Auto-Restart

apiVersion: v1
kind: Namespace
metadata:
  name: production
  annotations:
    operator.1password.io/auto-restart: "true"

Deployment with Auto-Restart

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  namespace: production
  annotations:
    operator.1password.io/auto-restart: "true"
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: app
          image: my-app:latest
          envFrom:
            - secretRef:
                name: database-secret  # OnePasswordItem-created secret

Disable Auto-Restart for Specific Item

apiVersion: onepassword.com/v1
kind: OnePasswordItem
metadata:
  name: static-config
  namespace: production
  annotations:
    operator.1password.io/auto-restart: "false"
spec:
  itemPath: "vaults/Production/items/Static Config"

Operator Environment Configuration

apiVersion: apps/v1
kind: Deployment
metadata:
  name: onepassword-operator
spec:
  template:
    spec:
      containers:
        - name: operator
          env:
            - name: POLLING_INTERVAL
              value: "300"  # 5 minutes
            - name: AUTO_RESTART
              value: "true"
            - name: WATCH_NAMESPACE
              value: "production,staging"  # Specific namespaces
            - name: OP_CONNECT_HOST
              value: "http://onepassword-connect:8080"

Kubernetes Secrets Injector

Alternative approach using init containers.

Injector Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  template:
    spec:
      serviceAccountName: my-app
      initContainers:
        - name: secrets-injector
          image: 1password/kubernetes-secrets-injector:latest
          env:
            - name: OP_SERVICE_ACCOUNT_TOKEN
              valueFrom:
                secretKeyRef:
                  name: op-service-account
                  key: token
          volumeMounts:
            - name: secrets
              mountPath: /secrets
      containers:
        - name: app
          image: my-app:latest
          envFrom:
            - secretRef:
                name: injected-secrets
          volumeMounts:
            - name: secrets
              mountPath: /secrets
              readOnly: true
      volumes:
        - name: secrets
          emptyDir:
            medium: Memory

Common Patterns

Multi-Environment Setup

# Development ClusterSecretStore
apiVersion: external-secrets.io/v1
kind: ClusterSecretStore
metadata:
  name: onepassword-dev
spec:
  provider:
    onepassword:
      connectHost: http://onepassword-connect.onepassword-system:8080
      vaults:
        development: 1
        shared: 2
      auth:
        secretRef:
          connectTokenSecretRef:
            name: onepassword-token-dev
            namespace: onepassword-system
            key: token
---
# Production ClusterSecretStore
apiVersion: external-secrets.io/v1
kind: ClusterSecretStore
metadata:
  name: onepassword-prod
spec:
  provider:
    onepassword:
      connectHost: http://onepassword-connect.onepassword-system:8080
      vaults:
        production: 1
      auth:
        secretRef:
          connectTokenSecretRef:
            name: onepassword-token-prod
            namespace: onepassword-system
            key: token

Kustomize Integration

# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - external-secrets.yaml

patches:
  - target:
      kind: ExternalSecret
    patch: |
      - op: replace
        path: /spec/secretStoreRef/name
        value: onepassword-prod

ArgoCD Application

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: app-secrets
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/org/secrets-repo
    targetRevision: HEAD
    path: external-secrets/production
  destination:
    server: https://kubernetes.default.svc
    namespace: production
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Troubleshooting Manifests

Debug ExternalSecret

apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: debug-secret
  annotations:
    external-secrets.io/debug: "true"
spec:
  refreshInterval: 1m  # Fast refresh for debugging
  secretStoreRef:
    kind: ClusterSecretStore
    name: onepassword
  target:
    name: debug-secret
    creationPolicy: Owner
  data:
    - secretKey: test
      remoteRef:
        key: test-item
        property: password

Check status:

kubectl describe externalsecret debug-secret
kubectl get externalsecret debug-secret -o yaml
kubectl logs -n onepassword-system -l app=onepassword-connect

Verify SecretStore Connection

# Check SecretStore status
kubectl get secretstore,clustersecretstore -A

# Describe for detailed status
kubectl describe clustersecretstore onepassword

# Check for sync errors
kubectl get externalsecret -A -o wide

1Password Python SDK Reference

Overview

The onepassword-sdk Python package provides native SDK access to 1Password without shelling out to the op CLI. It offers async operations for secret resolution, item CRUD, and vault management.

System Requirements

• Python: 3.9+
• libssl: 3.x (OpenSSL 3)
• glibc: 2.32+ (Linux)
• macOS: 12+ (Monterey)

Installation

# With uv (recommended)
uv add onepassword-sdk

# With pip
pip install onepassword-sdk

Authentication

Service Account Token (recommended for automation)

import os
from onepassword import Client

client = await Client.authenticate(
    auth=os.environ["OP_SERVICE_ACCOUNT_TOKEN"],
    integration_name="my-app",
    integration_version="1.0.0",
)

Environment Variable

Set OP_SERVICE_ACCOUNT_TOKEN in your environment:

export OP_SERVICE_ACCOUNT_TOKEN="ops_..."

API Reference

client.secrets

Resolve secret references without fetching full items.

# Single secret
value = await client.secrets.resolve("op://Vault/Item/Field")

# Batch resolve (more efficient for multiple secrets)
values = await client.secrets.resolve_all([
    "op://Vault/Item/Field1",
    "op://Vault/Item/Field2",
])
# Returns list of strings in same order as input

client.items

Full CRUD operations on 1Password items.

# List items in a vault
items = await client.items.list_all(vault_id)
async for item in items:
    print(item.title, item.id)

# Get a specific item
item = await client.items.get(vault_id, item_id)

# Create an item
from onepassword.types import (
    ItemCategory, ItemCreateParams, ItemField, ItemFieldType, ItemSection,
)

params = ItemCreateParams(
    title="my-environment",
    category=ItemCategory.APICREDENTIALS,
    vault_id=vault_id,
    tags=["environment"],
    sections=[ItemSection(id="variables", title="variables")],
    fields=[
        ItemField(
            id="API_KEY",
            title="API_KEY",
            value="secret-value",
            field_type=ItemFieldType.CONCEALED,
            section_id="variables",
        ),
    ],
)
created = await client.items.create(params)

# Update an item (get, modify, put)
item = await client.items.get(vault_id, item_id)
# ... modify item fields ...
await client.items.put(vault_id, item)

# Delete an item
await client.items.delete(vault_id, item_id)

# Archive an item
await client.items.archive(vault_id, item_id)

client.vaults

# List all accessible vaults
vaults = await client.vaults.list_all()
async for vault in vaults:
    print(vault.title, vault.id)

Item Creation Patterns

Environment Item (API Credential with variables section)

This is the pattern used by the op-env-* tools:

from onepassword.types import (
    ItemCategory, ItemCreateParams, ItemField, ItemFieldType, ItemSection,
)

variables = {"DB_HOST": "localhost", "DB_PORT": "5432", "API_KEY": "secret"}

params = ItemCreateParams(
    title="my-app-dev",
    category=ItemCategory.APICREDENTIALS,
    vault_id=vault_id,
    tags=["environment"],
    sections=[ItemSection(id="variables", title="variables")],
    fields=[
        ItemField(
            id=key,
            title=key,
            value=value,
            field_type=ItemFieldType.CONCEALED,
            section_id="variables",
        )
        for key, value in variables.items()
    ],
)

created = await client.items.create(params)

Field Types

CLI-to-SDK Migration

Key Differences from CLI

1. Vault IDs required — SDK uses vault IDs, not names. Use resolve_vault_id() helper. 2. No tag filtering — items.list_all() doesn't support tag filters. Use CLI subprocess fallback. 3. No get-by-title — Must iterate items to find by title. Use find_item_by_title() helper. 4. Async throughout — All SDK operations are async. Wrap with asyncio.run() for CLI tools. 5. Item update is get+modify+put — No atomic field edit; fetch the full item, modify, then save.

Error Handling

from onepassword import Client

try:
    client = await Client.authenticate(auth=token, ...)
except Exception as e:
    # Invalid token or network error
    print(f"Authentication failed: {e}")

try:
    value = await client.secrets.resolve("op://Vault/Item/Field")
except Exception as e:
    # Item not found, permission denied, etc.
    print(f"Secret resolution failed: {e}")

SecretsManager Usage

The SecretsManager class provides a higher-level abstraction with caching:

from op_env.secrets_manager import SecretsManager

async def main():
    sm = await SecretsManager.create()

    # Single secret (cached after first call)
    api_key = await sm.get("op://Production/API/key")

    # Batch resolve
    secrets = await sm.get_many([
        "op://Production/DB/password",
        "op://Production/DB/host",
    ])

    # Load all vars from a 1Password environment
    env = await sm.resolve_environment("my-app-prod", "Production")
    # Returns: {"DB_HOST": "...", "API_KEY": "...", ...}

    # List vaults
    vaults = await sm.list_vaults()

    # Clear cache when needed
    sm.clear_cache()

FastAPI Integration

from contextlib import asynccontextmanager
from fastapi import FastAPI
from op_env.secrets_manager import SecretsManager

sm: SecretsManager

@asynccontextmanager
async def lifespan(app: FastAPI):
    global sm
    sm = await SecretsManager.create()
    yield

app = FastAPI(lifespan=lifespan)

@app.get("/health")
async def health():
    db_url = await sm.get("op://Production/DB/url")
    return {"status": "ok"}

Django Integration

# settings.py
import asyncio
from op_env.secrets_manager import SecretsManager

def _load_secrets():
    async def _resolve():
        sm = await SecretsManager.create()
        return await sm.resolve_environment("my-app-prod", "Production")
    return asyncio.run(_resolve())

_secrets = _load_secrets()

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        "HOST": _secrets["DB_HOST"],
        "PASSWORD": _secrets["DB_PASSWORD"],
    }
}

1Password Python SDK Tools

Python CLI tools for managing 1Password Developer Environments using the official onepassword-sdk package. Drop-in replacement for the TypeScript/Bun tools with identical CLI interfaces.

Prerequisites

• Python 3.9+
• uv package manager
• OP_SERVICE_ACCOUNT_TOKEN environment variable set

Setup

cd tools-python
uv sync

CLI Tools

All tools accept the same arguments as their TypeScript counterparts.

Create Environment

# Inline variables
uv run op-env-create my-app-dev Personal API_KEY=secret DB_HOST=localhost

# From .env file
uv run op-env-create my-app-prod Production --from-file .env.prod

# Combine file + inline (inline overrides)
uv run op-env-create azure-config Shared --from-file .env EXTRA=value

List Environments

uv run op-env-list
uv run op-env-list --vault Personal
uv run op-env-list --json

Show Environment

uv run op-env-show my-app-dev Personal
uv run op-env-show my-app-dev Personal --reveal
uv run op-env-show my-app-dev Personal --json
uv run op-env-show my-app-dev Personal --keys

Update Environment

uv run op-env-update my-app-dev Personal API_KEY=new-key
uv run op-env-update my-app-dev Personal --from-file .env.local
uv run op-env-update my-app-dev Personal --remove OLD_KEY,DEPRECATED

Export Environment

uv run op-env-export my-app-dev Personal > .env
uv run op-env-export my-app-dev Personal --format docker > .env
uv run op-env-export my-app-dev Personal --format op-refs > .env.tpl
uv run op-env-export my-app-dev Personal --format json
uv run op-env-export azure Shared --prefix AZURE_ > .env

Delete Environment

uv run op-env-delete my-app-dev Personal
uv run op-env-delete old-config Shared --force
uv run op-env-delete deprecated Production --archive

SecretsManager (for application integration)

from op_env.secrets_manager import SecretsManager

async def main():
    sm = await SecretsManager.create()

    # Single secret (with caching)
    api_key = await sm.get("op://Production/API/key")

    # Batch resolve
    secrets = await sm.get_many([
        "op://Production/DB/password",
        "op://Production/DB/host",
    ])

    # Load all vars from an environment item
    env = await sm.resolve_environment("my-app-prod", "Production")

SDK vs CLI

Development

# Lint
uv run ruff check src/

# Type check
uv run mypy src/

# Run tests
uv run pytest