gogcli Keyring Backend Options: How to Configure Secure Token Storage

The gogcli keyring backend options are auto (default), keychain, and file, which control how OAuth tokens are stored and accessed across macOS, Linux, and containerized environments.

The steipete/gogcli tool manages GOG.com authentication through system keyrings, and selecting the appropriate backend ensures secure token storage whether you are running on macOS, headless Linux servers, or Docker containers. Understanding the available gogcli keyring backend options allows you to configure the tool for your specific security and deployment requirements.

Available gogcli Keyring Backend Options

The implementation in internal/secrets/store.go defines three mutually exclusive backends. Each backend determines which underlying keyring implementation accesses your stored OAuth credentials.

auto (Default)

The auto backend selects the most appropriate keyring implementation based on the operating system. On macOS, it uses the native Keychain; on Linux or WSL, it attempts to use the Secret Service API (DBus) if available, otherwise falling back to a file-based keyring. This is the default behavior when no backend is explicitly configured.

keychain

The keychain backend forces the use of the macOS Keychain implementation (keyring.KeychainBackend). This option is useful on macOS when you want to guarantee that the native system keychain is used regardless of other environment factors, ensuring credentials are stored in the user's macOS Keychain where they can be managed alongside other system passwords.

file

The file backend forces a file-based implementation (keyring.FileBackend) that stores encrypted credentials on disk. The directory is created under the user's configuration location at ~/.config/gogcli/keyring. This backend is essential for headless Linux environments, Docker containers, or CI/CD pipelines where no system keyring (like GNOME Keyring or macOS Keychain) is available.

How to Configure the Keyring Backend

You can select a backend through three different mechanisms, checked in the following order: CLI command, environment variable, and configuration file.

CLI Command Method

The gog auth keyring command displays or sets the active backend. The implementation in internal/cmd/auth_keyring.go handles this interaction.

To view the current backend:

gog auth keyring

To set a specific backend:

gog auth keyring file

If no argument is supplied, the command outputs the current configuration (e.g., keyring backend: auto).

Environment Variable Method

Set the GOG_KEYRING_BACKEND environment variable to override the configuration file setting. This is defined in internal/secrets/store.go and is useful for temporary overrides or container deployments.

export GOG_KEYRING_BACKEND=file
gog auth login

Valid values are auto, keychain, or file. Invalid values produce the error: invalid keyring backend: "<value>" (expected auto, keychain, or file).

Configuration File Method

The backend selection is persisted in the configuration file (managed via internal/cmd/root.go) under the keyring_backend field. When you use the CLI command to set the backend, it updates this configuration file, ensuring the setting persists across sessions.

Programmatic Access to Keyring Backends (Go)

For developers extending gogcli, the internal/secrets package provides functions to resolve and open keyrings programmatically.

import (
    "github.com/steipete/gogcli/internal/secrets"
)

func example() error {
    // Resolve backend based on env/config (auto/keychain/file)
    info, err := secrets.ResolveKeyringBackend()
    if err != nil {
        return err
    }
    
    // Open the keyring with the resolved backend
    ring, err := secrets.OpenKeyring(info)
    if err != nil {
        return err
    }
    
    // Use ring for token operations...
    return nil
}

The ResolveKeyringBackend() function checks the environment variable and configuration to determine which backend to instantiate, while OpenKeyring() initializes the actual keyring client.

Troubleshooting Invalid Backend Errors

If you encounter the error invalid keyring backend: "<value>", verify that you are using one of the three supported values exactly as specified:

• auto (lowercase)
• keychain (lowercase)
• file (lowercase)

When using the file backend in non-interactive environments (such as CI/CD pipelines), you must also provide a decryption password via the GOG_KEYRING_PASSWORD environment variable, as the file-based backend requires password-based encryption that cannot prompt interactively in headless environments.

Summary

• gogcli supports three keyring backends: auto (default), keychain, and file.
• The auto backend selects the best available system keyring (macOS Keychain or Linux Secret Service).
• The keychain backend forces macOS Keychain usage, while file uses an encrypted local store at ~/.config/gogcli/keyring.
• Configure the backend via the gog auth keyring command, the GOG_KEYRING_BACKEND environment variable, or the keyring_backend field in config.json.
• When using the file backend non-interactively, set GOG_KEYRING_PASSWORD to provide the decryption key.

Frequently Asked Questions

What is the default gogcli keyring backend?

The default backend is auto, which automatically selects the most appropriate keyring implementation for your operating system. On macOS, it uses the native Keychain; on Linux, it attempts to use the Secret Service API (DBus) if available, otherwise falling back to a file-based keyring.

How do I use gogcli in a Docker container without a system keyring?

Set the backend to file using the environment variable GOG_KEYRING_BACKEND=file and provide a password via GOG_KEYRING_PASSWORD. This forces gogcli to use an encrypted file-based store at ~/.config/gogcli/keyring instead of attempting to connect to a system keyring that does not exist in the container environment.

Can I switch between keyring backends without re-authenticating?

No, switching backends typically requires re-authentication because each backend stores credentials separately. The OAuth tokens stored in the macOS Keychain are not automatically migrated to the file-based backend or vice versa. After changing the backend via gog auth keyring or the environment variable, you will need to run gog auth login again to store fresh credentials in the new backend.

Where does the file backend store credentials on Linux?

The file backend stores encrypted credentials in the ~/.config/gogcli/keyring directory. This location follows the XDG Base Directory specification for user-specific configuration files, ensuring consistency with other Linux applications and allowing easy backup or removal of stored authentication data.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}