1password

What this skill does

# 1Password

## Overview

This skill provides comprehensive guidance for working with 1Password's secrets management ecosystem. It covers the `op` CLI for local development, service accounts for automation, **Developer Environments for project secrets**, and Kubernetes integrations including the native 1Password Operator and External Secrets Operator.

## Quick Reference

### Command Structure

1Password CLI uses a noun-verb structure: `op <noun> <verb> [flags]`

```bash
# Authentication
op signin                    # Sign in to account
op signout                   # Sign out
op whoami                    # Show signed-in account info

# Secret retrieval
op read "op://vault/item/field"              # Read single secret
op run -- <command>                          # Inject secrets as env vars
op inject -i template.env -o .env            # Inject secrets into file

# Item management
op item list                                 # List all items
op item get <item>                           # Get item details
op item create --category login              # Create new item
op item edit <item> field=value              # Edit item
op item delete <item>                        # Delete item

# Vault management
op vault list                                # List vaults
op vault get <vault>                         # Get vault info
op vault create <name>                       # Create vault

# Document management
op document list                             # List documents
op document get <document>                   # Download document
op document create <file> --vault <vault>    # Upload document
```

## Workflow Decision Tree

```
What do you need to do?
├── Retrieve a secret for local development?
│   └── Use: op read, op run, or op inject
├── Manage project environment variables?
│   └── See: Developer Environments (below)
├── Manage items/vaults in 1Password?
│   └── Use: op item, op vault, op document commands
├── Automate secrets in CI/CD?
│   └── Use: Service Accounts with OP_SERVICE_ACCOUNT_TOKEN
├── Sync secrets to Kubernetes?
│   ├── Using External Secrets Operator?
│   │   └── See: External Secrets Operator Integration
│   └── Using native 1Password Operator?
│       └── See: 1Password Kubernetes Operator
└── Configure shell plugins for CLI tools?
    └── Use: op plugin commands
```

## Developer Environments

Developer Environments provide a dedicated location to store, organize, and manage project secrets as environment variables. CLI tools are available in both TypeScript/Bun and Python SDK variants.

### Feature Overview

| Feature | GUI | TypeScript CLI | Python SDK CLI |
|---------|-----|---------------|----------------|
| Create environment | Yes | `bun run create` | `uv run op-env-create` |
| Update environment | Yes | `bun run update` | `uv run op-env-update` |
| Delete environment | Yes | `bun run delete` | `uv run op-env-delete` |
| Show environment | Yes | `bun run show` | `uv run op-env-show` |
| List environments | Yes | `bun run list` | `uv run op-env-list` |
| Export to .env | Yes | `bun run export` | `uv run op-env-export` |
| Mount .env file | Yes (beta) | No | No |

### CLI Tools Setup (TypeScript)

