Skip to main content

Secrets

v0.13

Caeros 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 Caeros 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:

    csh secret ui

The secrets UI provides a visual interface to view, add, edit, delete, and import secrets from 1Password.

Managing Secrets via CLI​

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

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

# Get a specific secret value
csh secret get MY_SECRET_NAME

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

# Delete a secret
csh 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:

csh secret set SERVER_PASSWORD=my_actual_password

Now when Caeros 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

Importing from 1Password​

v0.14

Caeros Terminal can import secrets directly from your 1Password vaults using the 1Password CLI (op).

Prerequisites​

  1. Install the 1Password CLI: Download from developer.1password.com/docs/cli
  2. Sign in: Run op signin in your terminal to authenticate

Import via UI​

  1. Open the Secrets settings panel
  2. Click Import from 1Password
  3. Browse and search your 1Password items (Logins, Passwords, API Credentials, Secure Notes)
  4. Select an item and choose a secret name
  5. Click Import Secret

The password field from the selected 1Password item will be stored as a Caeros secret.

Troubleshooting 1Password Import​

  • "1Password CLI (op) is not installed": Install the op CLI from the link above
  • "1Password CLI is not signed in": Run op signin in a terminal before importing

Security Considerations​

  • Encrypted Storage: Secrets are stored encrypted in your Caeros 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 Caeros Terminal.

Storage Backend​

Caeros 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, Caeros 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:

csh 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.