1Password CLI

Follow the official CLI get-started steps. Don't guess install commands.

Links

• https://developer.1password.com/docs/cli/get-started/
• https://developer.1password.com/docs/cli/secret-references/
• https://developer.1password.com/docs/cli/secrets-environment-variables/
• https://developer.1password.com/docs/cli/secrets-scripts/
• https://developer.1password.com/docs/cli/environment-variables/
• https://developer.1password.com/docs/cli/secret-reference-syntax/
• https://developer.1password.com/docs/cli/secrets-template-syntax/
• https://developer.1password.com/docs/cli/item-fields/
• https://developer.1password.com/docs/cli/item-template-json/
• https://developer.1password.com/docs/cli/vault-permissions/
• https://developer.1password.com/docs/cli/user-states/
• https://developer.1password.com/docs/cli/item-create/
• https://developer.1password.com/docs/cli/item-edit/
• https://developer.1password.com/docs/cli/ssh-keys/
• https://developer.1password.com/docs/cli/reference/
• https://developer.1password.com/docs/cli/best-practices/
• https://developer.1password.com/docs/cli/reference/commands/completion/
• https://developer.1password.com/docs/cli/reference/commands/inject/
• https://developer.1password.com/docs/cli/reference/commands/read/
• https://developer.1password.com/docs/cli/reference/commands/run/
• https://developer.1password.com/docs/cli/reference/commands/signin/
• https://developer.1password.com/docs/cli/reference/commands/signout/
• https://developer.1password.com/docs/cli/reference/commands/update/
• https://developer.1password.com/docs/cli/reference/commands/whoami/
• https://developer.1password.com/docs/cli/reference/management-commands/account/
• https://developer.1password.com/docs/cli/reference/management-commands/connect/
• https://developer.1password.com/docs/cli/reference/management-commands/document/
• https://developer.1password.com/docs/cli/reference/management-commands/events-api/
• https://developer.1password.com/docs/cli/reference/management-commands/group/
• https://developer.1password.com/docs/cli/reference/management-commands/item/
• https://developer.1password.com/docs/cli/reference/management-commands/plugin/
• https://developer.1password.com/docs/cli/reference/management-commands/service-account/
• https://developer.1password.com/docs/cli/reference/management-commands/user/
• https://developer.1password.com/docs/cli/reference/management-commands/vault/
• https://developer.1password.com/docs/environments/
• https://developer.1password.com/docs/environments/local-env-file/
• https://developer.1password.com/docs/environments/cursor-hook-validate/
• https://developer.1password.com/docs/cli/shell-plugins/homebrew/
• https://developer.1password.com/docs/cli/shell-plugins/huggingface/
• https://developer.1password.com/docs/cli/shell-plugins/openai/
• https://developer.1password.com/docs/cli/shell-plugins/cloudflare-workers/

References

• references/get-started.md (install + app integration + sign-in flow)
• references/cli-examples.md (real op examples)
• references/secret-references.md (what secret references are + how to resolve)
• references/secrets-environment-variables.md (env + .env usage with op run)
• references/secrets-scripts.md (script patterns using op run/read/inject)
• references/environment-variables.md (OP_* env vars and precedence)
• references/secret-reference-syntax.md (URI rules, attributes, variables)
• references/secrets-template-syntax.md (template/enclosure/variables rules)
• references/item-fields.md (built-in vs custom fields + types)
• references/item-template-json.md (template keys + sections/fields)
• references/vault-permissions.md (permission hierarchy + dependencies)
• references/user-states.md (user state meanings)
• references/item-create.md (create items safely, templates, assignments)
• references/item-edit.md (edit items safely, templates, caveats)
• references/ssh-keys.md (generate and retrieve SSH keys)
• references/cli-reference.md (command structure, IDs, caching, flags)
• references/best-practices.md (updates, least privilege, templates)
• references/commands-completion.md (shell completion)
• references/commands-inject.md (inject secrets into templates)
• references/commands-read.md (read secrets by reference)
• references/commands-run.md (run with env secrets)
• references/commands-signin.md (sign in via app integration)
• references/commands-signout.md (sign out behavior)
• references/commands-update.md (update op CLI)
• references/commands-whoami.md (active account info)
• references/management-account.md (account management commands)
• references/management-connect.md (Connect server commands)
• references/management-document.md (document item commands)
• references/management-events-api.md (Events API integration)
• references/management-group.md (group commands)
• references/management-item.md (item commands)
• references/management-plugin.md (shell plugin commands)
• references/management-service-account.md (service account commands)
• references/management-user.md (user commands)
• references/management-vault.md (vault commands)
• references/environments.md (Environments overview + requirements)
• references/environments-local-env-file.md (local .env mount destination)
• references/environments-cursor-hook-validate.md (Cursor hook validation flow)
• references/shell-plugins-homebrew.md (Homebrew plugin setup)
• references/shell-plugins-huggingface.md (Hugging Face plugin setup)
• references/shell-plugins-openai.md (OpenAI plugin setup)
• references/shell-plugins-cloudflare-workers.md (Cloudflare Workers plugin setup)

Workflow

