Prefer op run over all alternatives for secret injection.
Never enable shell tracing around secret commands (set -x, bash -x).
Never print secrets to stdout/logs (echo, cat on secret values/files). printf piped directly to stdin of another command (e.g., printf ... | curl -H @-) is acceptable when the output never reaches a log or terminal.
Never dump environment inside/after secret-bearing runs (env, printenv, set).
Never pass secrets as CLI args (arguments can appear in process lists).
Never pipe secret output to logs/files (tee, >, >>) unless explicitly writing a protected temporary file for op inject.
Never pipe op read output into logging pipelines.
Use op inject only with locked-down temp files: umask 077, chmod 600, trap cleanup.
Never include secret values in chat, tool output, or agent responses. If a command outputs a secret, do not echo or reference its value.

Banned Flags/Patterns

--no-masking — never use in agent workflows. Masking redacts accidental secret output and must stay on.
--reveal — never use in routine workflows. Outputs field values in cleartext.
op signin --raw — outputs raw session token to stdout.
Bare op read — never run without capturing into a variable. It prints secrets to stdout.
set -x — never enable around any op command.
curl -v — verbose mode logs auth headers. Use curl -sSf instead.
script / terminal recorders — session recording captures all secret output.

Untrusted Input

Never interpolate user-provided or external text into shell commands without strict quoting.
Always use -- to separate op flags from command arguments.
Vault/item/field names from untrusted sources must be validated (alphanumeric, hyphens, underscores, and spaces only).
Never use eval, backtick substitution, or string-built shell commands with secret references.
If an item name looks suspicious (contains $, backticks, semicolons, or pipes), stop and verify with the user.

Safe dynamic input template:

VAULT="my-vault"
ITEM="my-item"

# Validate: reject names with dangerous characters
for NAME in "$VAULT" "$ITEM"; do
  if ! LC_ALL=C [[ "$NAME" =~ ^[a-zA-Z0-9\ _-]+$ ]]; then
    echo "ERROR: invalid vault/item name: $NAME" >&2; exit 1
  fi
done

VALUE="$(op read "op://${VAULT}/${ITEM}/password")"
# use $VALUE, then:
unset VALUE

Always double-quote variable expansions. Never build op:// references from untrusted input without validation. Reject names containing /, $, backticks, semicolons, pipes, or other shell metacharacters.

`.env.tpl` Security

Treat as code: verify ownership, review changes, restrict permissions (chmod 600).
Do not accept .env.tpl files from untrusted sources.
Do not commit to public repos — references reveal vault/item structure.
Add to .gitignore if in a repo.
After creating/editing: chmod 600 .env.tpl
Only define expected variable names — reject templates containing dangerous env vars (PATH, LD_PRELOAD, BASH_ENV, NODE_OPTIONS, etc.).

Service Account Workflow (Primary)

Service accounts are the default for agents. No interactive auth needed.

1) Load and scope token

Load the token from your platform's secure store:

# macOS Keychain:
#   security find-generic-password -a <account> -s OP_SERVICE_ACCOUNT_TOKEN -w
# Linux (GNOME Keyring / libsecret):
#   secret-tool lookup service OP_SERVICE_ACCOUNT_TOKEN
# Last resort (interactive prompt, not automatable):
#   read -rs OP_SERVICE_ACCOUNT_TOKEN

OP_SERVICE_ACCOUNT_TOKEN="$(__REPLACE_WITH_SECURE_STORE_COMMAND__)"
[ -z "$OP_SERVICE_ACCOUNT_TOKEN" ] && { echo "ERROR: token retrieval failed" >&2; exit 1; }

Preferred: single-command scope (token never persists in shell env):

OP_SERVICE_ACCOUNT_TOKEN="$OP_SERVICE_ACCOUNT_TOKEN" \
  op run --env-file=.env.tpl -- <command>
unset OP_SERVICE_ACCOUNT_TOKEN

If multiple commands needed: export briefly with trap cleanup:

export OP_SERVICE_ACCOUNT_TOKEN
trap 'unset OP_SERVICE_ACCOUNT_TOKEN' EXIT
op run --env-file=.env.tpl -- <command-1>
op run --env-file=.env.tpl -- <command-2>
unset OP_SERVICE_ACCOUNT_TOKEN

2) Use `.env.tpl` + `op run` (preferred)

Create .env.tpl with 1Password references (not raw secrets):

API_KEY=op://my-vault/my-item/api-key
DB_PASSWORD=op://my-vault/my-item/password

Run:

op run --env-file=.env.tpl -- <command>

Masking is on by default and must stay on. Note: masking is defense-in-depth, not primary protection — transformed or partial secrets may evade redaction. The primary defense is never outputting secrets.

3) One-off fallback: `op read`

Use only when op run doesn't fit. Use a subshell for automatic cleanup:

(
  trap 'unset VALUE' EXIT
  VALUE="$(op read 'op://my-vault/my-item/field')"
  # use $VALUE here — auto-cleaned on exit
)

For API calls, prefer op run with a wrapper script to avoid sh -c:

# api-call.sh (chmod +x)
#!/usr/bin/env bash
set -euo pipefail
printf "Authorization: Bearer %s\n" "$API_TOKEN" | curl -sSf -H @- https://api.example.com/resource

op run --env-file=.env.tpl -- ./api-call.sh

4) Diagnostics

All diagnostic output contains metadata (account emails, vault names, item IDs, URLs) that should be treated as sensitive in logged/recorded agent sessions.

op whoami
op vault list --format json

5) Service account lifecycle

Scope is policy-driven: read-only vs read-write depends on configuration and vault permissions.
If access fails: verify vault grants and item permissions.
If token expired/revoked: regenerate in 1Password admin, update secure store, retry.
Limitation: service accounts may not support item creation depending on org policy.

`op inject` (restricted use)

Use only when a file must be materialized temporarily:

set -euo pipefail
set +x
umask 077

TMP_FILE="$(mktemp)"
cleanup() { rm -f "$TMP_FILE"; }
trap cleanup EXIT ERR INT TERM HUP QUIT

op inject -i config.tpl -o "$TMP_FILE"
chmod 600 "$TMP_FILE"

# use "$TMP_FILE" briefly, then auto-cleanup via trap

Never persist injected secret files beyond immediate use.

1password-sa

1Password CLI (Hardened)

References

Security Rules (must follow)