Auth

1Password Agent Secrets

1password-pp-cli

Agent-safe command layer over the official 1Password CLI and SDK service-account workflows.

Printed by @cathrynlavery (Cathryn Lavery)

Install

npx — recommended

npx -y @mvanhorn/printing-press-library install 1password

Installs the CLI binary and the agent skill (Claude Code, Codex, Cursor, Gemini CLI, Copilot, and more). Add --cli-only or --skill-only for one half. Requires Node.

Hermes

hermes skills install mvanhorn/printing-press-library/cli-skills/pp-1password --force

From the Hermes CLI. Inside a chat session use /skills install with the same path.

OpenClaw

Install the pp-1password skill from https://github.com/mvanhorn/printing-press-library/tree/main/cli-skills/pp-1password. The skill defines how its required CLI can be installed.

Paste this to your OpenClaw agent — the skill describes how to install its CLI.

Claude Desktop

This CLI ships an MCPB bundle. Download the latest release .mcpb and double-click it — Claude Desktop walks you through the install.

View source on GitHub →

Agent-safe command layer over the official 1Password CLI and SDK service-account workflows.

Use 1Password from agents without turning every task into a secret reveal. The CLI resolves fuzzy requests to exact op:// references, audits metadata, checks policy, and only calls op read, op inject, or op run after an explicit plan.

Quick Start

# Verify the official op CLI is installed and authenticated without reading any secret values.
1password-pp-cli op --json

# Summarize accessible vault and category metadata before planning a task.
1password-pp-cli access scope --json

# Check whether a task needs secret values, documents, cards, or write permissions.
1password-pp-cli secrets preflight --task "deploy using op run --env-file .env" --json

Unique Features

These capabilities aren't available in any other tool for this API.

Secrets

secrets resolve — Resolve fuzzy agent requests to exact op:// vault/item/field references without printing values.

Prevents accidental broad reads and gives later commands an exact reference to use.
```
1password-pp-cli secrets resolve --query "token" --json
```
secrets read — Read only an exact op:// reference, with policy checks and an explicit --reveal gate before values are printed.

Turns value access into a narrow, auditable action instead of a fuzzy search.
```
1password-pp-cli secrets read op://Engineering/GitHub/token --dry-run --json
```
secrets explain — Explain why a particular item and field was selected for a task without revealing the field value.
```
1password-pp-cli secrets explain --query "token" --json
```
secrets preflight — Check whether a planned task or command appears to require secret values, documents, cards, or write permissions.
```
1password-pp-cli secrets preflight --task "deploy using op run --env-file .env" --json
```

Environment

env plan — Parse .env, config, or shell files for missing variables and map them to safe op:// references.
```
1password-pp-cli env plan API_TOKEN= --json
```
env inject — Wrap op inject with a redacted plan first and require --write before producing an output file.
```
1password-pp-cli env inject --in-file README.md --out-file injected.env --json
```

Items

items classify — Find secure notes that look like API credentials, logins, SSH keys, cards, or documents.
```
1password-pp-cli items classify --json
```
items duplicates — Detect duplicate titles, URLs, usernames, and likely copied credentials across vaults without printing secret values.
```
1password-pp-cli items duplicates --json
```
items ownership — Flag shared or service credentials missing owner, purpose, rotation, or environment tags.
```
1password-pp-cli items ownership --json
```

Cards

cards audit — Find cards stored as notes or logins, missing owner/purpose tags, or CVV-like fields without printing card values.
```
1password-pp-cli cards audit --json
```
cards resolve — Return card item and field references without printing card numbers, expiry values, or CVVs.
```
1password-pp-cli cards resolve --query "card" --json
```

Documents

documents inventory — List document metadata and exact references without downloading document contents.
```
1password-pp-cli documents inventory --json
```
documents audit — Flag sensitive filenames, oversized docs, private-key/cert-like documents, and documents in shared vaults.
```
1password-pp-cli documents audit --json
```

Sharing

share preflight — Before sharing an item, show recipient, item category, included fields, expiry, and risk.

1password-pp-cli share preflight --ref op://Engineering/GitHub/token --recipient recipient --expires-in 1d --json

share audit — Report whether existing/shareable item link inspection is supported by op or the SDK and document unsupported status clearly.
```
1password-pp-cli share audit --json
```

Policy

policy check — Enforce rules such as never reading credit-card values, exact refs for production, and required owner tags.
```
1password-pp-cli policy check --ref op://Production/API/token --require-exact --json
```

Access

access scope — Summarize what the current service account or op session can access by vault, category, and count without values.
```
1password-pp-cli access scope --json
```
rate-limit status — Wrap op service-account ratelimit so agents can avoid burning quota.
```
1password-pp-cli rate-limit status --json
```

Agent

agent grant-plan — Suggest the minimum service-account vault permissions needed for a task.
```
1password-pp-cli agent grant-plan --task "read staging deploy token" --json
```

Runtime

run plan — Inspect an op run command or env files and show which secret references will resolve before executing.
```
1password-pp-cli run plan --command "npm test" --json
```

Audit

audit stale — Flag items that appear old, untagged, duplicated, or probably unused from metadata.
```
1password-pp-cli audit stale --days 180 --json
```
audit misplaced — Find API keys, cards, documents, or SSH material saved in the wrong 1Password category.
```
1password-pp-cli audit misplaced --json
```

Usage

Run 1password-pp-cli --help for the full command reference and flag list.

Commands

op

Inspect the local 1Password CLI authentication surface

1password-pp-cli op - Show whether op is installed and authenticated without reading secret values

Output Formats

# Human-readable table (default in terminal, JSON when piped)
1password-pp-cli op

# JSON for scripting and agents
1password-pp-cli op --json

# Filter to specific fields
1password-pp-cli op --json --select id,name,status

# Dry run — show the request without sending
1password-pp-cli op --dry-run

# Agent mode — JSON + compact + no prompts in one flag
1password-pp-cli op --agent

Agent Usage

This CLI is designed for AI agent consumption:

Non-interactive - never prompts, every input is a flag
Pipeable - --json output to stdout, errors to stderr
Filterable - --select id,name returns only fields you need
Previewable - --dry-run shows the request without sending
Read-only by default - this CLI does not create, update, delete, publish, send, or mutate remote resources
Offline-friendly - sync/search commands can use the local SQLite store when available
Agent-safe by default - no colors or formatting unless --human-friendly is set

Exit codes: 0 success, 2 usage error, 3 not found, 5 API error, 7 rate limited, 10 config error.

Health Check

1password-pp-cli doctor

Verifies configuration and access to the official op CLI.

Auth Setup

Install the official 1Password CLI (op) and authenticate it before using this wrapper.

For automation, set a 1Password service-account token:

export OP_SERVICE_ACCOUNT_TOKEN="<service-account-token>"

For local desktop workflows, sign in with op using the normal 1Password CLI or desktop-app integration. This CLI warns when OP_CONNECT_HOST or OP_CONNECT_TOKEN is set because those Connect variables take precedence over service-account auth in op.

Configuration

Config file: ~/.config/1password-pp-cli/config.toml

Static request headers can be configured under headers; per-command header overrides take precedence.

Troubleshooting

Not found errors (exit code 3)

Check the resource ID is correct
Run the list command to see available items

Generated by CLI Printing Press