bw-cli

Files (6)

• SKILL.md
• _meta.json
• commands.md · references/
• create-login-item.sh · scripts/
• safe-get-field.sh · scripts/
• unlock-session.sh · scripts/

SKILL.md (first lines)

# Bitwarden CLI Skill

Secure vault operations using the Bitwarden command-line interface.

## When to use

**Activate this skill when the user wants to:**
- Authenticate to Bitwarden (`login`, `unlock`, `logout`, `status`)
- Retrieve credentials (`get password`, `get username`, `get totp`, `get item`)
- Manage vault items (`list`, `create`, `edit`, `delete`, `restore`)
- Generate passwords/passphrases (`generate`)
- Handle attachments (`create attachment`, `get attachment`)
- Manage organizations (`list organizations`, `move`, `confirm`)
- Export/import vault data
- Work with Vaultwarden/self-hosted instances

**Do NOT use for:**
- Installing Bitwarden browser extensions or mobile apps
- Comparing password managers theoretically
- Self-hosting Bitwarden server setup (use server administration tools)
- General encryption questions unrelated to Bitwarden

## Prerequisites

- `bw` CLI installed (verify with `bw --version`)
- Internet access (or access to self-hosted server)
- For vault operations: valid `BW_SESSION` environment variable or interactive unlock

## Authentication & Session Management

Bitwarden CLI uses a two-step authentication model:
1. **Login** (`bw login`) - Authenticates identity, creates local vault copy
2. **Unlock** (`bw unlock`) - Decrypts vault, generates session key

### ⚠️ ALWAYS Sync Before Accessing Vault

**CRITICAL:** The Bitwarden CLI maintains a local copy of the vault that can become stale. **Always run `bw sync` before accessing vault data** to ensure you have the latest items:

```bash
# Sync vault before any retrieval operation
bw sync

# Then proceed with vault operations
bw get item "Coda API Token"
```

**Best practice pattern for all vault operations:**
1. Check status / unlock if needed
2. **Run `bw sync`** (always!)
3. Then list, get, create, edit items

This prevents working with outdated data, especially when:
- Items were added/updated via other devices or browser extensions
- Working with shared organization items
- Recent changes haven't propagated to the local vault copy

### Quick Start: Interactive Login

```bash
# Login (supports email/password, API key, or SSO)
bw login

# Unlock to get session key
bw unlock
# Copy the export command from output, then:
export BW_SESSION="..."
```

### Automated/Scripted Login

Use environment variables for automation:

```bash
# Method 1: API Key (recommended for automation)
export BW_CLIENTID="user.xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
export BW_CLIENTSECRET="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
bw login --apikey
bw unlock --passwordenv BW_PASSWORD # if BW_PASSWORD set

# Method 2: Password file
bw unlock --passwordfile ~/.secrets/bw-master-password.txt
```

### Secure Password Storage (User-Requested)

If the user explicitly requests saving the master password to disk for convenience:

```bash
# 1. Create secrets directory in workspace
mkdir -p ~/.openclaw/workspace/.secrets
chmod 700 ~/.openclaw/workspace/.secrets

# 2. Store password (user enters interactively)
read -s BW_MASTER_PASS
echo "$BW_MASTER_PASS" > ~/.openclaw/workspace/.secrets/bw-password.txt
chmod 600 ~/.openclaw/workspace/.secrets/bw-password.txt

# 3. Ensure git ignores it
echo ".secrets/" >> ~/.openclaw/workspace/.gitignore
```

**Security requirements:**
- File must be created with mode `600` (user read/write only)
- Directory must be mode `700`
- Must add `.secrets/` to `.gitignore` immediately
- Must inform user of risks

### Check Status

```bash
bw status
```

Returns JSON with `status`: `unauthenticated`, `locked`, or `unlocked`.

### End Session

```bash
# Lock (keep login, destroy session key)

From Trompetilla/Skills, MIT.

More from Trompetilla/Skills