Setup Guide

Install Release

curl -fsSL https://msgvault.io/install.sh | bash

The installer detects your OS and architecture, downloads the latest release from GitHub Releases, verifies the SHA-256 checksum, and installs the binary.

Verify the installation:

msgvault --help

Build From Source

Requires Go 1.25+ and a C/C++ compiler (GCC or Clang). CGO is required because msgvault uses mattn/go-sqlite3 (SQLite with FTS5) and go-duckdb (Parquet analytics), both of which compile native extensions.

git clone https://github.com/wesm/msgvault.git
cd msgvault
make install

Installs to ~/.local/bin or $GOPATH/bin. For a debug build use make build, or make build-release for an optimized binary with stripped debug symbols.

Verify the installation:

msgvault --help

Configure OAuth

Create a Google Cloud project, enable the Gmail API, and download your client_secret.json. See the full OAuth Setup Guide.

Create ~/.msgvault/config.toml:

[oauth]
client_secrets = "/path/to/client_secret.json"

Add Your Account

msgvault add-account you@gmail.com

This opens your browser for OAuth consent. For headless servers, use --headless for the device authorization flow.

Sync Email

# Test with a small batch first
msgvault sync-full you@gmail.com --limit 100

# Or sync a specific date range
msgvault sync-full you@gmail.com --after 2024-01-01 --before 2024-02-01

# Sync everything (no limit)
msgvault sync-full you@gmail.com

What to Expect

The initial full sync downloads every message and attachment from Gmail, so it can take a while. In testing we have observed roughly 50 messages per second on fast internet, but the Gmail API has per-user quotas that may throttle throughput further. An account with hundreds of thousands of messages and large attachments may take several hours; an account with millions of messages could take significantly longer. We recommend starting with --limit or a date range to verify everything works before kicking off the full run.

The good news: syncs are resumable (see below), and once the initial sync is complete, incremental syncs only fetch new and changed messages, which is much faster.

Full Sync Flags

Flag	Description
`--limit N`	Download at most N messages
`--after YYYY-MM-DD`	Only messages after this date
`--before YYYY-MM-DD`	Only messages before this date
`--noresume`	Start fresh instead of resuming
`--verbose`	Show detailed progress

Incremental Sync

After the initial full sync, use incremental sync for efficient updates. It uses the Gmail History API to fetch only new and changed messages:

msgvault sync you@gmail.com

# Or sync all accounts at once
msgvault sync

Resumable Checkpoints

If a sync is interrupted (network error, Ctrl+C), run the same command again. It resumes from the last checkpoint:

# This resumes automatically
msgvault sync-full you@gmail.com --after 2024-01-01 --before 2024-02-01

Checkpoint data is stored in the sync_checkpoints table. Use --noresume to discard checkpoints and start over.

Rate Limiting

msgvault uses token bucket rate limiting to respect Gmail API quotas. The default is 5 requests per second, configurable in config.toml:

[sync]
rate_limit_qps = 5

Reduce this value if you encounter rate limit errors during large syncs.

Safety

Sync operations are read-only. They use only messages.list and messages.get Gmail APIs. No write operations are performed. Your Gmail data remains untouched.

Explore

# Search your archive
msgvault search from:alice@example.com

# Launch the interactive TUI
msgvault tui

# View stats
msgvault stats

See Searching and Interactive TUI for more.