1password

# 1Password CLI

Follow the official CLI get-started steps. Don't guess install commands.

## References

- `references/get-started.md` (install + app integration + sign-in flow)
- `references/cli-examples.md` (real `op` examples)

## Workflow

1. Check OS + shell.
2. Verify CLI present: `op --version`.
3. Detect the auth mode the user has set up:
   - **Service account:** `OP_SERVICE_ACCOUNT_TOKEN` is set (typical for headless setups, CI, gateways).
   - **Desktop app integration:** the 1Password desktop app is running with CLI integration enabled (typical on macOS / Windows / Linux desktops).
   - **Standalone signin:** neither of the above — `op signin` will prompt for an account password every session.
4. Run `op` according to the auth mode (see below).
5. Verify access: `op whoami` should succeed before any secret read.
6. If multiple accounts: use `--account` or `OP_ACCOUNT`.

## Running `op` per auth mode

### Service account (preferred for headless / gateway use)

Direct exec. No tmux, no signin step.

```bash
export OP_SERVICE_ACCOUNT_TOKEN="ops_..."
op vault list
op read op://app-prod/db/password
```

### Desktop app integration

Direct exec. **Do not wrap in tmux** — the desktop app integration uses a per-user IPC channel that is established for the gateway's exec environment but is not always reliably reachable from tmux subshells, which run with a different environment context. The transport differs per platform (XPC via the 1Password Browser Helper on macOS, a Unix domain socket on Linux, a named pipe on Windows); the practical rule for an agent is the same on all three: run `op` directly. On macOS, a useful symptom indicator is the 1Password integration group container at `~/Library/Group Containers/2BUA8C4S2C.com.1password/t/`.

```bash
op vault list      # may trigger Touch ID / Windows Hello / system auth on first call
op whoami
```

If a call returns `1Password CLI couldn't connect to the 1Password desktop app`, do not switch to tmux. Confirm the desktop app is running and unlocked, then retry direct exec.

### Standalone signin (no app, interactive password)

This is the only mode where tmux helps. `op signin` prints an `eval`-style export setting an `OP_SESSION_*` token for POSIX shells; later commands in the same shell are authenticated by that env var. The gateway's per-command shells lose that state between calls, so a persistent tmux pane keeps the session token alive — but only if the export is actually applied with `eval` in a POSIX shell. Sending `op signin` as a plain command leaves stdout printed to the pane and `op whoami` will fail.

The tmux flow is only actionable on macOS/Linux hosts where the `tmux` skill is available. The example intentionally opens `/bin/sh` so the POSIX `eval "$(op signin ...)"` output is valid even when the user's normal shell is fish. On Windows, prefer desktop app integration or service account auth. If the user only has standalone interactive signin on Windows, stop and ask them to provide a persistent PowerShell session mechanism or switch to desktop integration/service account auth; do not translate the tmux commands directly.