1Password CLI (op)

Manage secrets in 1Password using the op command. Authenticated via service account.

User Request

$ARGUMENTS

Commands Reference

Important: Service accounts require --vault on every command. Before running any item commands, discover the available vault name first:

bash
1op vault list --format=json

Then use the vault name from the response in all subsequent commands.

List Items

bash
1# List all items in vault
2op item list --vault "VAULT_NAME" --format=json
3
4# Long format (with categories, dates)
5op item list --vault "VAULT_NAME" --long --format=json
6
7# Filter by category
8op item list --vault "VAULT_NAME" --categories Login --format=json
9op item list --vault "VAULT_NAME" --categories "API Credential" --format=json
10
11# Filter by tags
12op item list --vault "VAULT_NAME" --tags production --format=json
13
14# Filter favorites only
15op item list --vault "VAULT_NAME" --favorite --format=json

Get Item Details

bash
1# Full item details
2op item get "Item Title" --vault "VAULT_NAME" --format=json
3
4# Get OTP (one-time password / 2FA code)
5op item get "Item Title" --vault "VAULT_NAME" --otp
6
7# Get specific fields
8op item get "Item Title" --vault "VAULT_NAME" --fields label=username --format=json
9op item get "Item Title" --vault "VAULT_NAME" --fields label=password --format=json
10op item get "Item Title" --vault "VAULT_NAME" --fields label=username,label=password --format=json
11
12# Get fields by type
13op item get "Item Title" --vault "VAULT_NAME" --fields type=CONCEALED --format=json

Read Individual Secret

bash
1# Read a specific field value directly
2op read "op://VAULT_NAME/Item Title/username"
3op read "op://VAULT_NAME/Item Title/password"
4op read "op://VAULT_NAME/Item Title/Section Name/field"

List Vaults

bash
1op vault list --format=json

JSON Response Structures

op vault list --format=json:

json
1[
2  {"id": "abc123...", "name": "My Vault", "content_version": 42}
3]

op item list --format=json:

json
1[
2  {
3    "id": "abc123...",
4    "title": "Example Service",
5    "version": 1,
6    "vault": {"id": "xyz...", "name": "My Vault"},
7    "category": "LOGIN",
8    "last_edited_by": "...",
9    "created_at": "2025-01-01T00:00:00Z",
10    "updated_at": "2025-01-02T00:00:00Z",
11    "additional_information": "user@example.com",
12    "urls": [{"primary": true, "href": "https://example.com"}]
13  }
14]

op item get --format=json:

json
1{
2  "id": "abc123...",
3  "title": "Example Service",
4  "category": "LOGIN",
5  "vault": {"id": "xyz...", "name": "My Vault"},
6  "fields": [
7    {
8      "id": "username",
9      "type": "STRING",
10      "purpose": "USERNAME",
11      "label": "email",
12      "value": "user@example.com",
13      "reference": "op://My Vault/Example Service/email"
14    },
15    {
16      "id": "password",
17      "type": "CONCEALED",
18      "purpose": "PASSWORD",
19      "label": "password",
20      "value": "secret_value",
21      "reference": "op://My Vault/Example Service/password"
22    },
23    {
24      "id": "TOTP_xxx",
25      "type": "OTP",
26      "label": "one-time password",
27      "value": "otpauth://totp/...",
28      "totp": "123456"
29    }
30  ],
31  "urls": [{"primary": true, "href": "https://example.com"}]
32}

op item get --otp: Returns just the 6-digit TOTP code as plain text (e.g., 182448).

op item get --fields --format=json:

json
1[
2  {"id": "username", "type": "STRING", "label": "email", "value": "user@example.com"},
3  {"id": "password", "type": "CONCEALED", "label": "password", "value": "secret_value"}
4]

Important Notes

• Service account requires --vault — always discover vault name via op vault list first, then use it in all commands
• --otp returns plain text — do not combine with --format=json
• OTP field in JSON — when getting full item, the current TOTP code is in the totp key of OTP-type fields
• Categories: Login, Password, API Credential, Secure Note, Database, SSH Key, Credit Card, Identity, Document, Server, Software License

Instructions

1. Parse the user's natural language request to determine what they need
2. First, run op vault list --format=json to discover the available vault name(s)
3. Determine the appropriate op command, using the discovered vault name
4. Always use --format=json except for --otp (which returns plain text)
5. Execute the command via Bash
6. Parse the JSON response and present results clearly to the user
7. For OTP requests, just return the code prominently
8. For credential requests, format as a clear key-value list
9. Never log or echo secrets unnecessarily — only show what was requested

If the request is ambiguous, ask for clarification.