# 1password

> Use when managing secrets, credentials, API keys, or vault operations. Covers 1password, secrets, op, vault, migrate, credentials, mcp config secrets.

- Author: Etan Joseph Heyman
- Repository: EtanHey/claude-golem
- Version: 20260124150711
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/EtanHey/claude-golem
- Web: https://mule.run/skillshub/@@EtanHey/claude-golem~1password:20260124150711

---

---
name: 1password
description: Use when managing secrets, credentials, API keys, or vault operations. Covers 1password, secrets, op, vault, migrate, credentials, mcp config secrets.
---

# 1Password Operations

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

## Prerequisites Check

Run first:
```bash
op account list
```

If "not signed in" or error: See [workflows/troubleshoot.md](workflows/troubleshoot.md)

---

## 🌟 PREFERRED: 1Password Environments (Beta)

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

[Official Docs →](https://developer.1password.com/docs/environments/)

### Why Environments?

- **UI-based setup** - No CLI commands needed for configuration
- **Real-time sync** - Changes in 1Password instantly available
- **Named pipe mount** - Secrets never written to disk as plain text
- **Multi-device** - Same environment works across all your machines

### Setup Flow (One-Time)

1. **Open 1Password app** → Developer → Environments → Create Environment
2. **Import your .env** → Select the file or paste variables manually
3. **Set Mount Destination** → Destinations tab → Add path (e.g., `.env.local`)
4. **Activate** → Environment mounts automatically when 1Password is running

### 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.

### Important Limitations (Beta)

| Limitation | Details |
|------------|---------|
| **CLI invisible** | `op env list` cannot see UI-created environments |
| **Edits in UI only** | Changes to mounted file are lost - edit in 1Password UI |
| **Header marker** | Mounted file shows `# Generated by 1Password` at top |
| **Beta status** | Feature may change; CLI support coming later |

### When to Use CLI Instead

Use manual `op item create` ([workflows/migrate-env.md](workflows/migrate-env.md)) when:
- Automating migration in CI/CD pipelines
- Creating items programmatically from scripts
- Need to share secrets via templates (.env.template with op:// refs)

---

## Quick Actions

| What you want to do | Workflow |
|---------------------|----------|
| List secrets in vault | [workflows/list-secrets.md](workflows/list-secrets.md) |
| Add a new secret | [workflows/add-secret.md](workflows/add-secret.md) |
| Migrate .env to 1Password | [workflows/migrate-env.md](workflows/migrate-env.md) |
| Migrate MCP config secrets | [workflows/migrate-mcp.md](workflows/migrate-mcp.md) |
| Fix auth/biometric issues | [workflows/troubleshoot.md](workflows/troubleshoot.md) |

---

## Available Scripts

Execute directly - they handle errors and edge cases:

| Script | Purpose | Usage |
|--------|---------|-------|
| `scripts/migrate-env.sh` | Migrate .env with project/service nesting | `bash ~/.claude/commands/1password/scripts/migrate-env.sh .env [--dry-run]` |
| `scripts/scan-mcp-secrets.sh` | Find API keys in MCP configs | `bash ~/.claude/commands/1password/scripts/scan-mcp-secrets.sh` |

---

## Decision Tree

**Need to find a secret?**
- Search by name, tag, or vault
- Use: [workflows/list-secrets.md](workflows/list-secrets.md)

**Adding credentials for a service?**
- Create new item with password/API key
- Use: [workflows/add-secret.md](workflows/add-secret.md)

**Have a .env file to secure?**
- Auto-categorize by service (anthropic, supabase, etc.)
- Use: [workflows/migrate-env.md](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](workflows/migrate-mcp.md)

**Biometric timeout or auth problems?**
- Token refresh, re-auth, session issues
- Use: [workflows/troubleshoot.md](workflows/troubleshoot.md)

---

## Service Auto-Detection

When migrating secrets, keys are auto-categorized:

| Key prefix | Service folder |
|------------|----------------|
| `ANTHROPIC_*` | anthropic/ |
| `OPENAI_*` | openai/ |
| `SUPABASE_*` | supabase/ |
| `DATABASE_*`, `DB_*` | db/ |
| `STRIPE_*` | stripe/ |
| `AWS_*` | aws/ |
| `GITHUB_*` | github/ |
| Other | misc/ |

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

---

## Vault Organization

### Vault Types

| Vault | Purpose | Example Items |
|-------|---------|---------------|
| `development` | Global dev tools | context7, github CLI tokens |
| `Private` | Personal secrets | SSH keys, personal accounts |
| `{project}` | Project-specific | linear API key, deploy keys |
| `Shared` | Team secrets | Shared service accounts |

### Creating Vaults

```bash
# 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:
- context7, 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:

```bash
# Add tags when creating
op item create --vault development --category "API Credential" \
  --title "context7" '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:**
| Tag | Use for |
|-----|---------|
| `dev-tools` | Development utilities |
| `mcp` | MCP server credentials |
| `ci-cd` | CI/CD pipeline secrets |
| `api-key` | Third-party API keys |
| `deploy` | Deployment credentials |
| `{project}` | Project name for filtering |

### Reference Format

```bash
# Vault/Item/Field
op://development/context7/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