Skip to content

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 --user

Or for one project only (its git top level, or --project <dir>), committed with the code so the whole team gets it:

$ opv skill install

To 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:

any directory
$ 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:

your project
$ 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

  1. Install the tools. opv, the 1Password CLI, and your target's CLI. opv doctor names what is missing.
  2. 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 run eval "$(opv login --shell)" (fish: opv login --shell=fish | source). The assistant hands you that command and never runs it.
  3. Propose, then you apply. The assistant proposes products, keys, environments and targets (opv propose, or opv_propose over MCP) and shows you the contract diff and the vaults, items and empty fields they need. You run opv 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.
  4. Enter the values. You type each one at opv's masked prompt (opv set <KEY> --env <env>), import a file with opv import, or type it in the 1Password app at the link opv gives. 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 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 with opv_import_local.
  5. Check readiness. The assistant runs opv ready --json or opv next --json and reports names and value states only.
  6. Deliver. The assistant shows you opv plan <env>. CI, or you in your own terminal, runs opv sync <env> --expect-plan <id>, which refuses if anything changed, then opv ready --gate. The assistant never syncs.

Reference

Repository: github.com/matt-cochran/1password-vault