op-item-management

op item — item CRUD

The 20 categories

API Credential   Bank Account            Credit Card
Database         Document                Driver License
Email Account    Identity                Login
Membership       Outdoor License         Passport
Password         Reward Program          Secure Note
Server           Social Security Number  Software License
SSH Key          Wireless Router

Use exactly these names with --category (case-insensitive, whitespace-insensitive). For SSH Keys see the op-ssh-keys sub-skill.

Two ways to set fields: assignment statements vs JSON template

Assignment statements (quick, but visible to other processes)

Syntax:

[<section>.]<field>[<fieldType>]=<value>

• Section is optional unless multiple sections share a field name.
• fieldType in [brackets] for custom fields. Built-in fields don't need it.
• Escape ., =, \ in section/field NAMES with backslash. Don't escape values.

Field types that go in brackets:

fieldType	Field
text	plain string
password	concealed
email	email
url	URL
phone	phone
date	YYYY-MM-DD
monthyear	YYYY/MM
otp	otpauth://... URI
file	path to file (attachment)

Caveat: assignment values appear in the parent shell's argv (visible via ps, kept in shell history). For sensitive values, use a JSON template instead.

JSON template (recommended for sensitive values)

op item template get Login --out-file login.json
# edit login.json — set values for each field
op item create --template login.json
rm login.json

The same JSON shape returned by op item get <item> --format json works as a template. Use this to clone items between vaults or accounts:

op item get "My Login" --format json --account work | \
  op item create --account personal --vault Personal -

Pipe input replaces --template. Don't use both.

Combining the two

op item create --template login.json [email protected]

Assignment statements override the template's values for those keys.

op item create

op item create [- | --template <path>] [<assignment>...] [flags]

Flag	Purpose
--category <name>	Set category.
--title <title>	Set name.
--vault <vault>	Target vault (defaults to Private/Personal/Employee). Required for service accounts.
--url <url>	Set URL field (Login/Password/API Credential).
--tags a,b,c	Comma-separated tags.
--generate-password[=recipe]	Auto-generate. Default 32 chars w/ letters,digits,symbols. Recipe e.g. letters,digits,symbols,40 or letters,digits,20. Length must be 1–64.
--ssh-generate-key <type>	ed25519 (default), rsa, rsa2048, rsa3072, rsa4096.
--template <path>	JSON template.
--favorite	Mark as favorite.
--reveal	Print concealed values in output.
--dry-run	Preview without creating.

Examples

Login with generated password:

op item create --category=Login --title="Acme" --vault=Work \
  --url=https://acme.example.com \
  --generate-password=letters,digits,symbols,40 \
  [email protected]

API Credential with custom fields:

op item create --category="API Credential" --title="Stripe Live" --vault=Prod \
  --tags=production,billing \
  username=acct_123 \
  credential=sk_live_xxx \
  "Notes.Webhook URL[url]=https://hooks.acme.com/stripe"

Database with section and OTP:

op item create --category=Database --title="Postgres prod" --vault=Prod \
  type=postgresql \
  username=app \
  password=hunter2 \
  "Server.host[text]=db.prod.example.com" \
  "Server.port[text]=5432" \
  "Server.database[text]=app_prod" \
  "MFA.totp[otp]=otpauth://totp/Postgres?secret=JBSWY3DPEBLW64TMMQ&issuer=Acme"

Login with file attachment:

op item create --category=Login --title="VPN" --vault=Work \
  username=jane \
  "config[file]=/etc/openvpn/client.ovpn"

Secure Note:

op item create --category="Secure Note" --title="Recovery codes" --vault=Personal \
  notesPlain="$(cat recovery.txt)"
rm recovery.txt

op item edit

op item edit { <name> | <id> | <shareLink> } [<assignment>...] [flags]

Same flags as create minus --category and --ssh-generate-key. Plus a few specifics:

• Update a field's value: field=newvalue
• Change field type without value: field[password]
• Change both: field[monthyear]=2026/04
• Delete a custom field: section.field[delete]. If a section ends up empty, the section is removed.
• Built-in fields can't be deleted, only emptied: username=

Examples:

op item edit "Acme" --generate-password=letters,digits,symbols,32
op item edit "Acme" --tags=production,external,reviewed
op item edit "Acme" --title="Acme (rotated 2026-04)"
op item edit "Stripe Live" "Notes.Old Key[delete]"

op item get

op item get [{ <name> | <id> | <shareLink> | - }] [flags]

Flag	Purpose
--vault <vault>	Limit search scope. Required for service accounts unless piping.
--fields label=a,label=b	Return specific fields. Supports label=, type=. Comma-separated.
--otp	Print primary OTP (no secret reference needed).
--share-link	Print a shareable link for the item.
--include-archive	Include archived items.
--reveal	Show concealed values.

Examples:

op item get "Acme" --fields label=username,label=password --reveal --format=json
op item get Google --otp                     # current 6-digit code
op item get "Acme" --share-link              # shareable URL
op item list --tags work --format=json | op item get -   # bulk get from list

op item list (alias ls)

op item list [flags]

Flag	Purpose
--vault <vault>	Filter to one vault.
--categories Login,Database	Plural, comma-separated.
--tags work/client-a	Tag filter; nested tags include children.
--favorite	Favorites only.
--include-archive	Include archived.
--long	More detailed output.
--format json|csv	Machine-readable.

op item list --vault Prod --categories Login,Database --format=json
op item list --tags onboarding --format=csv

op item delete (aliases remove, rm)

op item delete <item> [--archive] [--vault <vault>]

• Default: soft delete (recoverable from "Recently Deleted" for 30 days).
• --archive: move to Archive instead.

op item move

op item move <item> --vault <source> --to-vault <dest>

Creates a copy in the destination vault and deletes the original. Permissions on both vaults required.

op item share

op item share <item> [flags]

Flag	Purpose
--emails [email protected],[email protected]	Restrict to these recipients (else anyone with the link).
--expires-in 7d	Lifetime — s/m/h/d/w. Default 7d.
--view-once	Expire after first view.
--vault <vault>	Source vault.

op item share "Customer credentials" [email protected] --expires-in=24h --view-once

Limitations: file attachments and Document items can't be shared. Subsequent edits to the item are not reflected in already-shared links.

op item template

op item template list                          # all categories
op item template get Login                     # JSON template for Login
op item template get Login --out-file l.json

Use the template as a starting point for --template or as documentation of available built-in fields per category.

op document — files as items

Documents are file attachments stored as their own items. Different from a file field on another item.

op document create ./report.pdf --vault Work --tags 2026,Q1
op document get "report" --vault Work --out-file ./report-from-1pw.pdf
op document edit "report" --file-path ./report-v2.pdf
op document delete "report" --archive
op document list

op document create - reads from stdin (use --file-name to set the saved name).

Common gotchas

1. Service accounts must specify --vault for op item get (or pipe the item). They can't search across vaults like an interactive user.
2. Assignment values land in shell history. For real secrets use a JSON template + rm after.
3. --categories (plural) for list, --category (singular) for create/get.
4. JSON templates don't carry passkeys. Editing a passkey-bearing item via --template overwrites the passkey.
5. op item delete is reversible for 30 days via the desktop app's Recently Deleted view. --archive is permanent until manually restored.