msgvault
CLI Reference
Global Flags
| Flag | Description |
|---|---|
--config | Path to config file (default: ~/.msgvault/config.toml) |
--help | Show help |
init-db
Initialize the SQLite database.
msgvault init-dbadd-account
Add a Gmail account and authorize via OAuth.
msgvault add-account <email>msgvault add-account <email> --headless| Flag | Description |
|---|---|
--headless | Use device authorization flow (no browser) |
sync-full
Download all messages from a Gmail account. When called without an email argument, syncs all configured accounts.
msgvault sync-full [email] [flags]| Flag | Description |
|---|---|
--limit N | Maximum messages to download |
--after YYYY-MM-DD | Only messages after this date |
--before YYYY-MM-DD | Only messages before this date |
--noresume | Ignore checkpoints, start fresh |
--verbose | Detailed progress output |
sync
Sync new and changed messages using Gmail History API. When called without an email argument, syncs all accounts that have completed an initial full sync.
msgvault sync [email]search
Search the archive with Gmail-like query syntax.
msgvault search <query> [flags]| Flag | Description |
|---|---|
--json | Output results as JSON |
See Searching for the full operator reference.
tui
Launch the interactive terminal interface.
msgvault tui [flags]| Flag | Description |
|---|---|
--account <email> | Filter to a specific account |
export-eml
Export a message as a .eml file.
msgvault export-eml [flags]| Flag | Description |
|---|---|
--message-id N | Internal database message ID |
--gmail-id <hex> | Gmail message ID |
--output <path> | Output file (default: stdout) |
verify
Verify local archive integrity against Gmail.
msgvault verify <email> [flags]| Flag | Description |
|---|---|
--sample-size N | Messages to sample (default: 100) |
stats
Show archive statistics.
msgvault statslist-senders
List top senders by message count.
msgvault list-senders [flags]| Flag | Description |
|---|---|
--limit N | Number of results (default: 10) |
list-domains
List top sender domains by message count.
msgvault list-domains [flags]| Flag | Description |
|---|---|
--limit N | Number of results (default: 10) |
list-labels
List all labels with message counts.
msgvault list-labelsbuild-cache
Build or update the Parquet analytics cache.
msgvault build-cache [flags]| Flag | Description |
|---|---|
--full-rebuild | Discard existing cache and rebuild |
mcp
Start the Model Context Protocol server for AI assistant integration.
msgvault mcp [flags]| Flag | Default | Description |
|---|---|---|
--force-sql | false | Always use SQL retrieval instead of FTS5 |
See MCP Server for configuration and tool reference.
cancel-deletion
Cancel pending or in-progress deletion batches. When called without a batch ID, lists available batches.
msgvault cancel-deletion [batch-id]msgvault cancel-deletion --all| Flag | Description |
|---|---|
--all | Cancel all pending and in-progress batches |
repair-encoding
Fix UTF-8 encoding issues in existing messages.
msgvault repair-encoding