1password

Files (1)

• SKILL.md

SKILL.md (first lines)

# 1Password CLI (`op`)

Interact with 1Password vaults and secrets via the `op` CLI.

## This Setup

This environment uses a **service account** for agent access. Key facts:

- **Vault:** `Automation` — the dedicated vault for agent-accessible secrets.
- **Service account token** is stored at: `op://Automation/agent-automation-token/credential`
- **Permissions:** `read_items` only. The agent cannot create or modify items.
- To write new items, the human must use an interactive session (`eval $(op signin)`) or the 1Password web UI.
- The service account was created with `--expires-in 90d` (90 days max). Check expiry if auth fails unexpectedly.

**Bootstrap pattern — always start a session this way:**

```bash
export OP_SERVICE_ACCOUNT_TOKEN=$(op read "op://Automation/agent-automation-token/credential")
op whoami   # verify before proceeding
```

Note: to run `op read` above, `OP_SERVICE_ACCOUNT_TOKEN` must already be set in the environment. The first time (or after rotation), the human must export the token manually.

## Orientation

Run these commands first to understand the environment:

```bash
which op
op --version
op account list
op whoami
```

## Authentication

### Preferred: Service Account Token (non-interactive, works in agent sessions)

Service accounts require no interactive auth and work in headless/automated contexts.

**Setup (one-time, requires an interactive session or web UI):**

1. Create a non-built-in vault if needed (service accounts cannot access Personal/Private/Employee/Shared built-in vaults):
   ```bash
   op vault create Automation
   ```
2. Create the service account with access to that vault:
   ```bash
   op service-account create "agent-automation" --expires-in 90d --vault Automation:read_items,write_items
   ```
   - The token is shown **only once** — save it to 1Password immediately.
   - Available permissions: `read_items`, `write_items` (requires `read_items`), `share_items` (requires `read_items`)
   - Include `--can-create-vaults` if the service account needs to create vaults.

3. Save the token as an `API Credential` item in the Automation vault:
   ```bash
   eval $(op signin)
   op item create \
     --category "API Credential" \
     --title "agent-automation-token" \
     --vault Automation \
     "credential=ops_..."
   ```

4. Verify the reference works:
   ```bash
   op read "op://Automation/agent-automation-token/credential"
   ```

**Usage:**

```bash
export OP_SERVICE_ACCOUNT_TOKEN="ops_..."
op whoami        # verify
op vault list    # should list accessible vaults
```

Set `OP_SERVICE_ACCOUNT_TOKEN` in the environment before running any `op` commands. No `op signin` needed.

### Fallback: Manual session (interactive terminals only)

Not suitable for agent sessions — the session token only lives in the shell that ran `eval $(op signin)` and cannot be passed to subprocesses automatically.

```bash
eval $(op signin)
op whoami
```

Session tokens expire after 30 minutes of inactivity.

## Common Workflows

### Get a username and password

```bash
# Human-readable
op item get "Item Name" --vault VaultName

# Get just the username
op item get "Item Name" --vault VaultName --fields username

# Get just the password
op item get "Item Name" --vault VaultName --fields password

# Both as JSON
op item get "Item Name" --vault VaultName --fields username,password --format json
```

### Get a one-time password (OTP / TOTP)

```bash
# Get the current OTP code
op item get "Item Name" --vault VaultName --otp

# Or via secret reference
op read "op://VaultName/Item Name/one-time password"
```

### Read a secret by reference

From jason-riddle/agent-skills, MIT.

More from jason-riddle/agent-skills