Skip to main content
skill CX Codex

1password-cli — Claude Code skill: what it does, install

This skill guides AI agents through 1Password CLI for reading secrets, filling development environments, and managing vault items. It fits local work and CI/CD.

MIT 2 installs ★ 1 updated 2025-12-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add research-developer/1password-cli-skill --skill 1password-cli -a claude-code
Open on GitHub

What 1password-cli does

The skill covers the op command for listing vaults and items, reading fields through op://vault/item/field references, returning item data as JSON, and working with selected fields. It also describes creating, editing, and deleting 1Password items from the CLI.

It shows how to pass secrets to processes with op run and .env files. This includes starting npm or Python commands with injected variables while keeping values masked in command output. Authentication options include desktop app integration, manual sign-in, and the OP_SERVICE_ACCOUNT_TOKEN environment variable.

CI/CD requires a service account token rather than interactive user authentication. The 1Password CLI is installed separately; on macOS, the documented command is brew install 1password-cli, followed by op --version to verify it.

What it helps with

  • read an API key from a vault using an op:// reference
  • start a local process with secrets from .env
  • inject environment variables with op run
  • search vaults and items through the op CLI
  • create or update a 1Password item from a script

Example prompts for the agent

  • Read op://Private/OpenAI/api-key and pass the value to the requested command without printing the secret.
  • Start npm run dev with variables from .env.local using op run.
  • List the available vaults, then find the item that contains the API key.

How to install 1password-cli

1Skills CLI (Vercel)

npx skills add research-developer/1password-cli-skill --skill 1password-cli -a claude-code

2Manually: put the files in place

~/.claude/skills/1password-cli/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/1password-cli/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about 1password-cli

How do I install 1password-cli in Claude Code?

Run npx skills add research-developer/1password-cli-skill --skill 1password-cli -a claude-code, then check ~/.claude/skills/1password-cli/SKILL.md.

What does the 1password-cli skill do?

It gives the agent instructions for using op to read secrets, find and manage 1Password items, and run commands with injected environment values.

How should I use 1password-cli in CI/CD?

Set OP_SERVICE_ACCOUNT_TOKEN and run op commands without interactive sign-in. The skill recommends limiting the service account to the vaults required by the automation.

Source text

SKILL.md · MIT
---
name: 1password-cli
description: Use this skill when working with the 1Password CLI (`op` command) for secrets management, retrieving API keys, injecting secrets into development environments, or any task involving 1Password vault operations. Triggers on: "1password", "op command", "secrets management", "api keys from vault", "op run", "op read", "service account token".
---

# 1Password CLI Skill

Use this skill when working with the 1Password CLI (`op` command) for secrets management, retrieving API keys, or injecting secrets into development environments.

## Installation

```bash
# macOS
brew install 1password-cli

# Verify installation
op --version
```

## Authentication Methods

### 1. Desktop App Integration (Interactive - Recommended for Development)

Enable biometric authentication (Touch ID/Windows Hello) through the 1Password desktop app:

1. Open 1Password app > Settings > Developer
2. Enable "Integrate with 1Password CLI"
3. Run any `op` command - you'll be prompted to authenticate

```bash
# This will prompt for biometric auth
op vault list
```

### 2. Service Account Token (Non-Interactive - CI/CD & Automation)

For automated environments without user interaction:

```bash
# Set the service account token as environment variable
export OP_SERVICE_ACCOUNT_TOKEN="ops_..."

# Now commands work without prompts
op vault list
```

Create service accounts in 1Password.com > Developer Tools > Service Accounts.

### 3. Manual Sign In (Legacy)

```bash
# Sign in and create a session
eval $(op signin)

# Or for a specific account
eval $(op signin --account my-team.1password.com)
```

## Secret Reference Syntax

Secret references use the URI format: `op://vault/item/[section/]field`

```
op://vault-name/item-name/field-name           # Simple field
op://vault-name/item-name/section/field-name   # Field in a section
op://Private/GitHub/password                    # Example: GitHub password
op://dev/Stripe/publishable-key                # Example: Stripe key
```

### Get Secret References

```bash
# Get reference for a specific field
op item get "GitHub" --vault Private --fields password --format json | jq -r '.reference'

# Output: op://Private/GitHub/password
```

## Reading Secrets

### Read a Single Secret

```bash
# Using secret reference
op read "op://vault-name/item-name/field-name"

# Examples
op read "op://Private/API Keys/openai-key"
op read "op://dev/Database/password"
```

### Get Item Details

```bash
# Get full item as JSON
op item get "item-name" --vault "vault-name" --format json

# Get specific field
op item get "GitHub" --fields password

# Get multiple fields
op item get "Database" --fields username,password
```

### List Items

```bash
# List all vaults
op vault list

# List items in a vault
op item list --vault "Private"

# Search for items
op item list --tags api-key
```

