/1password
1Password admin with Etan present (add/rotate/migrate; op = Touch ID). To use a key, load ~/.config/golems/*.env.
$ golems-cli skills install 1passwordUpdated 2 weeks ago
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. oponly 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
.envfile is missing, stop and ask the lead; don't reach forop.
Prerequisites Check
Only for a deliberate admin task with Etan present (it is itself an op call). Run first:
op account listIf "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)
- Enable Developer features ā Settings > Developer > Enable Developer Experience
- Create Environment ā Developer > Environments > New Environment
- Import your .env ā Click Import or manually add variables
- Set Mount Destination ā Destinations tab > Local .env file > Choose path
- Authorize ā Confirm when prompted
Environments vs CLI: When to Use Each
| Scenario | Use Environments | Use CLI (op run/op inject) |
|---|---|---|
| Local development | ā Best choice | Works but more setup |
| CI/CD pipelines | ā Can't automate creation | ā Service accounts |
| Team secrets | ā Built-in sharing | Manual sync needed |
| One-time scripts | Overkill | ā Quick and easy |
| Template configs | N/A | ā
op inject with .tpl |
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 dotenvop 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 onlyWorking 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 processExample: Golems Configuration
The golems ecosystem uses Environments for sensitive settings:
- Create Environment in 1Password:
golems - Add variables:
NTFY_TOPIC,ANTHROPIC_API_KEY,LINEAR_API_KEY - Mount to:
~/.config/golems/.env - Usage: Scripts source the mounted file, per command, in a subshell
( set -a; . ~/.config/golems/.env; set +a; bun run start )Important Limitations (Beta)
| Limitation | Details |
|---|---|
| UI-only creation | Cannot create/edit environments via CLI |
| Platform support | Mac and Linux only (no Windows) |
| Max mounts | 10 enabled .env files per device |
| Concurrent reads | May have conflicts with multiple processes |
| Edits in UI only | Changes to mounted file are lost - edit in 1Password UI |
| Beta status | Feature may change |
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.tplor.json.tplfiles with secret refs - Windows - Environments not available on Windows
Full SKILL.md source ā includes LLM directives, anti-patterns, and technical instructions stripped from the Overview tab.
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. oponly 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
.envfile is missing, stop and ask the lead; don't reach forop.
Prerequisites Check
Only for a deliberate admin task with Etan present (it is itself an op call). Run first:
op account listIf "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)
- Enable Developer features ā Settings > Developer > Enable Developer Experience
- Create Environment ā Developer > Environments > New Environment
- Import your .env ā Click Import or manually add variables
- Set Mount Destination ā Destinations tab > Local .env file > Choose path
- Authorize ā Confirm when prompted
Environments vs CLI: When to Use Each
| Scenario | Use Environments | Use CLI (op run/op inject) |
|---|---|---|
| Local development | ā Best choice | Works but more setup |
| CI/CD pipelines | ā Can't automate creation | ā Service accounts |
| Team secrets | ā Built-in sharing | Manual sync needed |
| One-time scripts | Overkill | ā Quick and easy |
| Template configs | N/A | ā
op inject with .tpl |
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 dotenvop 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 onlyWorking 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 processExample: Golems Configuration
The golems ecosystem uses Environments for sensitive settings:
- Create Environment in 1Password:
golems - Add variables:
NTFY_TOPIC,ANTHROPIC_API_KEY,LINEAR_API_KEY - Mount to:
~/.config/golems/.env - Usage: Scripts source the mounted file, per command, in a subshell
( set -a; . ~/.config/golems/.env; set +a; bun run start )Important Limitations (Beta)
| Limitation | Details |
|---|---|
| UI-only creation | Cannot create/edit environments via CLI |
| Platform support | Mac and Linux only (no Windows) |
| Max mounts | 10 enabled .env files per device |
| Concurrent reads | May have conflicts with multiple processes |
| Edits in UI only | Changes to mounted file are lost - edit in 1Password UI |
| Beta status | Feature may change |
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.tplor.json.tplfiles with secret refs - Windows - Environments not available on Windows
Quick Actions
| What you want to do | Workflow |
|---|---|
| Use 1Password Environments | workflows/use-environment.md |
| List secrets in vault | workflows/list-secrets.md |
| Add a new secret | workflows/add-secret.md |
| Migrate .env to 1Password | workflows/migrate-env.md |
| Migrate MCP config secrets | workflows/migrate-mcp.md |
| Fix auth/biometric issues | 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/skills/1password/scripts/migrate-env.sh .env [--dry-run] |
scripts/scan-mcp-secrets.sh | Find API keys in MCP configs | bash ~/.claude/skills/1password/scripts/scan-mcp-secrets.sh |
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:
| 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 | 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
# Create project vault
op vault create "myproject" --description "MyProject secrets" --icon buildings
# Create tools vault
op vault create "development" --description "Global dev tools" --icon gearsWhere 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:
| 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
# Vault/Item/Field
op://development/example-mcp/API_KEY
op://myproject/linear/API_KEY
op://Private/github/tokenSafety Rules
- Never log secret values - Only show masked versions
- Dry-run first - Use
--dry-runbefore actual migration - Don't delete .env files - Migration creates .env.template alongside
- Verify vault access - Run
op vault listbefore operations - Backup before bulk changes - Export vault if doing large migrations
Not yet evaluated on current models
Results will appear here once runs with a recorded model are published.
Changelog entries are derived from skill version updates. Full cascading changelog (Phase 4D) coming soon.
- +Initial release to Golems skill library
- +4 eval scenarios defined
- +6 workflows included: add-secret, list-secrets, migrate-env, migrate-mcp, troubleshoot, use-environment