Troubleshooting

purple writes structured logs to ~/.purple/purple.log. Use these to diagnose connection failures, provider sync problems, password retrieval errors and certificate issues.

Log file

The log file is created automatically on first run. It rotates at 5 MB (old file renamed to purple.log.1).

purple logs              # print the log file path
purple logs --tail       # follow in real time (uses tail -f)
purple logs --clear      # delete the log file

Log levels

By default only warnings and errors are logged. Increase verbosity with:

• --verbose flag: sets level to debug
• PURPLE_LOG environment variable: trace, debug, info, warn, error, off

The env var takes precedence over the flag.

purple --verbose                  # debug level
PURPLE_LOG=trace purple           # maximum detail
PURPLE_LOG=off purple             # disable logging entirely

Fault domains

Warnings and errors carry a prefix that identifies the source of the problem:

Prefix	Meaning	Examples
[external]	Remote host or third-party tool	SSH exit code, SCP failure, Vault unreachable, provider API error
[config]	Local configuration issue	Missing password manager binary, SSH key permissions, unrecognized config line
[purple]	Internal error in purple itself	Atomic write failure, SSH config write failure

Info and debug messages are operational flow markers without prefixes.

Startup banner

Each session writes a banner to the log file with diagnostic context:

--- purple v2.41.1 started at 2026-04-16 08:15:32Z ---
    os=macos arch=aarch64 config=/Users/you/.ssh/config
    ssh=OpenSSH_9.6p1, LibreSSL 3.3.6
    term=xterm-256color colorterm=truecolor
    providers=aws,hetzner,tailscale
    askpass=keychain:,vault:secret/ssh#password
    log_level=warn

This captures everything needed to reproduce an issue without asking the user to run extra commands.

Common issues

Provider sync returns 0 hosts

Look for [config] Provider sync returned 0 hosts in the log. Common causes:

• API token lacks read permissions (check the provider's IAM/token settings)
• Region filter excludes all instances (check --regions in purple provider add)

Password retrieval fails

Look for [config] Password manager binary not found or [external] Password retrieval failed. Common causes:

• The CLI tool (op, bw, pass, vault) is not installed or not on PATH
• Bitwarden vault is locked (run bw unlock first)

SSH key permission error

Look for [config] SSH key permission issue. Fix with:

chmod 600 ~/.ssh/id_*
chmod 644 ~/.ssh/id_*.pub

Vault SSH certificate signing fails

Look for [external] Vault entries. Common patterns:

• Vault unreachable: server is down, address is wrong or TLS mismatch
• Vault auth failed: token expired or policy missing. Run vault login
• Vault SSH signing failed: role misconfigured or public key not accepted

See Vault SSH Certificates for setup and policy configuration.