Multi-Account

One Secret, Many Tokens

A single client_secret.json supports all your Gmail accounts. You do not need to create separate OAuth credentials or edit your config between accounts. Each add-account call authorizes one account and stores a separate token file.

See the OAuth Setup Guide for the full setup walkthrough.

Adding Accounts

# Gmail accounts (OAuth)
msgvault add-account personal@gmail.com
msgvault add-account work@company.com

# IMAP accounts (password)
msgvault add-imap --host imap.fastmail.com --username you@fastmail.com

Gmail accounts open a browser for OAuth authorization. IMAP accounts prompt for a password and test the connection. All accounts share the same SQLite database and attachment storage.

Tip

Each account must be listed as a Test user in your Google Cloud OAuth consent screen. This is the most common reason a second account fails to authorize.

Syncing

Sync all accounts at once by omitting the email argument:

# Full sync all accounts
msgvault sync-full

# Incremental sync all accounts
msgvault sync

Or sync a specific account:

msgvault sync-full personal@gmail.com
msgvault sync work@company.com

If a token expires during sync, msgvault prints the re-authorization URL with the account name so you can select the correct Google account. It will not auto-launch a browser during re-auth to prevent accidentally authorizing the wrong account.

Cross-Account Search

Search queries run across all accounts by default:

msgvault search "quarterly report"

Use --account to limit results to a specific account:

msgvault search "quarterly report" --account work@company.com

TUI Filtering

Filter the TUI to a specific account:

msgvault tui --account work@company.com

Or press a in the TUI to cycle through account filters interactively.