[BUG] Unhelpful error when system keyring entry is deleted — "secret not found in keyring"

[elijah-apprabbit]

Describe the bug

After deleting my local system keyring (due to unrelated issues with GNOME Keyring), every doppler command fails with:

Token not found in system keyring
Doppler Error: secret not found in keyring

This happens because ~/.doppler/.doppler.yaml still contains a token: reference (e.g., token: secret-<keyring-secret-reference-id>)
pointing to a keyring entry that no longer exists. The CLI attempts to look it up, fails, and gives an error that doesn't explain the cause or
how to fix it.

This error blocks all CLI operations — including doppler login, doppler configure, and even passing a token inline with --token or
DOPPLER_TOKEN=. There is no way to recover without manually discovering and editing the YAML config file.

To Reproduce

1. Authenticate normally with doppler login (token is stored in system keyring, reference saved in ~/.doppler/.doppler.yaml)
2. Delete or reset the system keyring (e.g., remove GNOME Keyring data, switch desktop environments, or reinstall keyring service)
3. Run any doppler command:

$ doppler --debug secrets --project my-project --config prd

Debug output:

Debug: Using config dir /home/user/.doppler
Debug: Using config file /home/user/.doppler/.doppler.yaml
Debug: Reading config file
Debug: Retrieving token from system keyring
Token not found in system keyring                                                                                                                
Doppler Error: secret not found in keyring

Even explicitly providing a token fails:

$ DOPPLER_TOKEN="dp.st.prd.xxx" doppler secrets
Token not found in system keyring
Doppler Error: secret not found in keyring                                                                                                       
 
$ doppler secrets --token "dp.st.prd.xxx"                                                                                                        
Token not found in system keyring
Doppler Error: secret not found in keyring

4. The only fix is to manually delete the stale token reference from ~/.doppler/.doppler.yaml or remove the file entirely, then re-run doppler login.

Expected behavior

When the CLI detects that a keyring entry is missing, it should:

1. Provide a clear, actionable error message, e.g.:

   Error: Saved auth token not found in system keyring (it may have been deleted).                                                               
   Run `doppler login` to re-authenticate, or remove ~/.doppler/.doppler.yaml to reset.
   

2. Not block --token or DOPPLER_TOKEN usage. If a token is explicitly provided via flag or environment variable, the CLI should use it
   directly rather than unconditionally attempting to read the stale keyring reference first.

3. Ideally, offer to clear the stale reference automatically, e.g.:

   Saved auth token not found in system keyring. Clear stale config and re-login? [Y/n]                                                          
   

Desktop

• OS: Debian GNU/Linux 13 (trixie), kernel 6.12.74+deb13+1-amd64
• Desktop: GNOME (GNOME Keyring)

CLI Version

doppler v3.75.3

Additional context

The root cause is that ~/.doppler/.doppler.yaml stores an indirect reference to the keyring:

scoped:         
    /:
        token: secret-<keyring-secret-reference-id>
        api-host: https://api.doppler.com
        dashboard-host: https://dashboard.doppler.com

When the corresponding keyring entry is gone, the CLI enters a state where it cannot do anything — not even accept an explicitly-provided token.
This is likely because the keyring lookup is unconditional during config loading, before any command-specific token handling runs.

This may be related to the underlying zalando/go-keyring library. Previous keyring issues have been addressed in #475, #476, and #169.