AI assistants
Your assistant does the setup. You keep the secrets.
opv ships an agent skill, a version-matched guide and a machine-readable contract, so a coding assistant can read every key's value state, propose your keys, environments and targets, and check readiness. You sign in, run opv apply, and enter every value in 1Password or at opv's masked prompt. A key declared with file = "<path>" (a PEM, a certificate chain) is stored exactly with opv set <KEY> --env <env> --from-file <PATH> in your own terminal; the assistant hands that command over, never reads, writes or copies the file, and pasting a multi-line value into the 1Password app turns its line breaks into spaces. The assistant never sees one.
The agent skill
The skill is a short SKILL.md embedded in the opv binary, installed where your assistant looks for skills. It tells the assistant to start every session from the installed binary, to ask before anything that writes, and to hand sign-in, opv apply and secret values to you. It carries the version of the opv that installed it, so it never describes commands your opv does not have.
- Claude Code
.claude/skills/opv/SKILL.md--target claude - Codex and other .agents clients
.agents/skills/opv/SKILL.md--target codex
Install it
Installing opv with npm or the install script registers the skill for you, in every project, for both agents. To do it yourself, or after a Homebrew or cargo install:
$ opv skill install --userOr for one project only (its git top level, or --project <dir>), committed with the code so the whole team gets it:
$ opv skill installTo opt out, set OPV_NO_SKILL=1 or pass the install script --no-skill. CI installs never register it. --target claude or --target codex writes one agent's copy; the default is both.
Check and update
See every installed copy, its version, and whether it matches this opv:
$ opv skill status $ opv skill install --user # re-register by hand, for example after --no-skill
Only the installers (the install script and the npm postinstall) and opv skill install write the skill; no other opv command writes your home directory. After a Homebrew, cargo or manual upgrade the old copy stays, and opv skill status or opv doctor reports it as outdated. A copy you edited is kept; opv skill install --force replaces one. Project copies are updated with opv skill install in that project. After upgrading from 0.11 or earlier, also run opv mcp install again: the MCP tool set changed in 0.12.0.
Guide, schema, readiness
The skill points the assistant at three commands of the installed binary, so its instructions always match the opv it is driving:
$ opv guide agent # the full agent guide for this version: rules, flows, exit codes $ opv schema # every command, flag, effect, JSON document and error code $ opv ready --json # what is ready, what is not, who acts next (read-only)
opv ready and opv doctor never write 1Password, whoever runs them. Every failure has a stable error.code, and a human_required step is handed to you, not attempted.
Skill, CLI or MCP
Agent skill
Tells the assistant how to work with opv: start from the installed binary's guide, schema and readiness, ask before anything that writes, hand sign-in, opv apply and values to you.
Instructions only. It runs nothing by itself.
opv CLI
Everything opv does. Anyone can inspect and propose (opv inventory, opv needs, opv next, opv propose); a person applies (opv apply) and enters values (opv set, opv import); CI or a person delivers (opv sync, opv ready --gate).
Person commands (login, setup, config edit, apply, set) need your own terminal and refuse CI and agent mode.
MCP server (optional)
Five tools: opv_state, opv_next and opv_explain read; opv_propose returns a contract diff and a plan id and writes nothing; opv_import_local is the one writer, into a local-tier environment only. Every tool has the same CLI command.
Never accepts or returns a secret value, never applies a plan and never syncs. Built into opv: opv mcp serve; opv mcp install registers it.
MCP is optional. Through it an assistant inspects value states and proposes changes; it never applies one. A proposal writes nothing and ends with a plan id: you run opv apply <plan_id> in your own terminal, and the 1Password app asks you to authorize the writes. Every document carries a typed next (kind, actor, command): the assistant runs only an assistant step and hands a person step to you verbatim. A sync never happens over MCP; CI or you run opv sync <env> --expect-plan <id>. Sign-in, secret values and permission grants always stay with you. MCP interface
The setup path
- Install the tools. opv, the 1Password CLI, and your target's CLI.
opv doctornames what is missing. - Sign in, privately. You run
opv login --account <you>in your own terminal; the password goes only to 1Password's prompt. New in 0.14: to keep a shell signed in across commands without the desktop app, you runeval "$(opv login --shell)"(fish:opv login --shell=fish | source). The assistant hands you that command and never runs it. - Propose, then you apply. The assistant proposes products, keys, environments and targets (
opv propose, oropv_proposeover MCP) and shows you the contract diff and the vaults, items and empty fields they need. You runopv apply <plan_id>in your own terminal; the assistant never runs it. Existing values are kept, and a generated configuration is changed through its generator. - Enter the values. You type each one at opv's masked prompt (
opv set <KEY> --env <env>), import a file withopv import, or type it in the 1Password app at the link opv gives. A key declared withfile = "<path>"(a PEM, a certificate chain) is stored exactly withopv set <KEY> --env <env> --from-file <PATH>in your own terminal; the assistant hands that command over and never reads, writes or copies the file, and pasting a multi-line value into the 1Password app turns its line breaks into spaces. Never in chat, files or command arguments. For a local-tier environment only, the assistant may import a local file withopv_import_local. - Check readiness. The assistant runs
opv ready --jsonoropv next --jsonand reports names and value states only. - Deliver. The assistant shows you
opv plan <env>. CI, or you in your own terminal, runsopv sync <env> --expect-plan <id>, which refuses if anything changed, thenopv ready --gate. The assistant never syncs.
Reference
- Agent setup guide →The rules and flows; the same text as
opv guide agent. - MCP interface →The five tools, propose-only, who does what, and the limits.
- INSTALL.md for assistants →Point your assistant here to install and set up opv.
- JSON contract →Documents, exit codes and error codes.
Repository: github.com/matt-cochran/1password-vault