How to Manage Multiple Google Accounts with gogcli: A Complete Guide

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.

OS Keyring Storage Layout

Each account is stored under a key formatted as token:<client>:<email> (or token:<email> for the legacy default client). The keyring also maintains default account pointers:

• default_account – the global default when no client is specified
• default_account:<client> – a client-scoped default

These entries are managed by KeyringStore.SetDefaultAccount and KeyringStore.GetDefaultAccount in 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, the AuthAddCmd.Run function (lines 476-511) calls googleauth.Authorize, which completes the OAuth handshake and then persists the token via store.SetToken.

# Authorize a second Google account

gog auth add --account [email protected]

The browser will open to complete OAuth authorization, and the token will be securely stored under token:<client>:[email protected].

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 (lines 194-224). It reads all tokens via store.ListTokens(), retrieves the current default through GetDefaultAccount, and renders templates/accounts.html (embedded in templates_embed.go). Submitting the form POSTs to /set-default, which triggers store.SetDefaultAccount.

# 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 and exposed via the CLI in 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.

# Create an alias for your work account

gog auth alias set work [email protected]

# 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 (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.

# Use the aliased work account for calendar operations

gog calendar list --account work

# Use the full email address directly

gog drive list --account [email protected]

Summary

• Store tokens securely using gog auth add to save OAuth refresh tokens in your OS keyring under keys like token:<client>:<email>.
• Manage defaults visually by running gog auth manage, which starts a web server defined in internal/googleauth/accounts_server.go to set or remove the default account.
• Create shortcuts with gog auth alias set <alias> <email> to avoid typing full email addresses, storing mappings in internal/config/aliases.go.
• Switch per-command by passing --account <email|alias> to any subcommand; the resolver in 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:<client>:<email> (or token:<email> for legacy clients), and the storage backend in 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. Each token is keyed by token:<client>:<email>, and default account preferences are stored under default_account or default_account:<client>.

Can I use aliases instead of full email addresses?

Yes. Use gog auth alias set <alias> <email> to create a shortcut. These aliases are stored in a JSON configuration file managed by internal/config/aliases.go. When you pass --account <alias> to any command, the resolver in 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. 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.

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