# How to Manage Multiple Google Accounts with gogcli: A Complete Guide > Efficiently manage multiple Google accounts with gogcli. Securely store OAuth tokens and switch accounts easily using the CLI. Get the complete guide today. - Repository: [Peter Steinberger/gogcli](https://github.com/steipete/gogcli) - Tags: how-to-guide - Published: 2026-02-16 --- **Use `gog auth add` to store OAuth tokens for each Google account in your OS keyring, then switch between them using the `--account` flag or set a default via `gog auth manage`.** Working with several Google identities from the terminal requires secure credential storage and seamless account switching. The `steipete/gogcli` tool implements a complete multi-account architecture that lets you authorize, alias, and select different Google accounts on a per-command basis. This guide explains how to manage multiple Google accounts with gogcli using its built-in authentication system, web-based account manager, and command-line aliases. ## How gogcli Stores Multiple Account Tokens `gogcli` persists a **refresh token** for every Google account you authorize. These tokens live in your operating system's keyring, accessed through the abstraction layer in [`internal/secrets/store.go`](https://github.com/steipete/gogcli/blob/main/internal/secrets/store.go). ### OS Keyring Storage Layout Each account is stored under a key formatted as `token::` (or `token:` for the legacy default client). The keyring also maintains default account pointers: - `default_account` – the global default when no client is specified - `default_account:` – a client-scoped default These entries are managed by `KeyringStore.SetDefaultAccount` and `KeyringStore.GetDefaultAccount` in [`internal/secrets/store.go`](https://github.com/steipete/gogcli/blob/main/internal/secrets/store.go). ## Adding New Google Accounts to gogcli To authorize an additional Google account, use the `gog auth add` command. This initiates an OAuth flow and stores the resulting refresh token in your keyring. In [`internal/cmd/auth.go`](https://github.com/steipete/gogcli/blob/main/internal/cmd/auth.go), the `AuthAddCmd.Run` function (lines 476-511) calls `googleauth.Authorize`, which completes the OAuth handshake and then persists the token via `store.SetToken`. ```bash # Authorize a second Google account gog auth add --account second@example.com ``` The browser will open to complete OAuth authorization, and the token will be securely stored under `token::second@example.com`. ## Setting a Default Account with the Web UI When you have multiple accounts, you can designate one as the default using an embedded web interface. Running `gog auth manage` starts a local server that lists every stored account and lets you set or remove the default. The server implementation lives in [`internal/googleauth/accounts_server.go`](https://github.com/steipete/gogcli/blob/main/internal/googleauth/accounts_server.go) (lines 194-224). It reads all tokens via `store.ListTokens()`, retrieves the current default through `GetDefaultAccount`, and renders [`templates/accounts.html`](https://github.com/steipete/gogcli/blob/main/templates/accounts.html) (embedded in [`templates_embed.go`](https://github.com/steipete/gogcli/blob/main/templates_embed.go)). Submitting the form POSTs to `/set-default`, which triggers `store.SetDefaultAccount`. ```bash # Open the account manager in your browser gog auth manage ``` The UI displays a table of accounts with options to set one as default or delete stored tokens. ## Creating Short Aliases for Frequently Used Accounts Typing full email addresses repeatedly is cumbersome. `gogcli` supports account aliasing through the `gog auth alias` command, which maps short names to email addresses stored in a JSON configuration file. Alias data is managed by [`internal/config/aliases.go`](https://github.com/steipete/gogcli/blob/main/internal/config/aliases.go) and exposed via the CLI in [`internal/cmd/auth_alias.go`](https://github.com/steipete/gogcli/blob/main/internal/cmd/auth_alias.go). The `config.SetAccountAlias` function writes to the config file, while `config.ResolveAccountAlias` translates aliases back to emails during command execution. ```bash # Create an alias for your work account gog auth alias set work admin@company.com # List all configured aliases gog auth alias list ``` ## Selecting Accounts in CLI Commands Any subcommand that interacts with Google services accepts an `--account` flag. If omitted, `gogcli` falls back to the default account or the sole stored token. The resolution logic resides in `resolveClientForEmail` within [`internal/cmd/auth.go`](https://github.com/steipete/gogcli/blob/main/internal/cmd/auth.go) (lines 270-285). This helper first attempts to expand the provided value via `config.ResolveAccountAlias`. If no account is specified, it retrieves the default from `store.GetDefaultAccount`. ```bash # Use the aliased work account for calendar operations gog calendar list --account work # Use the full email address directly gog drive list --account personal@gmail.com ``` ## Summary - **Store tokens securely** using `gog auth add` to save OAuth refresh tokens in your OS keyring under keys like `token::`. - **Manage defaults visually** by running `gog auth manage`, which starts a web server defined in [`internal/googleauth/accounts_server.go`](https://github.com/steipete/gogcli/blob/main/internal/googleauth/accounts_server.go) to set or remove the default account. - **Create shortcuts** with `gog auth alias set ` to avoid typing full email addresses, storing mappings in [`internal/config/aliases.go`](https://github.com/steipete/gogcli/blob/main/internal/config/aliases.go). - **Switch per-command** by passing `--account ` to any subcommand; the resolver in [`internal/cmd/auth.go`](https://github.com/steipete/gogcli/blob/main/internal/cmd/auth.go) handles alias expansion and fallback to the default token. ## Frequently Asked Questions ### How many Google accounts can I add to gogcli? You can add as many accounts as your operating system's keyring can store. Each account creates a distinct entry under `token::` (or `token:` for legacy clients), and the storage backend in [`internal/secrets/store.go`](https://github.com/steipete/gogcli/blob/main/internal/secrets/store.go) handles retrieval for any number of tokens. ### Where are the OAuth tokens actually stored? Tokens are stored in your OS keyring (macOS Keychain, Windows Credential Manager, or Linux secret service) via the abstraction layer in [`internal/secrets/store.go`](https://github.com/steipete/gogcli/blob/main/internal/secrets/store.go). Each token is keyed by `token::`, and default account preferences are stored under `default_account` or `default_account:`. ### Can I use aliases instead of full email addresses? Yes. Use `gog auth alias set ` to create a shortcut. These aliases are stored in a JSON configuration file managed by [`internal/config/aliases.go`](https://github.com/steipete/gogcli/blob/main/internal/config/aliases.go). When you pass `--account ` to any command, the resolver in [`internal/cmd/auth.go`](https://github.com/steipete/gogcli/blob/main/internal/cmd/auth.go) automatically expands it to the full email address before retrieving the token. ### What happens if I don't specify the --account flag? If you omit `--account`, `gogcli` first checks for a default account stored in the keyring via `GetDefaultAccount` in [`internal/secrets/store.go`](https://github.com/steipete/gogcli/blob/main/internal/secrets/store.go). If only one token exists in the keyring, that account is used implicitly. If multiple tokens exist and no default is set, the command will fail or prompt you to specify an account.