Tools are written in TypeScript and require [Bun](https://bun.sh) runtime:

```bash
# Navigate to tools directory
cd tools

# Run any tool with bun
bun run src/op-env-create.ts --help
bun run src/op-env-list.ts --help

# Or use npm scripts
bun run create -- --help
bun run list -- --help
```

### CLI Tools Setup (Python SDK)

Python tools use the official `onepassword-sdk` package and require [uv](https://docs.astral.sh/uv/):

```bash
# Navigate to tools-python directory
cd tools-python

# Install dependencies
uv sync

# Run any tool
uv run op-env-create --help
uv run op-env-list --help
```

**Requirements:** Python 3.9+, `OP_SERVICE_ACCOUNT_TOKEN` environment variable.

### When to Use SDK vs CLI

| Use Case | Recommended | Why |
|----------|------------|-----|
| Python applications (FastAPI, Django) | Python SDK | Native async, no subprocess overhead |
| Shell scripts, CI/CD pipelines | TypeScript CLI or `op` CLI | Direct CLI integration |
| Batch secret resolution | Python SDK | `resolve_all()` for efficiency |
| Tag-based filtering | TypeScript CLI | SDK lacks tag filter support |
| Interactive local development | Either | Both have identical interfaces |

### SecretsManager (Python SDK)

For Python applications that need runtime secret resolution:

```python
from op_env.secrets_manager import SecretsManager

async def main():
    sm = await SecretsManager.create()

    # Single secret (with caching)
    api_key = await sm.get("op://Production/API/key")

    # Batch resolve
    secrets = await sm.get_many([
        "op://Production/DB/password",
        "op://Production/DB/host",
    ])

    # Load all vars from an environment item
    env = await sm.resolve_environment("my-app-prod", "Production")
```

See `references/python-sdk.md` for full SDK reference and integration patterns.

### Environment Workflow

#### 1. Create Environment

```bash
# From inline variables
bun run src/op-env-create.ts my-app-dev Personal \
    API_KEY=secret \
    DB_HOST=localhost \
    DB_PORT=5432

# From .env file
bun run src/op-env-create.ts my-app-prod Production --from-file .env.prod

# Combine file + inline (inline overrides file)
bun run src/op-env-create.ts azure-config Shared --from-file .env EXTRA_KEY=value

# With custom tags
bun run src/op-env-create.ts secrets DevOps --tags "env,production,api" KEY=value
```

#### 2. List Environments

```bash
# List all environments (tagged with 'environment')
bun run src/op-env-list.ts

# Filter by vault
bun run src/op-env-list.ts --vault Personal

# Filter by tags
bun run src/op-env-list.ts --tags "production"

# JSON output
bun run src/op-env-list.ts --json
```

#### 3. Show Environment Details

```bash
# Show with masked values (default)
bun run src/op-env-show.ts my-app-dev Personal

# Show with revealed values
bun run src/op-env-show.ts my-app-dev Personal --reveal

# JSON output
bun run src/op-env-show.ts my-app-dev Personal --json

# Show only variable names
bun run src/op-env-show.ts my-app-dev Personal --keys
```

#### 4. Update Environment

```bash
# Update/add single variable
bun run src/op-env-update.ts my-app-dev Personal API_KEY=new-key

# Merge from .env file
bun run src/op-env-update.ts my-app-dev Personal --from-file .env.local

# Remove variables
bun run src/op-env-update.ts my-app-dev Personal --remove OLD_KEY,DEPRECATED

# Update and remove in one command
bun run src/op-env-update.ts my-app-dev Personal NEW_KEY=value --remove OLD_KEY
```

#### 5. Export Environment

```bash
# Export to .env file (standard format)
bun run src/op-env-export.ts my-app-dev Personal > .env

# Docker-compatible format (quoted values)
bun run src/op-env-export.ts my-app-dev Personal --format docker > .env

# op:// references template (for op run/inject)
bun run src/op-env-export.ts my-app-dev Personal --format op-refs > .env.tpl

# JSON format
bun run src/op-env-export.ts my-app-dev Personal --format json

# Add prefix to all variables
bun run src/op-env-export.ts azure-config Shared --prefix AZURE_ > .env
```

#### 6. Delete Environment

```bash
# Interactive deletion (asks for confirmation)
bun run src/op-env-delete.ts my-app-dev Personal

# Force delete without confirmation
bun run src/op-env-delete.ts my-app-dev Personal --force

# Archive instead of permanent delete
bun run src/op-env-delete.ts my-app-dev Personal --archive
```

### Environment Secret Reference

Access individual variables using the secret reference format:

```
op://<vault>/<environment>/variables/<key>
```

Example:
```bash
# Read single variable
op read "op://Personal/my-app-dev/variables/API_KEY"

# Use in template file (.env.tpl)
API_KEY=op://Personal/my-app-dev/variables/API_KEY
DB_HOST=op://Personal/my-app-dev/variables/DB_HOST
```

### Integration Patterns

#### With op run (recommended)

```bash
# 1. Export environment as op://