1password-use

English | 中文

Not an official 1Password product. It wraps the official op CLI; the command is 1pass-use (short name opu).

Let AI agents use your 1Password: look up accounts, fill passwords and one-time codes, inject secrets into scripts, while keeping passwords out of the agent's own output and skipping the app's approval prompt for the vault you set aside for agents.

What it solves

• An agent that needs a password has to see it. Running op item get --reveal puts the password into the agent's transcript and terminal output, where anyone can read it later.
• Scheduled jobs and background agents can't wait for an approval. With the 1Password app integration, op asks you to approve at the start of a session and again after it has been idle (10 minutes by default); with nobody at the Mac, the job stalls.
• The agent can see too much. Once app authorization works, an agent could browse your whole vault, when it usually needs a handful of items.

What changes once it's installed

• Secrets masked by default. find, show and login mask passwords, one-time codes, concealed fields and secure-note bodies; usernames, URLs and plain-text fields are shown as they are, so keep secrets in concealed fields. Only get, totp, read and run reveal values, so your agent host can require your approval for those four.
• Secrets can go to a child process only. run --env PW=<item>#password -- <command> puts the value in that command's environment. 1pass-use never prints it or passes it as an argument; what the command itself does with it is up to that command.
• A separate vault for agents, no approval prompt. A 1Password service account reads and writes an "agent vault" (named Agent by default), with its token in the macOS login keychain. Agents work in that vault day to day; everything else stays in your private vault and needs app authorization, which asks you to approve (Touch ID or your password). The service account can reach only the vaults you grant it when you create it. Without a token, 1pass-use uses app authorization, which can see every vault your account can.
• New accounts go to your private vault. put without a vault saves to the private vault (Personal by default). Only the items you name go to the agent vault.
• Browser sign-in plugs in. login --domain <url> finds the login items for a site, masked. With chrome-use's auth login --1password, the username, password and code go only to the browser-side child process.

Things you might worry about

Is the service-account token safe in the keychain? The token can reach only the vaults you grant the service account when you create it. It is written to the login keychain through security's standard input, so it never shows up in process arguments. Put only items you are happy for agents to use directly in the agent vault.

Will it print my passwords? Default output masks passwords, one-time codes, concealed fields and secure-note bodies, and the tests assert it. Usernames, URLs and plain-text fields are shown. Only get, totp, read and run reveal values, and a command started with run can still print what it receives.

Which platforms? macOS only for now: the service-account token lives in the login keychain, and the entry scripts use the system /usr/bin/python3 (3.9 or newer).

What does it depend on? Only the official op CLI (brew install --cask 1password-cli). The program uses the Python standard library and runs no service.

What language are the messages in? Help text and errors are in Chinese for now.

Do passkeys work? No. The official op cannot export passkeys, so sites that only accept a passkey need another tool.

Get started in 5 minutes

brew install --cask 1password-cli
curl -fsSL https://raw.githubusercontent.com/Jerryx333/1password-use/main/install.sh | bash
1pass-use status                 # op version, accounts in the app, whether a service-account token is in the keychain

The installer clones the repo into ~/.local/share/1password-use (OPU_DIR changes it), puts 1pass-use and opu in ~/.local/bin and links the skill into the agent skills folders it finds (~/.claude/skills, ~/.codex/skills, ~/.agents/skills). Run the same line again to update. It needs git. From a clone of your own, run ./install.sh instead.

Turn on "Settings → Developer → Integrate with 1Password CLI" in the 1Password app to use app authorization. To let agents work without a fingerprint, create an Agent vault and a service account that can reach only it, then store its token in the keychain:

op service-account create my-agent --vault Agent:read_items,write_items --raw | 1pass-use service-account set
1pass-use check                  # exits 0 when it can be used right away

Common commands

Command	What it does
1pass-use find github	Find items by title, username or URL, without passwords
1pass-use show <id>	Show an item's fields, secrets masked
1pass-use get <id> --field username	Reveal one field (password by default)
1pass-use totp <id>	Get the current one-time code
1pass-use read 'op://Agent/item/password'	Reveal a value by op:// reference
1pass-use run --env PW=<id>#password -- ./script.sh	Run a command with values in its environment; fields can be username, totp, custom:<name>
1pass-use login --domain https://x.com/login --list	List the login items for a site, masked, for browser sign-in (sites are compared by an approximate registrable domain; on common shared-hosting domains only the exact host matches)
printf '%s' "$PW" | 1pass-use put "Site" --username u --url https://x.com --password-stdin	Create a login item, in the private vault by default
printf '%s' "$NEW" | 1pass-use set <id>	Change one field, new value on standard input

status, find, show, get, totp, put and set take --json. --vault picks a vault for find, show, get, totp, put, set, run and login. --mode goes before the command: 1pass-use --mode desktop find github forces app authorization. Vault names can be changed with environment variables: OPU_AGENT_VAULT (agent vault) and OPU_PRIVATE_VAULT (private vault).

More docs

• SKILL.md: usage for agents, including authorization and storage rules (Chinese).
• AGENTS.md: notes for people and agents changing the code (Chinese).

Contributing

The tests run offline against a fake op, without touching real accounts or the keychain:

/usr/bin/python3 -m unittest discover -s tests -v

Issues and PRs are welcome. If you change default output, add a test asserting it carries no plaintext.

License: Apache-2.0.