1password

1Password CLI

Use this skill when the user wants secrets managed through 1Password instead of plaintext env vars or files. The primary host platform is Windows (PowerShell); Linux/macOS commands are provided where they differ.

When to Use

• Install or configure the 1Password CLI (op)
• Sign in with op signin (desktop app integration)
• Read secret references like op://Vault/Item/field
• Inject secrets into config/templates using op inject
• Run commands with secret env vars via op run
• Set up headless/CI authentication using a service account token

Prerequisites

• A 1Password account (personal, family, or business)
• 1Password CLI (op) installed — see Procedure below
• One of the following authentication methods:
  • Service Account token (OP_SERVICE_ACCOUNT_TOKEN) — recommended for automation/CI
  • Desktop App Integration — interactive, requires the 1Password desktop app unlocked
  • Connect Server — self-hosted, for shared/team automation
• tmux available for stable authenticated sessions during non-interactive terminal calls (desktop app flow only; not needed for service account token)

Procedure

1. Install the CLI

# Windows (winget) — primary
winget install AgileBits.1Password.CLI

# macOS
brew install 1password-cli

# Linux — see references/get-started.md for distro-specific package links
# Load references/get-started.md when the user needs Linux install details or distro-specific URLs.

2. Verify installation

op --version

3. Choose and configure an authentication method

Option A — Service Account (recommended for automation / Hermes)

Set OP_SERVICE_ACCOUNT_TOKEN in your environment. On Windows PowerShell:

$env:OP_SERVICE_ACCOUNT_TOKEN = "YOUR_TOKEN_HERE"

For persistent storage, add it to your shell profile or a .env file loaded by your agent framework. The skill will prompt for this token on first load if missing.

No desktop app is needed. Supports op read, op inject, op run.

op whoami  # verify — should show Type: SERVICE_ACCOUNT

Service accounts require CLI v2.18.0 or later.

Option B — Desktop App Integration (interactive)

1. Open the 1Password desktop app.
2. Go to Settings → Developer → Integrate with 1Password CLI and enable it.
3. Ensure the app is unlocked.
4. Run op signin and approve the biometric/prompt in the desktop app.

op signin --account my.1password.com

Option C — Connect Server (self-hosted)

$env:OP_CONNECT_HOST = "http://localhost:8080"
$env:OP_CONNECT_TOKEN = "YOUR_CONNECT_TOKEN"

4. Running op in non-interactive terminal sessions (desktop app flow)

Non-interactive terminal commands can lose auth context between calls. For reliable op use with desktop app integration, run sign-in and secret operations inside a dedicated tmux session.

This is NOT needed when using OP_SERVICE_ACCOUNT_TOKEN — the token persists across terminal calls automatically.

SOCKET_DIR="${TMPDIR:-/tmp}/hermes-tmux-sockets"
mkdir -p "$SOCKET_DIR"
SOCKET="$SOCKET_DIR/hermes-op.sock"
SESSION="op-auth-$(date +%Y%m%d-%H%M%S)"

tmux -S "$SOCKET" new -d -s "$SESSION" -n shell

# Sign in (approve in desktop app when prompted)
tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- "eval \"\$(op signin --account my.1password.com)\"" Enter

# Verify auth
tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- "op whoami" Enter

# Example read
tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- "op read 'op://Private/Npmjs/one-time password?attribute=otp'" Enter

# Capture output when needed
tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -200

# Cleanup
tmux -S "$SOCKET" kill-session -t "$SESSION"

5. Common operations

Read a secret

op read "op://app-prod/db/password"

Get an OTP

op read "op://app-prod/npm/one-time password?attribute=otp"

Inject secrets into a template

echo "db_password: {{ op://app-prod/db/password }}" | op inject

Run a command with a secret env var

$env:DB_PASSWORD = "op://app-prod/db/password"
op run -- pwsh -c 'if ($env:DB_PASSWORD) { Write-Output "DB_PASSWORD is set" } else { Write-Output "DB_PASSWORD missing" }'

# Bash equivalent
export DB_PASSWORD="op://app-prod/db/password"
op run -- sh -c '[ -n "$DB_PASSWORD" ] && echo "DB_PASSWORD is set" || echo "DB_PASSWORD missing"'

Load references/cli-examples.md when the user needs more advanced op command examples (bulk inject, document operations, item creation, etc.).

Pitfalls

• Never print raw secrets back to the user unless they explicitly request the value. Prefer op run / op inject so secrets stay in env/process memory only.
• "account is not signed in" error (desktop app flow): Run op signin again in the same tmux session. Auth context does not persist across separate terminal calls without a persistent session.
• Desktop app integration unavailable (headless/CI): Use the service account token flow instead. Interactive op signin will hang or fail.
• Service account CLI version: Service accounts require CLI v2.18.0+. Run op --version to confirm.
• Secret reference syntax: Field names with spaces must be included as-is inside the op:// URI, e.g. op://Vault/Item/one-time password?attribute=otp.
• Writing secrets to files: Avoid writing secrets into config files. Use op inject with a template, or op run to pass secrets as env vars to the consuming process.
• Windows PowerShell quoting: Use double quotes for op:// URIs in PowerShell. Single quotes prevent variable expansion but are fine for literal secret references.

Verification

1. Confirm the CLI is installed and at a supported version:

op --version
# Expected: 2.18.0 or higher (required for service accounts)

2. Confirm authentication is active:

op whoami
# Service account → Type: SERVICE_ACCOUNT
# Desktop app  → Type: INDIVIDUAL / BUSINESS with your account details
# Connect      → Type: CONNECT

3. Confirm a secret can be read (replace with a real reference):

op read "op://Private/Test/username"
# Expected: the stored value, printed to stdout

4. Confirm op run injects env vars correctly:

$env:TEST_SECRET = "op://Private/Test/username"
op run -- pwsh -c 'Write-Output "Secret length: $($env:TEST_SECRET.Length)"'
# Expected: Secret length: <non-zero number>

References

• references/get-started.md — load when the user needs Linux distro-specific install instructions or package manager details.
• references/cli-examples.md — load when the user needs advanced op command examples beyond read/inject/run.
• https://developer.1password.com/docs/cli/
• https://developer.1password.com/docs/service-accounts/