hermes-skills/devops/1password-cli/SKILL.md

name, description

name	description
1password-cli	1Password CLI (`op`) usage patterns: reading secrets, extracting SSH keys, handling sensitive field blocking with --reveal workarounds.

1Password CLI (op)

Use op (v3+) to read secrets from 1Password during agent sessions. All outputs should avoid leaking secrets into logs/chat.

Authentication

1Password CLI integrates via the 1Password app (op signin) or service account tokens. Verify status with:

op whoami    # Shows account URL + integration ID

Session Token Pattern (op signin --raw)

For scripted use, capture the session token directly:

export OP_SESSION="$(op signin --raw 2>&1)"
# Now all subsequent op commands use this session
op item list --vault Hermes

This avoids the interactive eval pattern and works in non-interactive shells.

Reading Items

Basic item retrieval

# Human-readable output
op item get 'ITEM_TITLE' --vault 'VAULT_NAME'

# JSON (for programmatic parsing)
op item get 'ITEM_TITLE' --vault 'VAULT_NAME' --format json

Reading specific fields

# String fields (works directly — no restrictions)
op item get 'ITEM' --field 'field_label'

# Sensitive fields (passwords, private keys, tokens)
# These are BLOCKED when piped or redirected:
op item get 'ITEM' --field 'Sensitive-Field'    # Returns "[use 'op item get ID --reveal' to reveal]"

⚠️ Pitfall: Sensitive Field Extraction Blocked

The 1Password CLI blocks direct output of sensitive fields (SSH keys, passwords, tokens) when piped, redirected, or captured. This is a security feature, not a bug.

Workarounds:

Method	Command	Notes
--reveal	op item get ITEM --reveal --field 'Field-Name'	Outputs the actual value (may include wrapping quotes)
--reveal --value	op item get ITEM --reveal --field 'Field-Name' --value	Strips quotes, raw value only
Temp file	op item get ITEM --reveal --field 'Field' > /tmp/file	Write to file, then cat or use via tool

SSH Key Extraction Pattern

# SSH keys are always TYPE:SSHKEY in 1Password
tmpkey=$(mktemp /tmp/op_ssh_key_XXXX)
op item get 'SSH-KEY-NAME' --vault 'VaultName' --reveal --field 'Private-Key' --value > "$tmpkey" 2>/dev/null
chmod 600 "$tmpkey"
# Then use: eval "$(ssh-agent)" && ssh-add "$tmpkey"
# Or: ssh -i "$tmpkey" user@host

After use, clean up: rm -f "$tmpkey"

SSH Key JSON Parse

# Get full SSH key item as JSON, parse the openssh format
op item get 'SSH-KEY-NAME' --vault 'Vault' --reveal --format json | python3 -c "
import sys, json
data = json.load(sys.stdin)
for f in data.get('fields', []):
    if 'private' in f.get('label','').lower() or f.get('id') == 'private_key':
        print(f.get('value', ''))
"

Note: If --reveal still returns [REDACTED] in openssh format, the session may need refresh. Re-signin with op signin may be required.

Useful Commands

# Search items
op item list --vault 'VaultName'
op item search 'keyword'

# List vaults
op vault list

# Service account (non-interactive)
op connect server CONNECT_URL
op connect service-account --account ACCOUNT_ID --secret TOKEN

⚠️ Service Account --vault Requirement

When authenticated as a service account, op item get REQUIRES --vault:

# FAILS: "a vault query must be provided when this command is called by a service account"
op item get <ITEM_ID> --fields credential

# WORKS: explicit --vault
op item get <ITEM_ID> --vault Hermes --fields label=credential --reveal

API_CREDENTIAL Item Type

HA API tokens stored as API_CREDENTIAL category have a credential field:

# Extract API credential (requires --reveal for concealed field)
TOKEN=$(op item get <ITEM_ID> --vault Hermes --fields label=credential --reveal)

--fields Syntax

# By field label (preferred — robust against ID changes)
op item get ITEM --fields label=credential --reveal
op item get ITEM --fields label=username,label=password --reveal

# By field type
op item get ITEM --fields type=concealed --reveal

# Multiple fields as CSV
op item get ITEM --fields label=username,label=password --format json

Common Field Types

STRING    → Direct output works (hostnames, usernames, URLs without passwords)
PASSWORD  → Requires --reveal
SSHKEY    → Requires --reveal + file redirect for private key usage
NOTES     → --field 'notesPlain'

Related Support Files

File	Purpose
references/sensitive-field-extraction.md	Detailed troubleshooting for blocked/restricted fields