# gogcli Keyring Backend Options: How to Configure Secure Token Storage

> Explore gogcli keyring backend options: auto, keychain, and file. Learn how to securely store OAuth tokens on macOS, Linux, and in containers.

- Repository: [Peter Steinberger/gogcli](https://github.com/steipete/gogcli)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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`](https://github.com/steipete/gogcli/blob/main/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`](https://github.com/steipete/gogcli/blob/main/internal/cmd/auth_keyring.go) handles this interaction.

To view the current backend:

```bash
gog auth keyring

```

To set a specific backend:

```bash
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`](https://github.com/steipete/gogcli/blob/main/internal/secrets/store.go) and is useful for temporary overrides or container deployments.

```bash
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`](https://github.com/steipete/gogcli/blob/main/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.

```go
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`](https://github.com/steipete/gogcli/blob/main/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.