/1password

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

Prerequisites Check

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):

# 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, launch with op run.

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

Wrapper scripts:

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 or use op run

# Option 1: Source mounted .env
source ~/.config/golems/.env
 
# Option 2: Use op run with template
op run --env-file ~/.config/golems/.env.template -- 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