---
name: pws
description: Password Safe commands for credentials, systems, accounts, secrets, and user management. Use when working with PWS checkouts, managed systems, Secrets Safe, or credential rotation.
---

# Password Safe Commands (`bt pws`)

## IMPORTANT: Destructive Operations

**ALWAYS confirm with the user before:**
- `bt pws systems delete` - Deletes managed system
- `bt pws accounts delete` - Deletes managed account
- `bt pws secrets safes delete` - Deletes entire safe
- `bt pws secrets folders delete` - Deletes folder and contents
- `bt pws quick offboard` - Removes system + accounts + asset

List affected resources first, then ask for explicit confirmation.

## Quick Commands (Most Common)

```bash
# Checkout credentials
bt pws quick checkout -s "axion-finapp-01" -a "root"
bt pws quick checkout -s axion -a root --duration 30 --reason "Maintenance"
PASSWORD=$(bt pws quick checkout -s server -a admin --raw)

# Check in
bt pws quick checkin 17
bt pws quick checkin 17 --rotate

# Quick password lookup with auto-checkin
bt pws quick password -s "axion-finapp-01" -a "root"

# Search systems and accounts
bt pws quick search axion
bt pws quick search root -o json

# Rotate password
bt pws quick rotate -s "axion-finapp-01" -a "root"

# Onboard system (asset + system + account)
bt pws quick onboard -n "my-server" -i "10.0.1.50" -w 3
bt pws quick onboard -n "web-01" -i "10.0.1.100" -w 3 -f 7 -e "sudo"

# Offboard system
bt pws quick offboard -s "my-server"
bt pws quick offboard -s "web-01" --force
```

## Systems & Accounts

```bash
# List systems
bt pws systems list
bt pws systems list --workgroup 3
bt pws systems list -o json

# Get system details
bt pws systems get 22

# List accounts on a system
bt pws accounts list --system 22
bt pws accounts get 45
```

## Secrets Safe

```bash
# Safes
bt pws secrets safes list
bt pws secrets safes create --name "MyApp" --description "App credentials"
bt pws secrets safes delete <safe_id>

# Folders
bt pws secrets folders list
bt pws secrets folders create --name "Database" --parent <safe_id>
bt pws secrets folders delete <folder_id>

# Secrets
bt pws secrets secrets list
bt pws secrets secrets get <secret_id>
bt pws secrets secrets create --folder <folder_id> --title "db-admin" \
    --username "admin" --password "secret123"

# Search secrets
bt pws quick find-secret database
bt pws quick get-secret "MySafe/Folder/SecretName"
PASSWORD=$(bt pws quick get-secret "MySafe/Secret" --raw)
```

### Storing SSH Private Keys

Use **TEXT type** for SSH keys - simpler retrieval for automation:

```bash
# Store SSH key as TEXT (recommended for automation)
bt pws secrets secrets create-text --folder <folder_id> --title "svc-deploy SSH Key" \
    --file /path/to/id_rsa --description "Deployment service account key"

# Retrieve SSH key (one API call)
bt pws secrets secrets get <secret_id> --show-password

# Alternative: FILE type (preserves filename metadata)
bt pws secrets secrets create-file --folder <folder_id> --title "svc-deploy Key" \
    --file /path/to/id_rsa

# Download FILE type secret
bt pws secrets secrets download <secret_id> -o /tmp/key
```

**Note:** TEXT type stores content in Password field (retrieved with `-p`). FILE type requires separate download command.

## Users & Groups

```bash
bt pws users list
bt pws users list -s "admin"           # Search
bt pws users get 4
bt pws users groups
bt pws users group 1 --members
bt pws users roles

# User entitlements report
bt pws quick user-entitlements dave
```

## Credential Checkout Flow (Manual)

```bash
# 1. Find system
bt pws systems list -o json | jq '.[] | select(.SystemName=="axion-finapp-01")'

# 2. Find account
bt pws accounts list --system 22

# 3. Checkout
bt pws credentials checkout --system "axion-finapp-01" --account "root"

# 4. Get password
bt pws credentials show <request_id>

# 5. Checkin
bt pws credentials checkin <request_id>
```

## CSV Import/Export

```bash
# Export template
bt pws export systems --file systems-template.csv
bt pws export secrets --file secrets-template.csv

# Dry run validation
bt pws import systems --file systems.csv --dry-run

# Import
bt pws import systems --file systems.csv
bt pws import secrets --file secrets.csv
```

## Key IDs

| Resource | ID |
|----------|-----|
| Workgroup: Default | 1 |
| Workgroup: Datacenter_West | 2 |
| Workgroup: AWS_Account | 3 |
| Platform: Windows | 1 |
| Platform: Linux | 2 |
| Platform: MySQL | 10 |
| Platform: PostgreSQL | 79 |
| Functional Account | 7 |

## EC2 Systems in AWS

When onboarding EC2 instances to Password Safe, use the **internal AWS DNS name** (not public IP) for reliable connectivity:

```bash
# Use internal DNS for EC2 systems
bt pws quick onboard -n "web-prod-01" \
    -i "ip-10-0-12-45.us-east-1.compute.internal" \
    -w 3 -f 7

# Or set DNS separately
bt pws systems update <system_id> --dns "ip-10-0-12-45.us-east-1.compute.internal"
```

**Why internal DNS?**
- Public IPs change on instance restart
- Internal DNS resolves correctly from VPC-connected jumpoints
- Enables ECM integration (PWS system name must match PRA jump item)

## API Notes

- Pagination: `limit`/`offset` (not page/perPage)
- Response format: `{"TotalCount": N, "Data": [...]}`
- Asset creation requires workgroup: `POST /Workgroups/{id}/Assets`
