Initial commit: Hermes Agent Skills collection

2026-07-12 19:02:59 +00:00
commit e9cc106625
789 changed files with 233126 additions and 0 deletions
@@ -0,0 +1,156 @@
+---
+name: 1password-cli
+description: >
+  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:
+
+```bash
+op whoami    # Shows account URL + integration ID
+```
+
+### Session Token Pattern (`op signin --raw`)
+
+For scripted use, capture the session token directly:
+
+```bash
+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
+```bash
+# 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
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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`:
+
+```bash
+# 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:
+
+```bash
+# Extract API credential (requires --reveal for concealed field)
+TOKEN=$(op item get <ITEM_ID> --vault Hermes --fields label=credential --reveal)
+```
+
+### `--fields` Syntax
+
+```bash
+# 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 |