1. Check OS + shell.
2. Verify CLI present: op --version.
3. Confirm desktop app integration is enabled (per get-started) and the app is unlocked.
4. REQUIRED: create a fresh tmux session for all op commands (no direct op calls outside tmux).
5. Sign in / authorize inside tmux: op signin (expect app prompt).
6. Verify access inside tmux: op whoami (must succeed before any secret read).
7. If multiple accounts: use --account or OP_ACCOUNT.
8. Choose the secret-loading path:
   • op run for environment variables / .env files.
   • op read for a single secret to stdout or a file.
   • op inject for config/template files.
   • op plugin run for shell plugin flows.
9. Environment notes:
   • Prefer 1Password Environments or service accounts for automation.
   • Keep .env templates in source control; never commit resolved env files.
   • Use Cursor validate hooks (if enabled) to fail fast on missing env vars.

Environments UI quick nav

• Enable Developer: Settings > Developer > Show 1Password Developer experience.
• Open Environments: Developer > View Environments.
• Create environment: New environment.
• Add variables: Import .env file or New variable.
• Manage access: Manage environment > Manage access.
• Configure destinations: Destinations tab > Configure destination.

REQUIRED tmux session (T-Max)

The shell tool uses a fresh TTY per command. To avoid re-prompts and failures, always run op inside a dedicated tmux session with a fresh socket/session name.

Example (see tmux skill for socket conventions, do not reuse old session names):

SOCKET_DIR="${CLAWDBOT_TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/clawdbot-tmux-sockets}"
mkdir -p "$SOCKET_DIR"
SOCKET="$SOCKET_DIR/clawdbot-op.sock"
SESSION="op-auth-$(date +%Y%m%d-%H%M%S)"

tmux -S "$SOCKET" new -d -s "$SESSION" -n shell
tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- "op signin --account my.1password.com" Enter
tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- "op whoami" Enter
tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- "op vault list" Enter
tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -200
tmux -S "$SOCKET" kill-session -t "$SESSION"

Guardrails

• Never paste secrets into logs, chat, or code.
• Prefer op run / op inject over writing secrets to disk.
• If sign-in without app integration is needed, use op account add.
• If a command returns "account is not signed in", re-run op signin inside tmux and authorize in the app.
• Do not run op outside tmux; stop and ask if tmux is unavailable.

Compliance

• Follow repo and platform security standards (least privilege, no plaintext secrets).

Scope and triggers

• Use this skill when the task matches its description and triggers.
• If the request is outside scope, route to the referenced skill.

Response format (required)

• For normal requests, include a ## Outputs section describing delivered artifacts.
• For edge cases with missing info, include a ## Inputs section listing what is missing.

Cognitive Support / Plain-Language

• Optimize for low cognitive load (TBI support): one task at a time, explicit steps.

• Use plain language first; define jargon in parentheses.

• Keep steps short and checklist-driven where possible.

• Externalize state: decisions, assumptions, and the next step.

• Provide ELI5 explanations for non-trivial logic.

• Ask one question at a time; prefer multiple-choice when possible.

• For out-of-scope requests, include a ## When to use section explaining the correct trigger.

Required inputs

• User request details and any relevant files/links.

Deliverables

• A structured response or artifact appropriate to the skill.
• Include schema_version: 1 if outputs are contract-bound.

Constraints

• Redact secrets/PII by default.
• Avoid destructive operations without explicit user direction.

Validation

• Run any relevant checks or scripts when available.
• Fail fast and report errors before proceeding.

Philosophy

• Favor clarity, explicit tradeoffs, and verifiable outputs.

Anti-patterns

• Avoid vague guidance without concrete steps.
• Do not invent results or commands.
• Do not add features outside the agreed scope.

Procedure

1. Clarify scope and inputs.
2. Execute the core workflow.
3. Summarize outputs and next steps.

Variation

• Vary tone, depth, and structure based on context.
• Avoid repeating the same outline across outputs.

Remember

The agent is capable of extraordinary work in this domain. Use judgment, adapt to context, and push boundaries when appropriate.

<!-- skill-score-boost-v1 -->

Philosophy and tradeoffs

• Use this skill when consistent decision-making matters more than one-off execution because project context should drive the approach.
• Principle and mindset: prioritize tradeoffs and constraints over rigid checklists; understand why each step exists.
• Ask this to keep outcomes robust: Why is this the right default, and what could change this outcome?
• How do we adapt if constraints shift?
• What evidence is needed before choosing one path over another?

Anti-patterns and caveats

• Avoid applying this playbook generically without checking repository-specific context.
• NEVER skip required validation gates when behavior changes.
• DO NOT use this skill as a rigid replacement for engineering judgment.
• DON'T ignore warnings or assume one pattern fits all repos.
• Common pitfall: treating anti-patterns as optional.
• Incorrect assumptions here can lead to fragile guidance.
• Warning: wrong sequencing can create avoidable regressions.

Variation and adaptation

• Vary the workflow by team size, risk, and deployment target.
• Use different strategies for small, medium, and large changes.
• Adapt recommendations to the specific environment and avoid repetitive templates.
• Avoid generic or cookie-cutter responses; craft context-specific alternatives.
• Keep outputs diverse and not repetitive.
• Converge on a custom path only after evidence review.
• Different constraints should produce different, non-generic recommendations.

Empowering execution style

• Be capable of exploring multiple options and enabling the team to make safe decisions.
• Unlock confidence by explaining options and tradeoffs clearly.
• Feel free to be creative while staying rigorous and precise.
• Push boundaries with practical alternatives when simple recipes fail.
• Enable outcomes-oriented problem solving.