1Password Operations

Secret management skill using 1Password CLI (op). Routes to workflows for specific operations.

Never call op for routine secrets

Every op call asks Etan for his fingerprint (1Password Touch ID). Agents calling op for routine work, plus agents ssh-ing through the 1Password SSH agent, made him approve prompts all day (measured 2026-11-01). So:

• Using a key (live tests, API calls, CLIs): load the per-tool file under ~/.config/golems/ for that one command, in a subshell: ( set -a; . ~/.config/golems/<tool>.env; set +a; <cmd> ). Never print or echo the value.
• op only for a deliberate, one-time step Etan is there to approve: adding, rotating or migrating a secret, or regenerating a launcher cache (repogolem generate). Say beforehand that a Touch ID prompt is coming. Never in loops, hooks, schedules, health checks or as a fallback.
• If a needed .env file is missing, stop and ask the lead; don't reach for op.

Prerequisites Check

Only for a deliberate admin task with Etan present (it is itself an op call). Run first:

op account list

If "not signed in" or error: See workflows/troubleshoot.md

🌟 PREFERRED: 1Password Environments (Beta)

For .env file management, use 1Password Environments instead of manual CLI migration.

Official Docs → | Full Workflow →

Key Insight: UI Creation, CLI Access

Environments are created in the 1Password desktop app UI - not via CLI. However, once created, CLI tools can still interact with secrets via op run and op inject.

┌─────────────────────────────────────────────────────────────┐
│                    ENVIRONMENTS WORKFLOW                     │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  CREATION (UI Only)           ACCESS (Multiple Options)     │
│  ─────────────────            ─────────────────────────     │
│  1Password Desktop App   ──►  • Mounted .env (named pipe)   │
│  • Developer > Environments   • op run (env vars)           │
│  • NOT automatable            • op inject (config files)    │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Why Environments?

• Secrets never on disk - Named pipe mount, not plaintext file
• Real-time sync - Changes in 1Password instantly available
• Team sharing - Grant access with granular permissions
• Multi-device - Same environment works across all your machines

Setup Flow (One-Time in Desktop App)

1. Enable Developer features → Settings > Developer > Enable Developer Experience
2. Create Environment → Developer > Environments > New Environment
3. Import your .env → Click Import or manually add variables
4. Set Mount Destination → Destinations tab > Local .env file > Choose path
5. Authorize → Confirm when prompted

Environments vs CLI: When to Use Each

Mounted .env vs op inject

Mounted .env (Environments):

# App reads .env.local directly (named pipe, no real file)
npm run dev
# Variables available automatically via dotenv

op inject (CLI):

# Template file with secret references (.env.template)
DATABASE_URL=op://prod/db/url
API_KEY=op://prod/api/key

# Inject at runtime
op inject -i .env.template -o .env && npm run build
# Remember to delete .env after!

op run (CLI; Etan's own interactive runs only, since each call is a Touch ID prompt; agents load ~/.config/golems/*.env):

# Pass secrets as environment variables
op run --env-file .env.template -- npm run build
# No temp file created, secrets in process env only

Working Example: songscript

The songscript project uses Environments with 9 variables mounted to .env.local:

• Environment contains: CONVEX_DEPLOY_KEY, ANTHROPIC_API_KEY, etc.
• Destination: .env.local (named pipe, not actual file)
• Works seamlessly with bun dev, npm run dev, etc.

Centralized MCP Secrets (Recommended for Agents)

Problem: Each MCP with op:// refs triggers separate auth prompts.

Solution: Centralize all secrets in one file. For agents, that file is a resolved ~/.config/golems/*.env, loaded per command (see the rule at the top). An op run launcher prompts for Touch ID on every launch, so it is only for a session Etan starts himself.

~/.config/mcp-secrets/
├── secrets.env          # All op:// refs (one auth loads all)
└── secrets.env.example  # Template (safe to share)

Wrapper scripts (Etan's own interactive sessions only; never for agent launches):

cursor-secure   # op run --env-file secrets.env -- cursor
claude-secure   # op run --env-file secrets.env -- claude
with-secrets    # op run --env-file secrets.env -- <any command>

MCP configs use empty env:

{ "env": {} }  // Inherits from parent process

Example: Golems Configuration

The golems ecosystem uses Environments for sensitive settings:

1. Create Environment in 1Password: golems
2. Add variables: NTFY_TOPIC, ANTHROPIC_API_KEY, LINEAR_API_KEY
3. Mount to: ~/.config/golems/.env
4. Usage: Scripts source the mounted file, per command, in a subshell

( set -a; . ~/.config/golems/.env; set +a; bun run start )

Important Limitations (Beta)

When to Use CLI Instead

Use op run or op inject (workflows/migrate-env.md) when:

• CI/CD pipelines - Need Service Accounts for automated access
• Scripted operations - Creating items programmatically
• Template configs - .yml.tpl or .json.tpl files with secret refs
• Windows - Environments not available on Windows

Quick Actions

Available Scripts

Execute directly - they handle errors and edge cases:

Decision Tree

Setting up secrets for a project?

• PREFERRED: Use Environments (desktop app UI)
• Use: workflows/use-environment.md

Need to find a secret?

• Search by name, tag, or vault
• Use: workflows/list-secrets.md

Adding credentials for a service?

• Create new item with password/API key
• Use: workflows/add-secret.md

Have a .env file to secure?

• For local dev: Use Environments (UI-based)
• For CI/CD: Use workflows/migrate-env.md or scripts/migrate-env.sh

MCP configs have hardcoded keys?

• Scan and migrate to 1Password references
• Use: workflows/migrate-mcp.md

Biometric timeout or auth problems?

• Token refresh, re-auth, session issues
• Use: workflows/troubleshoot.md

Service Auto-Detection

When migrating secrets, keys are auto-categorized:

Item path format: {project}/{service}/{key}

Vault Organization

Vault Types

Creating Vaults

# Create project vault
op vault create "myproject" --description "MyProject secrets" --icon buildings

# Create tools vault
op vault create "development" --description "Global dev tools" --icon gears

Where to Put Secrets

Global dev tools → development vault:

• Shared MCP tools, IDE plugins
• Used across all projects

Project-specific → {project} vault:

• Linear API keys (per workspace)
• Deploy keys, CI/CD tokens
• Database credentials

Personal → Private vault:

• SSH keys, personal tokens
• Accounts only you use

Tagging Strategy

Use tags for cross-vault searching and organization:

# Add tags when creating
op item create --vault development --category "API Credential" \
  --title "example-mcp" 'API_KEY[password]=xxx' \
  --tags "dev-tools,mcp,documentation"

# Search by tag across all vaults
op item list --tags "mcp"
op item list --tags "dev-tools"

Recommended tags:

Reference Format

# Vault/Item/Field
op://development/example-mcp/API_KEY
op://myproject/linear/API_KEY
op://Private/github/token

Safety Rules

1. Never log secret values - Only show masked versions
2. Dry-run first - Use --dry-run before actual migration
3. Don't delete .env files - Migration creates .env.template alongside
4. Verify vault access - Run op vault list before operations
5. Backup before bulk changes - Export vault if doing large migrations