| name | 1password-cli |
| description | Expert on the 1Password CLI (the `op` command) for managing 1Password from the terminal and securely loading secrets into scripts and CI. Use when the user wants to read/inject secrets, use secret references (op://vault/item/field), run `op run` or `op inject` or `op read`, manage items/vaults, set up service accounts for automation, configure shell plugins (`op plugin`), use the 1Password SSH agent or git commit signing, or enable biometric/desktop-app integration. Triggers on mentions of 1Password CLI, `op` command, op cli, secret references, op run, op inject, op read, service account, secrets automation, 1Password vault/item from terminal, op plugin, 1Password SSH agent. |
| allowed-tools | Read, Write, Edit, Glob, Grep, Bash, WebFetch |
1Password CLI (op)
The 1Password CLI brings password management to your terminal. Authenticate with biometrics via the desktop app, or with a service account / Connect server for automation — then read secrets, inject them into files and processes, and manage items, vaults, and users.
Overview
op command structure — noun-verb: op <command> <subcommand> [flags] (e.g. op item get, op vault list).- Secret references —
op://vault/item/[section/]field URIs let you keep plaintext secrets out of code; resolve them with op read, op run, or op inject.
- Three auth modes — desktop app integration (biometric, interactive), service accounts (
OP_SERVICE_ACCOUNT_TOKEN, for CI/headless), and Connect server (OP_CONNECT_HOST/OP_CONNECT_TOKEN, self-hosted).
- Manage items & vaults — full CRUD with
op item and op vault, JSON templates for sensitive values, share links, and granular permissions.
- Shell plugins —
op plugin injects credentials into 80+ third-party CLIs (aws, gh, stripe…) behind biometric unlock.
- SSH & git — read SSH keys in OpenSSH format, and pair with the 1Password SSH agent for SSH auth and git commit signing.
Quick Start
# Install (macOS), then enable desktop-app integration in Settings > Developer
brew install 1password-cli && op --version
# Sign in (picks an account from the app)
op signin
# Read a single secret
op read "op://Private/GitHub/token"
# Get a field from an item
op item get "GitHub" --fields label=username,label=password
# Inject secrets into a process via env vars
export DB_PASSWORD="op://prod/db/password"
op run -- ./start-server.sh
Core Concepts
- Secret references —
op://<vault>/<item>/[<section>/]<field>; case-insensitive, quote anything with spaces. Supports ?attribute=otp and ?ssh-format=openssh. See secret-reference-syntax.
op run vs op inject — op run -- <cmd> resolves references in env vars and runs a command (secrets masked by default); op inject -i tpl -o out substitutes references inside a file. See secret-references.- Interactive vs automated — app integration is for humans (biometric); service accounts and Connect are for scripts/CI and follow least-privilege via vault scoping. See service-accounts.
- IDs over names — pass 26-char IDs in scripts: more stable and fewer API requests (matters for service-account rate limits).
Documentation
Getting started & auth
Secrets
Items & vaults
Automation & integrations
Reference
Common Workflows
- Inject secrets into a local app: put
KEY=op://vault/item/field lines in a .env, then op run --env-file=./.env -- npm start.
- CI without plaintext: create a service account scoped to one vault, set
OP_SERVICE_ACCOUNT_TOKEN, and use op run/op inject (pass vault/item IDs to stay under rate limits).
- Biometric auth for any CLI:
op plugin init aws, source ~/.config/op/plugins.sh, then run aws … — credentials are unlocked with your fingerprint.
Upstream Sources
Sync & Update
Docs under docs/ mirror the upstream 1password.dev/cli/ URL structure. Run discover-pages.sh to detect new upstream CLI pages from the site's llms.txt/sitemap.xml; run the sync script (or sync) to refresh cached docs. On diff, compare current docs/ vs upstream.
