opz

1Password CLI wrapper for seamless secret injection into commands.

Features

• Find items by keyword search
• Run commands with secrets from 1Password items as environment variables
• Generate env files with gen subcommand (appends to existing, overwrites duplicates)
• Item list caching for faster repeated runs
• Fuzzy matching when exact title match is not found

Installation

cargo install opz

Trusted publishing

This repository is configured for crates.io trusted publishing. Create a tag such as v2025.12.0 and push it to trigger the Publish to crates.io workflow, which mints a short-lived token via OIDC and runs cargo publish --locked. You must enable trusted publishing for the opz crate in the crates.io UI (linked repository: f4ah6o/opx) before the workflow is allowed to request tokens.

Usage

Find Items

Search for 1Password items by keyword:

opz find <query>

Example:

opz find <query>
# Output: item-1	item-2	item-3

Run Commands with Secrets

Run a command with secrets from a 1Password item as environment variables:

opz [OPTIONS] <ITEM> [ENV] -- <COMMAND>...

Options:

• --vault <NAME> - Vault name (optional, searches all vaults if omitted)

Arguments:

• <ITEM> - Item title to fetch secrets from
• [ENV] - Output env file path (optional, no file generated if omitted)

When [ENV] is specified, the env file is preserved after command execution. If the file already exists, new entries are appended and duplicate keys are overwritten.

Examples:

# Run command with secrets from "example-item" item (no .env file generated)
opz example-item -- your-command

# Run with secrets and generate .env file
opz example-item .env -- your-command

# Specify custom env file path
opz example-item .env.local -- your-command

# Specify vault
opz --vault Private example-item -- your-command

Generate Env File

Generate env file only without running a command:

opz gen <ITEM> [ENV]

Examples:

# Output env to stdout
opz gen example-item

# Generate .env file
opz gen example-item .env

# Generate to custom path
opz gen example-item .env.production

# Specify vault
opz --vault Private gen example-item

How It Works

1. Fetches item list from 1Password (cached for 60 seconds)
2. Finds the matching item by title (exact or fuzzy match)
3. Builds op://<vault>/<item>/<field> references for each field
4. If env file is specified, writes the file with references (appends to existing, overwrites duplicate keys); otherwise outputs to stdout
5. Runs the command with secrets injected as environment variables

With gen subcommand, only steps 1-4 are executed (no command run).

op Command Usage

For security transparency, here's how opz uses the op CLI:

sequenceDiagram
    participant opz
    participant op as op CLI

    Note over opz: User runs: opz example-item -- claude "hello"

    opz->>op: op item list --format json
    op-->>opz: [{id, title, vault}, ...]
    Note over opz: Match "example-item" → get item ID

    opz->>op: op item get <id> --format json
    op-->>opz: {fields: [{label, value}, ...]}
    Note over opz: Resolve secret values<br/>(inject as env vars)

    Note over opz: Optional: write .env if specified

    opz->>op: sh -c "claude \"hello\""
    Note over opz: Execute with secrets in environment
    op-->>opz: Exit status

Security: opz delegates all secret access and authentication to op CLI. Item list is cached (60s) with metadata only.

Requirements

• 1Password CLI (op) installed and authenticated