CLI Reference

The primary interface is the TUI. The CLI subcommands below are alternatives for scripting and automation.

General

purple                              # launch the TUI
purple myserver                     # connect if exact match, otherwise open TUI with search
purple -c myserver                  # direct connect (skip the TUI)
purple --config ~/other/ssh_config  # use alternate config file
purple --list                       # list all configured hosts
purple update                       # self-update to latest version
purple --verbose                    # enable debug-level logging
purple --completions zsh            # generate shell completions (bash, zsh, fish)
purple --demo                       # launch with built-in demo data
purple --theme "Catppuccin Mocha"   # launch with a specific theme (session only)

Host management

purple add deploy@10.0.1.5:22          # quick-add (user@host:port)
purple add user@host --alias name       # quick-add with custom alias
purple add user@host --key ~/.ssh/id_ed25519  # quick-add with key
purple import hosts.txt                 # bulk import from file
purple import --known-hosts             # import from ~/.ssh/known_hosts

Provider management

purple provider add digitalocean --token YOUR_TOKEN
purple provider add aws --profile default --regions us-east-1,eu-west-1
purple provider add aws --token AKID:SECRET --regions us-east-1,eu-west-1
purple provider add proxmox --url https://pve:8006 --token user@pam!token=secret
purple provider add gcp --token /path/to/sa-key.json --project my-project --regions us-central1-a
purple provider add azure --token /path/to/sp.json --regions SUBSCRIPTION_ID
purple provider add tailscale                               # local CLI, no token
purple provider add tailscale --token tskey-api-YOUR_KEY    # API
purple provider add oracle --token ~/.oci/config --compartment OCID --regions eu-amsterdam-1
purple provider add ovh --token APP_KEY:APP_SECRET:CONSUMER_KEY --project PROJECT_ID
purple provider add leaseweb --token YOUR_API_KEY
purple provider add i3d --token YOUR_API_KEY
purple provider add transip --token /path/to/private-key.pem
purple provider add transip --token BEARER_TOKEN
purple provider add digitalocean --token TOKEN --no-auto-sync
purple provider list
purple provider remove digitalocean

Syncing

purple sync                     # sync all providers
purple sync digitalocean        # sync single provider
purple sync --dry-run           # preview changes
purple sync --remove            # remove hosts deleted from provider

Tunnels

purple tunnel list                              # list all tunnels
purple tunnel list myserver                     # list tunnels for a host
purple tunnel add myserver L:8080:localhost:80  # add forward
purple tunnel remove myserver L:8080:localhost:80
purple tunnel start myserver                    # start tunnel (Ctrl+C to stop)

Snippets

purple snippet list                                # list all snippets
purple snippet add NAME "COMMAND"                  # add a snippet
purple snippet add NAME "COMMAND" --description "desc"
purple snippet add check-path "df -h {{path:/tmp}}"  # parameterized
purple snippet remove NAME
purple snippet run NAME myserver                   # run on single host
purple snippet run NAME --tag prod                 # run on hosts with tag
purple snippet run NAME --all                      # run on all hosts
purple snippet run NAME --all --parallel           # run concurrently

Themes

purple theme list                  # list available themes (built-in + custom)
purple theme set <name>            # set the active theme

The --theme flag overrides the theme for a single session without saving:

purple --theme "Catppuccin Mocha"  # session-only override

11 built-in themes are included. Custom themes can be added as TOML files in ~/.purple/themes/.

Password management

purple password set myserver        # store password in OS keychain
purple password remove myserver     # remove from keychain

Vault SSH

purple vault sign my-host                                         # sign a single host via the HashiCorp Vault SSH secrets engine
purple vault sign --all                                           # sign every host with a Vault SSH role configured
purple vault sign my-host --vault-addr https://vault.example.com  # override the Vault server address for this run
purple vault sign --all --vault-addr http://127.0.0.1:8200        # same flag works with --all

Flags:

• --vault-addr <URL>: override the Vault server address for this signing run. Precedence: flag > per-host # purple:vault-addr comment > per-provider vault_addr= in ~/.purple/providers > inherited shell VAULT_ADDR env var. Lets you sign without exporting VAULT_ADDR in your shell

See Vault SSH Certificates for setup and policy.

MCP server

purple mcp                              # start MCP server for AI agents (stdio JSON-RPC)
purple --config ~/other/ssh_config mcp  # with custom config

See MCP Server for client setup and available tools.

Logging

purple logs                         # print log file path (~/.purple/purple.log)
purple logs --tail                  # follow log output in real time
purple logs --clear                 # delete the log file

Pass --verbose to any command to enable debug-level logging. Or set PURPLE_LOG (trace, debug, info, warn, error, off) for finer control. See Troubleshooting for details on log format and fault domains.