pp-1password

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/auth/1password/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

# 1Password — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `1password-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows:
   ```bash
   npx -y @mvanhorn/printing-press-library install 1password --cli-only
   ```
2. Verify: `1password-pp-cli --version`
3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill.

If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.4 or newer). This installs into `$GOPATH/bin` (default `$HOME/go/bin`), so add that directory to `$PATH` instead:

```bash
go install github.com/mvanhorn/printing-press-library/library/auth/1password/cmd/1password-pp-cli@latest
```

If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds.

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.

## When Not to Use This CLI

Do not activate this CLI for requests that require creating, updating, deleting, publishing, commenting, upvoting, inviting, ordering, sending messages, booking, purchasing, or changing remote state. This printed CLI is intended for secret-reference planning, metadata audits, policy checks, and tightly gated local `op read` / `op inject` workflows.

## Unique Capabilities

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._

  ```bash
  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._

  ```bash
  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.

  ```bash
  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.

  ```bash
  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.

  ```bash
  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.

  ```bash
  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.

  ```bash
  1password-pp-cli items classify --json
  ```
- **`items duplicates`** — Detect duplicate titles, URLs, usernames, and likely copied credentials across vaults without printing secret values.

  ```bash
  1password-pp-cli items duplicates --json
  ```
- **`items ownership`** — Flag shared or service credentials missing owner, purpose, rotation, or environment tags.

  ```bash
  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.

  ```bash
  1password-pp-cli cards audit --json
  ```
- **`cards resolve`** — Return card item and field references without printing card numbers, expiry values, or CVVs.

  ```bash
  1password-pp-cli cards resolve --query "card" --json
  ```

### Documents
- **`documents inventory`** — List document metadata and exact references without downloading document contents.

  ```bash
  1password-pp-cli documents inventory --json
  ```
- **`documents audit`** — Flag sensitive filenames, oversized docs, private-key/cert-like documents, and documents in shared vaults.

  ```bash
  1password-pp-cli documents audit --json
  ```

### Sharing
- **`share preflight`** — Before sharing an item, show recipient, item category, included fields, expiry, and risk.

  ```bash
  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.

  ```bash
  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.

  ```bash
  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.

  ```bash
  1password-pp-cli access scope --json
  ```
- **`rate-limit status`** — Wrap op service-account ratelimit so agents can avoid burning quota.

  ```bash
  1password-pp-cli rate-limit status --json
  ```

### Agent
- **`agent grant-plan`** — Suggest the minimum service-account vault permissions needed for a task.

  ```bash
  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.

  ```bash
  1password-pp-cli run plan --command "npm test" --json
  ```

### Audit
- **`audit stale`** — Flag items that appear old, untagged, duplicated, or probably unused from metadata.

  ```bash
  1password-pp-cli audit stale --days 180 --json
  ```
- **`audit misplaced`** — Find API keys, cards, documents, or SSH material saved in the wrong 1Password category.

  ```bash
  1password-pp-cli audit misplaced --json
  ```

## Recipes

### Resolve a secret request without revealing the value

```bash
1password-pp-cli secrets resolve --query "token" --json
```

Returns exact op:// references and candidate metadata with values redacted so a later step can require an exact reference.

### Plan environment injection before writing output

```bash
1password-pp-cli env inject --in-file README.md --out-file injected.env --json
```

Shows the references op inject would resolve and keeps will_write false unless --write is explicitly supplied.

## Command Reference

**op** — Inspect the local 1Password CLI authentication surface

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


### Finding the right command

When you know what you want to do but not which command does it, ask the CLI directly:

```bash
1password-pp-cli which "<capability in your own words>"
```

`which` resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code `0` means at least one match; exit code `2` means no confident match — fall back to `