Skip to content
msgvault
GitHub stars

Multi-Account

OAuth Apps and Tokens

For personal Gmail accounts, a single client_secret.json supports all of them. Each add-account call authorizes one account and stores a separate token file.

Google Workspace organizations often restrict OAuth to apps created within their own org. If a Workspace account fails to authorize with your default app, create a separate OAuth app inside that org and add it as a named app in config.toml. See the OAuth Setup Guide for the full walkthrough.

Diagram showing default and named OAuth apps creating separate token files for each account

Adding Accounts

Terminal window
# Gmail accounts (OAuth)
msgvault add-account personal@gmail.com
msgvault add-account you@acme.com --oauth-app acme   # Workspace org


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

Syncing

Sync all accounts at once by omitting the email argument:

Terminal window
# Full sync all accounts
msgvault sync-full


# Incremental sync all accounts
msgvault sync

Or sync a specific account:

Terminal window
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.

Search queries run across all accounts by default:

Terminal window
msgvault search "quarterly report"

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

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

TUI Filtering

Filter the TUI to a specific account:

Terminal window
msgvault tui --account work@company.com

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