Authentication

First Launch

On the very first launch, you will be presented with a Login screen containing three fields:

Field	What to Enter
Server URL	The full URL of your server, including the protocol. Example: https://music.example.com
Username	Your Subsonic username
Password	Your (hashed/plaintext)password or API key

Use Tab / Shift+Tab (or Up / Down) to move between fields, and press Enter on the password field to connect.

Note: The URL must include the protocol (http:// or https://). SubTUI will show an error if it is missing.

Authentication Methods

SubTUI supports multiple authentication strategies to interface securely with your Subsonic server. You can define how SubTUI authenticates in your credentials.toml file.

1. Plaintext: Your password is saved normally (in plain text) within the config file. (Note: For your security, SubTUI still generates a secure hash and salt from this password before it leaves your device, so it is never sent raw over the network).
2. Hashed: Your password is stored locally as a pre-computed hash and salt. This prevents your raw password from being readable by anyone looking at the credentials.toml file, adding an extra layer of local device security.
3. API Key / App Password: If your server supports generating unique app passwords, you can provide that key.

Credentials File

Once you log in, your credentials are saved to ~/.config/subtui/credentials.toml. You can also edit this file directly instead of using the login screen.

[server]
url = 'https://music.domain.tld'
# Options: 'plaintext', 'hashed', 'api_key'
auth_method = 'plaintext'
username = ''
# Required if auth_method = 'plaintext'
password = ''
# Required if auth_method = 'hashed'
password_token = ''
# Required if auth_method = 'hashed'
password_salt = ''
# Required if auth_method = 'api_key'
api_key = ''


[security]
redact_credentials_in_logs = true

Security Settings

Security Note: Your credentials are stored in plaintext on disk when choosing the plaintext authentication method to allow automated logins. The file is strictly created with 0600 permissions (owner read/write only) to protect it from other users on your system. We highly recommend using an API Key or enabling Token Auth rather than using your primary plaintext password.

The redact_credentials_in_logs option is enabled by default and should be left set to true. It prevents your server URL, username, and password from appearing in SubTUI's debug log. If you are developing or need to inspect raw API calls, you can temporarily set it to false, but remember to re-enable it afterwards.