1Password CLI: comprehensive guide to creating, reading, updating, and deleting secrets
Documentation verified: October 6, 2026
Utility: 1Password CLI, executable op, current CLI 2 syntax
Primary authentication: an already exported OP_SERVICE_ACCOUNT_TOKEN
Examples: Bash on macOS/Linux; jq for JSON processing
This guide covers secrets stored as items and fields in 1Password vaults. It includes authentication checks, complete CRUD workflows, secret references, safe input/output handling, runtime use, file secrets, and troubleshooting. The separate 1Password Environments product is not the storage model used here; service accounts currently have read-only access to Environments. S02
The token is assumed to be configured already. Do not paste it into this document, command arguments, or example files. An environment token can mean different things: first confirm the variable name in section 2.
Verification boundary: Commands and behavior were cross-checked against the official sources linked throughout and listed at the end. Bash examples were syntax-checked, and the JSON transformations were checked locally with synthetic data. op was not installed in the authoring workspace, so no live 1Password authentication, secret retrieval, or CRUD operation was performed. Section 13 provides an optional live test you can run in a permitted test vault.
Contents
- Requirements and conventions
- Use the existing token
- Select a vault and identify items
- Fields, JSON, and safe secret handling
- Create secrets
- Read secrets
- Update secrets
- Archive, delete, and restore
- Move or copy items
- Use secrets in applications
- Store and retrieve files
- Automation and error handling
- Optional live CRUD verification
- Troubleshooting
- Accuracy notes and official sources
1. Requirements and conventions
Use a current stable 1Password CLI 2 release. Service-account authentication requires at least 2.18.0, but that minimum does not imply that every later feature is available in 2.18.0. Check your installed binary's help when a flag is unfamiliar. S01
op --version
op --help
op item create --help
op item get --help
op item edit --help
op item delete --help
jq --versionIf op is missing, follow the official installation instructions. The documented Homebrew installation command is:
brew install 1password-cliThe examples are individual workflows, not a single script to paste and execute from beginning to end. Replace example IDs, paths, and names with your own. A command that creates, edits, moves, archives, or deletes an item changes your account unless it explicitly uses a supported --dry-run flag.
For this Bash session:
set +x
set -o pipefail
umask 077set +x disables command tracing; pipefail makes an upstream pipeline failure visible; umask 077 restricts permissions on newly created local files. Complete scripts below also use set -euo pipefail. These are shell practices, not additional op flags.
2. Use the existing token
Identify the authentication mode
| Existing environment variable | Meaning | Applicability here |
|---|---|---|
OP_SERVICE_ACCOUNT_TOKEN |
Service-account credential | Main workflow: item CRUD, subject to vault permissions. |
OP_CONNECT_HOST and OP_CONNECT_TOKEN |
Credentials for a deployed Connect server | The documented CLI integration supports read, run, inject, and item get --format json; it is not a full CLI CRUD authentication path. |
OP_SESSION |
Session from manual user sign-in | User authentication; not a service-account token. |
These variables are not interchangeable. --session accepts a user session token, not a service-account token. S03S05
Confirm the token is exported without displaying it
set +x
bash -c ': "${OP_SERVICE_ACCOUNT_TOKEN:?OP_SERVICE_ACCOUNT_TOKEN is not exported or is empty}"'This only checks availability in a child process. It does not validate the token, permissions, or network connection. If the variable was assigned but not exported, export the existing value without retyping it:
export OP_SERVICE_ACCOUNT_TOKENWith service-account authentication, op uses the variable directly; you do not need an interactive op signin step. The official configuration check is: S06
op user get --meConfirm that the displayed identity is the intended service account. This displays account metadata, not the token.
Resolve Connect precedence
Connect variables take precedence over the service-account variable. If this shell is intentionally supposed to use the service account, clear the competing variables and repeat the identity check: S06
unset OP_CONNECT_HOST OP_CONNECT_TOKEN
op user get --meDo not do this in a shell that is intentionally configured for Connect. For full CRUD through Connect itself, consult the Connect API; the limited CLI integration is a different interface. S05
Required access
For these service-account workflows, the target vault needs read_items for reads and read_items,write_items for writes. write_items depends on read_items. share_items is separate and is not needed for ordinary CRUD. S07
Service accounts cannot access the built-in Personal/Private/Employee vault or the default Shared vault. Use a permitted custom vault. Existing service-account vault grants and permissions cannot be expanded in place: create a replacement service account with the needed access if necessary. S02
A successful identity check proves authentication, not write permission. A successful read does not prove permission to create, edit, or delete.
3. Select a vault and identify items
List accessible vaults and use the returned ID: S08
op vault list --format=json | jq '.[] | {id, name}'
VAULT_ID='REPLACE_WITH_VAULT_ID'
op vault get "$VAULT_ID" --format=json | jq '{id, name}'Prefer IDs in automation. Titles can be duplicated or renamed; an item's ID remains stable until it is moved to a different vault. Always scope these examples to a vault, including when using item IDs. S03
op item list --vault "$VAULT_ID" --format=json |
jq '.[] | {id, title, category}'
# Choose an existing item's ID when reading, updating, or deleting it.
ITEM_ID='REPLACE_WITH_ITEM_ID'Useful inventory filters: S09
op item list --vault "$VAULT_ID" --categories 'Login,Password' --format=json
op item list --vault "$VAULT_ID" --tags 'myapp' --format=json
op item list --vault "$VAULT_ID" --include-archive --format=jsonAn inventory is not a full export of every item's secret fields. Fetch an individual item with item get or a field with read when you need its value. Treat names and metadata as potentially confidential too.
4. Fields, JSON, and safe secret handling
An item belongs to a category such as Login, Password, API Credential, Secure Note, Database, or SSH Key. Items contain built-in fields and optional custom fields, which may belong to sections. Discover the actual template instead of guessing a category's built-in field IDs: S10
op item template list
op item template get 'API Credential'
op item template get 'Login' |
jq '.fields[] | {id, label, type, purpose}'Assignment syntax
The literal assignment shape is [section.]field[fieldType]=value; section and type are optional. These examples contain only non-secret values:
username=worker@example.invalid
Connection.host[text]=db.internal.example
Connection.port[text]=5432For built-in fields, use the template's field ID and omit the type, for example username=.... For custom fields, common mappings are: S10
| Assignment type | JSON field type | Use |
|---|---|---|
password |
CONCEALED |
Password or API token |
text |
STRING |
Ordinary text |
email |
EMAIL |
Email address |
url |
URL |
URL field |
date |
DATE |
Date, YYYY-MM-DD |
monthYear |
MONTH_YEAR |
Month/year |
phone |
PHONE |
Telephone number |
otp |
OTP |
otpauth:// seed URI |
file |
Not a JSON field type | Attachment path; assignment input only |
Quote entire assignments in the shell. Escape literal ., =, and \ in section/field **names** using a backslash; do not apply those name-escaping rules to values. Example: 'Connection.host\.name[text]=db.internal.example'. S11
Put sensitive values in JSON input
Avoid password=REAL_SECRET, --arg secret "$SECRET", or similar process arguments. Shell expansion still places the resulting value in an argument even when you use a variable. 1Password recommends JSON templates for sensitive assignments. S11
Use one of these paths:
- A protected JSON file supplied with
--template. - JSON supplied through standard input.
- A secret file read by
jq --rawfile, then serialized to JSON.
CONCEALED controls field display; it does not make plaintext input, full JSON output, or a resolved file safe to log. Handle all full item JSON as secret-bearing. Human-readable concealment and op run output masking are different features. S13
5. Create secrets
A. Create a Login with a generated password
This generates the password inside op; the password is not passed as an argument. It prints only the created item ID through jq:
ITEM_ID="$(
op item create \
--vault "$VAULT_ID" \
--category Login \
--title 'myapp-worker' \
--url 'https://app.example.invalid/login' \
--tags 'myapp,development' \
--generate-password='letters,digits,symbols,32' \
'username=worker@example.invalid' \
'Connection.host[text]=db.internal.example' \
--format=json |
jq -er '.id'
)"
printf 'Created item: %s\n' "$ITEM_ID"Password generation supports Login and Password items. A recipe selects character classes and a length from 1–64; the documented default is 32 characters using letters, digits, and symbols. --dry-run previews a create without saving it. Preview output can still contain sensitive data. S11
For example, preview an independent dummy item:
op item create --vault "$VAULT_ID" --category Password \
--title 'preview-only' --generate-password='letters,digits,40' \
--dry-run --format=json |
jq '{title, category}'A generated preview password is not a reservation of the password for a later command. A later create generates its own value.
B. Create an API token or other existing text secret
This stores an existing UTF-8 text secret in a custom concealed token field on a Secure Note. SECRET_FILE must already contain the intended value and be protected on disk. The file's contents, including any final newline, are preserved by --rawfile. S15
SECRET_FILE='/secure/path/to/api-token.txt'
ITEM_ID="$(
set -euo pipefail
set +x
umask 077
: "${VAULT_ID:?Set VAULT_ID}"
test -r "$SECRET_FILE"
secret_work_dir="$(mktemp -d "${TMPDIR:-/tmp}/op-create.XXXXXXXX")"
trap 'rm -rf -- "$secret_work_dir"' EXIT
jq -n --rawfile secret "$SECRET_FILE" '{
title: "myapp-api-token",
category: "SECURE_NOTE",
fields: [
{label: "token", type: "CONCEALED", value: $secret}
]
}' > "$secret_work_dir/item.json"
op item create - --vault "$VAULT_ID" --format=json \
< "$secret_work_dir/item.json" |
jq -er '.id'
)"
printf 'Created item: %s\n' "$ITEM_ID"The JSON serializer handles quotes, backslashes, and multiline text. Do not manually interpolate an arbitrary secret into JSON. Remove the source secret file when your workflow no longer needs it; the cleanup above only removes the temporary JSON directory.
To read this example's field later:
op read "op://$VAULT_ID/$ITEM_ID/token"That command prints the actual secret. See section 6 for reads that do not print to the terminal.
C. Create using a category template and editor
For a category with several built-in fields, fetch its template and fill in the relevant field value properties. Preserve the category, field IDs, types, and purposes supplied by the template. S11
(
set -euo pipefail
set +x
umask 077
secret_work_dir="$(mktemp -d "${TMPDIR:-/tmp}/op-template.XXXXXXXX")"
trap 'rm -rf -- "$secret_work_dir"' EXIT
op item template get 'API Credential' \
--out-file "$secret_work_dir/item.json"
# Substitute a trusted local editor; account for its backups/swap files.
vi "$secret_work_dir/item.json"
jq -e 'type == "object" and (.fields | type == "array")' \
"$secret_work_dir/item.json" > /dev/null
op item create --vault "$VAULT_ID" --title 'myapp-integration' \
--template "$secret_work_dir/item.json" --format=json |
jq '{id, title, vault: .vault.id}'
)Do not combine --template with piped JSON input. If you combine a template with field assignments, the assignments override the template's corresponding values. S11
6. Read secrets
Read an item or selected fields
# Human-readable output; concealed fields are hidden by default on current CLI.
op item get "$ITEM_ID" --vault "$VAULT_ID" --format=human-readable
# Explicitly reveal sensitive values to the terminal.
op item get "$ITEM_ID" --vault "$VAULT_ID" --reveal --format=human-readable
# Select fields; this can expose their values.
op item get "$ITEM_ID" --vault "$VAULT_ID" \
--fields 'label=username,label=password' --format=json--fields supports label or type filters, such as type=concealed. Use it on an item that actually has the selected fields. For one precise value, prefer op read. S09
Inspect structure without printing the value properties:
op item get "$ITEM_ID" --vault "$VAULT_ID" --format=json |
jq '{id, title, category, fields: [.fields[] | {
id, label, type, section, reference
}]}'Full JSON still passes through the pipe. Do not add tee, command tracing, or debug logging to secret-bearing pipelines.
Read one field by secret reference
op://vault/item/field
op://vault/item/section/fieldEach component can use a name or ID. References are case-insensitive. Supported name characters are alphanumerics, spaces, ., _, and -; use IDs for components containing other characters. Quote references, especially spaces and query strings. Use section IDs/names to disambiguate fields with matching labels. S17
# Password field on a Login/Password item.
op read "op://$VAULT_ID/$ITEM_ID/password"
# Custom field inside a named section.
op read "op://$VAULT_ID/$ITEM_ID/Connection/host"
# Avoid the extra output newline added by op read.
op read --no-newline "op://$VAULT_ID/$ITEM_ID/password"
# Save directly to a new protected file instead of printing the secret.
op read --no-newline --file-mode 0600 --out-file ./password.secret \
"op://$VAULT_ID/$ITEM_ID/password"read resolves a reference; it does not create or update anything. --no-newline suppresses the extra output newline, not newlines that are part of the stored value. The output-file default mode is 0600; use filesystem permissions appropriate to your OS. S18
For text secrets where trailing newlines do not matter, capture the value without displaying it:
set +x
SECRET_VALUE="$(op read --no-newline "op://$VAULT_ID/$ITEM_ID/password")"
# Consume it without logging it or putting it in process arguments.
unset SECRET_VALUEBash command substitution removes trailing newlines. Use a file or stream when exact text preservation matters.
OTP codes and SSH keys
For an item with an existing OTP field or SSH private key: S18
op item get "$ITEM_ID" --vault "$VAULT_ID" --otp
op read "op://$VAULT_ID/$ITEM_ID/one-time password?attribute=otp"
op read --out-file ./id_ed25519 --file-mode 0600 \
"op://$VAULT_ID/$ITEM_ID/private key?ssh-format=openssh"Change labels to the fields actually present on your item. An OTP seed URI is itself a secret; write it through a JSON template rather than a literal shell assignment.
7. Update secrets
Update metadata and non-secret fields
op item edit "$ITEM_ID" --vault "$VAULT_ID" \
--title 'myapp-worker-production' \
--tags 'myapp,production' \
--url 'https://app.example.invalid/login' \
'Connection.host[text]=db.production.example' > /dev/nullUse --url with a compatible item category. --tags replaces the tag list; it is not an append operation. --tags '' clears tags. An assignment can create a missing custom field or section. Review misspellings so an intended update does not silently become a new field. S09
Preview a metadata change:
op item edit "$ITEM_ID" --vault "$VAULT_ID" \
--title 'proposed-title' --dry-run --format=json |
jq '{id, title}'Replace one secret field using a fresh JSON snapshot
Passkey limitation: do not use this JSON round-trip workflow on an item containing a passkey. 1Password explicitly warns that updating such an item with a JSON template overwrites its passkey. Use an appropriate supported editing method for that item instead. S12
Set FIELD_ID from the structural output in section 6. For a built-in Login password it is password; a custom token field normally has its own generated ID.
FIELD_ID='password'
SECRET_FILE='/secure/path/to/replacement-secret.txt'
(
set -euo pipefail
set +x
umask 077
: "${VAULT_ID:?Set VAULT_ID}"
: "${ITEM_ID:?Set ITEM_ID}"
: "${FIELD_ID:?Set FIELD_ID}"
test -r "$SECRET_FILE"
secret_work_dir="$(mktemp -d "${TMPDIR:-/tmp}/op-edit.XXXXXXXX")"
trap 'rm -rf -- "$secret_work_dir"' EXIT
op item get "$ITEM_ID" --vault "$VAULT_ID" --format=json \
> "$secret_work_dir/current.json"
jq --arg field "$FIELD_ID" --rawfile secret "$SECRET_FILE" '
if ([.fields[] | select(.id == $field)] | length) != 1 then
error("Expected exactly one matching field ID")
else
(.fields[] | select(.id == $field) | .value) = $secret
end
' "$secret_work_dir/current.json" > "$secret_work_dir/updated.json"
op item edit "$ITEM_ID" --vault "$VAULT_ID" \
--template "$secret_work_dir/updated.json" --format=json |
jq '{id, title, updated_at}'
# Verify exact text without printing it.
op read --no-newline \
--out-file "$secret_work_dir/readback.secret" \
"op://$VAULT_ID/$ITEM_ID/$FIELD_ID"
cmp -s "$SECRET_FILE" "$secret_work_dir/readback.secret"
printf 'Secret replacement verified.\n'
)This retains the fetched item's other JSON fields and changes only the selected value in that snapshot. Perform the fetch and write close together and serialize competing writers; this is not an atomic field patch or a guarantee against concurrent changes. Do not use a blank category template as a replacement for an existing item's complete representation.
Alternatively, after generating a complete updated JSON file, pipe it to op item edit ITEM_ID --vault VAULT_ID. item edit accepts the JSON through stdin while the positional argument identifies the existing item. Do not also pass --template. S12
Generate a replacement password
For a suitable Login or Password item:
op item edit "$ITEM_ID" --vault "$VAULT_ID" \
--generate-password='letters,digits,symbols,40' > /dev/nullThis changes the stored password in 1Password. It does not change the credential at your database, website, or API provider. Coordinate provider-side rotation and application reloads separately.
Delete a custom field or clear a built-in field
# Remove a custom field.
op item edit "$ITEM_ID" --vault "$VAULT_ID" \
'Connection.host[delete]' > /dev/null
# Clear a built-in field on a compatible item.
op item edit "$ITEM_ID" --vault "$VAULT_ID" 'username=' > /dev/nullDeleting the last field in a custom section removes the section. Built-in fields cannot be deleted through this mechanism; clear their values instead. S09
8. Archive, delete, and restore
First inspect the target ID and title. This prints only selected metadata:
op item get "$ITEM_ID" --vault "$VAULT_ID" --format=json |
jq '{id, title, vault: .vault.id}'Choose the intended action:
# Keep the item in Archive.
op item delete "$ITEM_ID" --vault "$VAULT_ID" --archive# Delete the item.
op item delete "$ITEM_ID" --vault "$VAULT_ID"Archived items can remain in Archive indefinitely. Deleted items remain in Recently Deleted for 30 days, unless permanently destroyed earlier. Restore archived/deleted items or permanently destroy deleted items through the 1Password apps or 1Password.com. The documented op item command set does not provide a restore subcommand. S19
To inspect archived items:
op item list --vault "$VAULT_ID" --include-archive --format=json
op item get "$ITEM_ID" --vault "$VAULT_ID" --include-archiveArchiving is not credential revocation: archived items can still be retrieved by ID or with archive-inclusive reads. Deleting a stored API token also does not revoke that token at its issuer. Revoke or rotate the actual credential at the provider when necessary. S09
For bulk deletion, prepare and review a file containing one intended item ID per line, then deliberately run:
op item delete - --vault "$VAULT_ID" < reviewed-item-ids.txtAvoid an unreviewed broad list-to-delete pipeline. The item-delete reference does not document a --dry-run flag. S09
9. Move or copy items
Use the dedicated move command and accessible source/destination vaults:
DESTINATION_VAULT_ID='REPLACE_WITH_DESTINATION_VAULT_ID'
op item move "$ITEM_ID" \
--current-vault "$VAULT_ID" \
--destination-vault "$DESTINATION_VAULT_ID" \
--format=json |
jq '{id, title, vault: .vault.id}'A move copies the item into the destination and deletes the original, producing a new item ID. Update stored IDs and secret references after moving; the destination's access rules also apply. Do not treat item edit --vault as the documented move interface. S09
You can also create a separate copy from item JSON: S11
op item get "$ITEM_ID" --vault "$VAULT_ID" --format=json |
op item create - --vault "$DESTINATION_VAULT_ID" \
--title 'myapp-copy' --format=json |
jq '{id, title, vault: .vault.id}'Treat this as JSON-based duplication, not a lossless backup strategy for every item feature; the passkey limitation still matters.
10. Use secrets in applications
Environment variables with op run
For an item containing a password field:
export DB_PASSWORD="op://$VAULT_ID/$ITEM_ID/password"
op run -- php ./worker.php
unset DB_PASSWORDReplace the executable with your application's command. The exported value is a reference; the child process receives the resolved value. An already running process does not automatically receive later secret changes. S20
Alternatively, store references in app.env:
DB_USERNAME="op://Application Secrets/myapp-worker/username"
DB_PASSWORD="op://Application Secrets/myapp-worker/password"op run --env-file ./app.env -- php ./worker.phpA file containing only references can be versioned if its names/metadata are acceptable to disclose. Never put OP_SERVICE_ACCOUNT_TOKEN or plaintext secret values in that committed file.
op run masks resolved secrets on stdout/stderr by default. --no-masking and OP_RUN_NO_MASKING can disable masking. Masking is not a security boundary: processes still receive plaintext secrets, and same-user processes may access process environments. S14
If a shell must expand a resolved variable, expand it inside the child shell:
DB_PASSWORD="op://$VAULT_ID/$ITEM_ID/password" \
op run -- sh -c 'test -n "$DB_PASSWORD"'Putting "$DB_PASSWORD" directly in the parent command's arguments causes the parent shell to expand it before op run resolves the reference. Environment files override exported variables; when several --env-file options define the same variable, the last file wins. S14
Template substitution with op inject
For example, a plain-text template token.txt.tpl can contain:
{{ op://Application Secrets/myapp-api-token/token }}op inject --in-file ./token.txt.tpl --out-file ./token.txt --file-mode 0600The output contains the actual secret. Keep generated files out of source control and delete them when no longer required. Without an output file, inject writes resolved content to stdout. S21
For JSON, YAML, shell code, or connection URLs, treat injection as text substitution: arbitrary secret characters may need format-specific encoding. Use an appropriate serializer or environment variables when unrestricted values could break the target syntax. inject does not write anything back to the vault.
11. Store and retrieve files
Use Document items for file payloads and attachments for files associated with an ordinary item. The current service-account CLI guide lists op document as supported; do not assume documents are categorically unavailable to service accounts. Vault permissions still apply. S06
Document CRUD
DOCUMENT_ID="$(
op document create ./service-config.json \
--vault "$VAULT_ID" --title 'myapp-service-config' \
--file-name service-config.json --format=json |
jq -er '.id'
)"
op document list --vault "$VAULT_ID" --format=json
op document get "$DOCUMENT_ID" --vault "$VAULT_ID" \
--out-file ./downloaded-service-config.json --file-mode 0600
op document edit "$DOCUMENT_ID" ./updated-service-config.json \
--vault "$VAULT_ID" --file-name service-config.json > /dev/null
op document delete "$DOCUMENT_ID" --vault "$VAULT_ID" --archiveUse a new download path. document edit replaces the file payload. Create/edit also accept file bytes on stdin using -. S23
The document command reference describes this separate command as permanent deletion:
op document delete "$DOCUMENT_ID" --vault "$VAULT_ID"There is inconsistent published wording between that reference and the general item-deletion policy. Do not assume a 30-day recovery guarantee for this document command; use archive if recovery is required, or verify the behavior for your installed version with 1Password before relying on it. S19
Attachments
Example for an existing item:
op item edit "$ITEM_ID" --vault "$VAULT_ID" \
'client\.pem[file]=/secure/path/to/client.pem' > /dev/null
op read "op://$VAULT_ID/$ITEM_ID/client.pem" \
--out-file ./downloaded-client.pem --file-mode 0600Escape the period in the assignment field name, as shown; the reference uses the actual filename. Attachment input is a file path, not inline file contents. For exact binary payloads, prefer document/attachment file operations over shell variables. S10S17
12. Automation and error handling
Use explicit --format=json for machine parsing, and select only the metadata you intend to log. OP_FORMAT can change defaults, so do not depend on an inherited output format. S03
Practical patterns for scripts:
- Stop after an authentication, fetch, JSON parsing, or write failure. Do not hide every error with
|| true. - Use exact IDs and vault scope; a not-found result is not sufficient evidence that an item should be created.
- Keep the ID returned by create. Re-running create is not an upsert and can produce another item with the same title.
- If a create times out, determine whether it succeeded before retrying. A blind retry can create duplicates.
- Serialize concurrent writers to an item. Retrying a full JSON snapshot can reapply stale values.
- Re-fetch after a write when correctness matters; compare values without logging them, as in section 7.
- Treat
--dry-runas a preview, not proof of write/delete permission or an end-to-end test. - Use a job's secret store to inject the existing token. Do not commit it, dump the environment, or enable shell tracing around secret use.
Check service-account usage when throttled:
op service-account ratelimitThere are separate hourly read/write limits and an account-wide daily request limit; one CLI command can make multiple requests. Use IDs, reduce redundant calls, and apply bounded backoff for transient failures. Consult the current rate-limit page for your plan's numeric limits instead of hardcoding them into a runbook. S07
Manage token expiration, rotation, or revocation on the service-account page in 1Password.com. Rotation retains the service account's permissions; changing access requires a new service account. Unsetting a local variable is not token revocation. S25
13. Optional live CRUD verification
This performs writes in the test vault you choose. It creates one disposable Password item, checks a read, updates and reads a custom field, deletes that item, and checks that the ID is absent from the successful archive-inclusive list. It prints IDs/status only.
Save this block as a Bash script, replace the vault placeholder, and run it deliberately. If it stops early, use the printed item ID to inspect or clean up that specific test item. The deletion step is intentionally explicit, not an exit trap.
#!/usr/bin/env bash
set -euo pipefail
set +x
umask 077
: "${OP_SERVICE_ACCOUNT_TOKEN:?Token must already be exported}"
if [[ -n "${OP_CONNECT_HOST:-}" || -n "${OP_CONNECT_TOKEN:-}" ]]; then
printf 'Choose service-account authentication before this test.\n' >&2
exit 1
fi
VAULT_ID='REPLACE_WITH_A_PERMITTED_TEST_VAULT_ID'
command -v op > /dev/null
command -v jq > /dev/null
op user get --me > /dev/null
test_title="op-crud-check-$(date -u +%Y%m%dT%H%M%SZ)-$$"
test_item_id="$(
op item create --vault "$VAULT_ID" --category Password \
--title "$test_title" --generate-password='letters,digits,32' \
--format=json |
jq -er '.id'
)"
printf 'Created test item: %s\n' "$test_item_id"
password_size="$(
op read --no-newline "op://$VAULT_ID/$test_item_id/password" | wc -c
)"
[[ "$password_size" -eq 32 ]]
op item edit "$test_item_id" --vault "$VAULT_ID" \
'crud_check[text]=updated' > /dev/null
[[ "$(op read "op://$VAULT_ID/$test_item_id/crud_check")" == 'updated' ]]
op item delete "$test_item_id" --vault "$VAULT_ID"
op item list --vault "$VAULT_ID" --include-archive --format=json |
jq -e --arg id "$test_item_id" 'all(.[]; .id != $id)' > /dev/null
printf 'PASS: create, read, update, and delete completed.\n'This is an operational check for your installed CLI, token, vault, and network. It does not verify passkeys, Documents, provider-side credential rotation, or every optional feature in this guide.
14. Troubleshooting
| Symptom | Check or action |
|---|---|
op: command not found |
Install the official CLI and confirm the executable is on the current process's PATH. S01 |
| Unexpected sign-in or biometric prompt | Confirm the intended token is exported in this shell, container, or CI step; a variable in another process is not automatically available here. S04 |
| Wrong authentication backend | Check whether Connect variables are overriding the service-account token. S06 |
| Reads work; writes fail | Check write_items on the target vault and whether you are using the read-oriented Connect CLI integration. S05 |
| Vault unavailable | Confirm its ID, the service account's immutable grants, supported vault type, and whether service-account access is disabled for that vault. S02 |
| Ambiguous or missing item | Use its ID and an explicit vault; account for Archive and any prior move. S03 |
| Field missing or a new field appeared | Check the category template, exact field ID, section, and assignment spelling. S10 |
| Reference fails with punctuation in a name | Use the relevant component ID; do not assume URL percent-encoding bypasses the documented character restrictions. S17 |
Secret is visible despite no --reveal |
JSON, op read, resolved files, and other output paths must be treated as plaintext; human-readable concealment is not universal redaction. S13S18 |
| Updated value rejected by the application | Check source-file newlines, application reloads, reference target, and provider-side rotation. |
| Rate-limit error | Inspect op service-account ratelimit, reduce calls, and wait/back off according to the applicable limit. S24 |
| Unknown flag/subcommand | Check the local --help, installed version, and current official reference. Do not mix CLI 1 and CLI 2 examples. S03 |
| Passkey disappeared after JSON edit | Restore an earlier item version using 1Password's supported recovery UI; avoid further JSON-template edits on that item. S12 |
15. Accuracy notes and official sources
The examples intentionally follow the current command reference when a tutorial contains conflicting wording:
- Vault selection: the item reference defines
item edit --vaultas the vault containing the item. This guide uses the dedicateditem movecommand for moves, even though the edit tutorial also describes changing vaults with--vault. S09 - Vault scope: the service-account guide requires explicit scope when multiple vaults are accessible, while the item-get reference states it more broadly. This guide always supplies the vault. S06
- Field deletion: the item reference clearly distinguishes custom-field deletion from clearing built-in fields. Its syntax is used here. S09
- Documents: current documentation lists service-account support, but the document-delete reference's permanence wording conflicts with the broader deletion policy. The guide flags that uncertainty instead of promising recovery. S06S23
- Passkeys and JSON: the warning about passkey loss is explicit in official documentation. JSON templates are not a universally lossless editing format. S12
The shell workflows and sample names are original examples built from the documented interfaces. The verification here establishes source alignment and local syntax/JSON correctness; it does not establish account-specific permissions or live server behavior.
Source register
All links below are official 1Password documentation except the separately identified official jq manual. The legacy developer.1password.com/docs/... documentation URLs redirected to www.1password.dev/... during verification.
| ID | Official source | What was checked |
|---|---|---|
| S01 | Get started with 1Password CLI | Installation and executable/version check |
| S02 | Get started with Service Accounts | Version floor, vault restrictions, immutable grants, Environments access |
| S03 | CLI reference | Global flags, IDs, output formats, current command structure |
| S04 | CLI environment variables | Authentication and output-related variable names |
| S05 | Use CLI with a Connect server | Documented Connect-backed CLI command subset |
| S06 | Use service accounts with CLI | Token authentication, identity check, precedence, supported commands |
| S07 | Service-account command reference | Permission names and rate-limit command |
| S08 | Vault command reference | Vault discovery and lookup |
| S09 | Item command reference | CRUD, filtering, flags, fields, movement, archive scope |
| S10 | Item fields | Built-in identifiers and custom field types |
| S11 | Create items | Generated passwords, assignments, templates, stdin, attachments |
| S12 | Edit items | JSON update workflow, input methods, passkey limitation |
| S13 | CLI release notes | Human-readable concealment and dry-run behavior |
| S14 | op run reference |
Child environment, masking, expansion order, precedence |
| S15 | Item JSON template | JSON structure, optional/generated field IDs, sections |
| S16 | Official jq manual | --rawfile, --arg, JSON mutation, raw output, exit status |
| S17 | Secret reference syntax | Name/ID paths, character rules, references, field/file addressing |
| S18 | op read reference |
Exact read flags, OTP, SSH format, output files |
| S19 | Archive and delete items | Archive retention, 30-day item recovery, restoration UI |
| S20 | Load secrets into the environment | .env references, runtime injection, process-environment limits |
| S21 | op inject reference |
Template input/output and file-mode flags |
| S22 | Load secrets into config files | Generated plaintext files and cleanup |
| S23 | Document command reference | File CRUD, output files, document deletion wording |
| S24 | Service-account rate limits | Hourly/daily scopes and request-count behavior |
| S25 | Manage service accounts | Access inspection, rotation, revocation, vault access controls |