Guide for implementing 1Password secrets management - CLI operations, service accounts, Developer Environments, and Kubernetes integration. Use when retrieving secrets, managing vaults, configuring CI/CD pipelines, integrating with External Secrets Operator, managing Developer Environments, or automating secrets workflows with 1Password.
Guide for implementing 1Password secrets management - CLI operations, service accounts, Developer Environments, and Kubernetes integration. Use when retrieving secrets, managing vaults, configuring CI/CD pipelines, integrating with External Secrets Operator, managing Developer Environments, or automating secrets workflows with 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
op item edit <item> field=value
op item delete <item>
op vault list
op vault get <vault>
op vault create <name>
op document list
op document get <document>
op document create <file> --vault <vault>
# Create new item
# Edit item
# Delete item
# Vault management
# List vaults
# Get vault info
# Create vault
# Document management
# List documents
# Download document
# 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
Feature
GUI
TypeScript CLI
Python SDK CLI
Create environment
Yes
bun run create
uv run op-env-create
Update environment
Yes
bun run update
uv run op-env-update
Delete environment
Yes
bun run delete
uv run op-env-delete
Show environment
Yes
bun run show
uv run op-env-show
List environments
Yes
bun run list
uv run op-env-list
Export to .env
Yes
bun run export
uv run op-env-export
Mount .env file
Yes (beta)
No
No
CLI Tools Setup (TypeScript)
Tools are written in TypeScript and require Bun runtime:
# Navigate to tools directorycd 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 directorycd tools-python
# Install dependencies
uv sync# Run any tool
uv run op-env-create --help
uv run op-env-list --help
For Python applications that need runtime secret resolution:
from op_env.secrets_manager import SecretsManager
asyncdefmain():
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 filesource .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
Name each 1Password Developer Environment after the thing it holds credentials for, e.g.
<project>-azure-rg-<name>-dev, <team>-pim, <project>-github. Keep the actual inventory of your
environments in a git-ignored local note, not in a committed (and potentially public) skill file.
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
# 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
apiVersion:external-secrets.io/v1kind:ExternalSecretmetadata:name:database-credentialsspec:refreshInterval:1hsecretStoreRef:kind:ClusterSecretStorename:onepasswordtarget:name:database-credentialscreationPolicy:Ownerdata:-secretKey:usernameremoteRef:key:Database# Item title in 1Passwordproperty:username# Field label-secretKey:passwordremoteRef:key:Databaseproperty:password
Using dataFrom with regex:
apiVersion:external-secrets.io/v1kind:ExternalSecretmetadata:name:env-configspec:refreshInterval:1hsecretStoreRef:kind:ClusterSecretStorename:onepasswordtarget:name:app-envdataFrom:-find:path:app-config# Item titlename:regexp:"^[A-Z_]+$"# Match all uppercase env vars
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'
If you work with multiple GitHub accounts, you can configure per-repo credentials:
# For a specific repo, use a different 1Password itemcd /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 configurationrm ~/.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 aliaswhich gh # Shows: gh: aliased to op plugin run -- gh# Run gh directly to bypass the alias
/opt/homebrew/bin/gh auth status
# Check current session
op whoami# Sign in again
op signin
# For service accounts, verify tokenecho$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
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.
