157 lines
4.5 KiB
Markdown
157 lines
4.5 KiB
Markdown
---
|
|
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 |
|