## Injecting Secrets into Environment Variables

### Using `op run`

The most secure way to use secrets - they exist only during command execution:

```bash
# Set secret reference in environment
export DB_PASSWORD="op://app-prod/database/password"

# Run command with secrets injected
op run -- ./my-script.sh

# Secrets are automatically masked in output
op run -- printenv DB_PASSWORD  # Shows: <concealed by 1Password>

# Disable masking if needed
op run --no-masking -- printenv DB_PASSWORD
```

### Using .env Files

Create a `.env` file with secret references:

```bash
# .env file
DATABASE_URL="op://dev/postgres/connection-string"
API_KEY="op://dev/my-api/key"
SECRET_TOKEN="op://dev/app/secret-token"
```

Run with the env file:

```bash
op run --env-file=.env -- npm start
op run --env-file=.env -- python app.py
```

### Environment-Specific Secrets

Use variables to switch between environments:

```bash
# .env file with variable
DB_PASSWORD="op://$APP_ENV/database/password"

# Switch environments
APP_ENV=dev op run --env-file=.env -- ./start.sh
APP_ENV=prod op run --env-file=.env -- ./start.sh
```

## Common Use Cases

### Retrieve API Keys for Development

```bash
# Get a single API key
OPENAI_KEY=$(op read "op://Private/OpenAI/api-key")

# Use in a command
curl -H "Authorization: Bearer $(op read 'op://Private/OpenAI/api-key')" ...
```

### Populate Environment for Local Development

```bash
# Create .env.local with secret references
cat > .env.local << 'EOF'
SUPABASE_URL="op://dev/Supabase/url"
SUPABASE_KEY="op://dev/Supabase/service-role-key"
ANTHROPIC_API_KEY="op://dev/Anthropic/api-key"
EOF

# Start development server with secrets
op run --env-file=.env.local -- npm run dev
```

### Export Secrets to Shell Session

```bash
# Export secrets for current shell session
export GITHUB_TOKEN=$(op read "op://Private/GitHub/token")
export NPM_TOKEN=$(op read "op://Private/npm/token")
```

### Use in Scripts

```bash
#!/bin/bash
# deploy.sh - uses 1Password for secrets

# Ensure we have access
op whoami > /dev/null 2>&1 || eval $(op signin)

# Get deployment credentials
DEPLOY_KEY=$(op read "op://prod/deploy/ssh-key")
API_TOKEN=$(op read "op://prod/api/token")

# Use in deployment...
```

## Creating and Managing Items

### Create a New Item

```bash
# Create API key item
op item create \
  --category "API Credential" \
  --title "My API Key" \
  --vault "dev" \
  --fields "api-key=sk-abc123"

# Create login item
op item create \
  --category Login \
  --title "Service Account" \
  --vault Private \
  --fields "username=admin,password=secret123"
```

### Update an Item

```bash
# Update a field
op item edit "My API Key" --vault dev "api-key=sk-newkey456"
```

### Delete an Item

```bash
op item delete "Old API Key" --vault dev
```

## Security Best Practices

1. **Use Service Accounts for CI/CD**: Never use personal credentials in automated environments

2. **Limit Vault Access**: Service accounts should only access vaults they need

3. **Use `op run` Over Export**: Secrets only exist during command execution, not in shell history

4. **Avoid Logging Secrets**: `op run` masks secrets by default - keep it enabled

5. **Rotate Service Account Tokens**: Regularly rotate tokens used in CI/CD pipelines

6. **Use Secret References in Code**: Store references, not secrets, in configuration files

7. **Audit Access**: Review service account usage reports in 1Password.com

## Troubleshooting

### "You are not currently signed in"

```bash
# Check current session
op whoami

# Sign in again
eval $(op signin)

# Or set service account token
export OP_SERVICE_ACCOUNT_TOKEN="ops_..."
```

### "Item not found"

```bash
# List available vaults to verify access
op vault list

# Search for the item
op item list --vault "vault-name" | grep "item-name"
```

### Desktop App Integration Not Working

1. Ensure 1Password app is running and unlocked
2. Check Settings > Developer > "Integrate with 1Password CLI" is enabled
3. Restart terminal after enabling integration

## Quick Reference

| Command | Description |
|---------|-------------|
| `op vault list` | List all accessible vaults |
| `op item list --vault X` | List items in vault X |
| `op item get "Name"` | Get item details |
| `op read "op://..."` | Read a secret value |
| `op run -- cmd` | Run command with secrets |
| `op run --env-file=.env -- cmd` | Run with .env secrets |
| `op whoami` | Check current session |
| `op signin` | Sign in interactively |

© research-developer · MIT · research-developer/1password-cli-skill

Similar skills

All skills for Security →

Project sponsors

Companies that keep this analytics open