Skip to main content

Secrets

v0.13

Wave Terminal provides a secure way to store sensitive information like passwords, API keys, and tokens. Secrets are stored encrypted in your system's native keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service), ensuring your sensitive data remains protected.

Why Use Secrets?​

Secrets in Wave Terminal allow you to:

  • Store SSH passwords - Automatically authenticate to SSH connections without typing passwords
  • Manage API keys - Keep API tokens, keys, and credentials secure
  • Share across sessions - Access your secrets from any terminal block or remote connection
  • Avoid plaintext storage - Never store sensitive data in configuration files or scripts

Opening the Secrets UI​

There are several ways to access the secrets management interface:

  1. From the widgets bar (recommended):

    • Click the settings icon on the widgets bar
    • Select Secrets from the menu

  2. From the command line:

    wsh secret ui

The secrets UI provides a visual interface to view, add, edit, and delete secrets.

Managing Secrets via CLI​

Wave Terminal provides a complete CLI for managing secrets from any terminal block:

# List all secret names (not values)
wsh secret list

# Get a specific secret value
wsh secret get MY_SECRET_NAME

# Set a secret (format: name=value, no spaces around =)
wsh secret set GITHUB_TOKEN=ghp_xxxxxxxxxx
wsh secret set DB_PASSWORD=super_secure_password

# Delete a secret
wsh secret delete MY_SECRET_NAME

Secret Naming Rules​

Secret names must match the pattern: ^[A-Za-z][A-Za-z0-9_]*$

This means:

  • Must start with a letter (A-Z or a-z)
  • Can only contain letters, numbers, and underscores
  • Cannot contain spaces or special characters

Valid names: MY_SECRET, ApiKey, ssh_password_1 Invalid names: 123_SECRET, my-secret, secret name

Using Secrets with SSH Connections​

v0.13

Secrets can be used to automatically provide passwords for SSH connections, eliminating the need to type passwords repeatedly.

Configure in connections.json​

Add the ssh:passwordsecretname field to your connection configuration:

{
    "myserver": {
        "ssh:hostname": "example.com",
        "ssh:user": "myuser",
        "ssh:passwordsecretname": "SERVER_PASSWORD"
    }
}

Then store your password as a secret:

wsh secret set SERVER_PASSWORD=my_actual_password

Now when Wave connects to myserver, it will automatically use the password from your secret store instead of prompting you.

Benefits​

  • Security: Password stored encrypted in your system keychain
  • Convenience: No need to type passwords for each connection
  • Flexibility: Update passwords by changing the secret, not the configuration

Security Considerations​

  • Encrypted Storage: Secrets are stored encrypted in your Wave configuration directory. The encryption key itself is protected by your operating system's secure credential storage (macOS Keychain, Windows Credential Manager, or Linux Secret Service).

  • No Plaintext: Secrets are never stored unencrypted in logs or accessible files.

  • Access Control: Secrets are only accessible to Wave Terminal.

Storage Backend​

Wave Terminal automatically detects and uses the appropriate secret storage backend for your operating system:

  • macOS: Uses the macOS Keychain
  • Windows: Uses Windows Credential Manager
  • Linux: Uses the Secret Service API (freedesktop.org specification)
Linux Secret Storage

On Linux systems, Wave requires a compatible secret service backend (typically GNOME Keyring or KWallet). These are usually pre-installed with your desktop environment. If no compatible backend is detected, you won't be able to set secrets, and the UI will display a warning.

Troubleshooting​

"No appropriate secret manager found"​

This error occurs on Linux when no compatible secret service backend is available. Install GNOME Keyring or KWallet and ensure the secret service is running.

Secret not found​

Ensure the secret name is spelled correctly (names are case-sensitive) and that the secret exists:

wsh secret list

Permission denied on Linux​

The secret service may require you to unlock your keyring. This typically happens after login. Consult your desktop environment's documentation for keyring management.