CLI Reference

Global Flags

Flag	Description
`--config`	Path to config file (default: `~/.msgvault/config.toml`)
`--home`	Home directory for all data (overrides `MSGVAULT_HOME`)
`-v`, `--verbose`	Verbose output
`--local`	Force local database mode when `[remote]` is configured
`--help`	Show help

init-db

Initialize the SQLite database.

msgvault init-db

add-account

Add a Gmail account and authorize via OAuth.

msgvault add-account <email>
msgvault add-account <email> --headless

Flag	Description
`--headless`	Show instructions for headless server setup
`--display-name`	Set a display name for the account

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
`--query`	Gmail search query filter
`--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]

import-mbox

Import a local MBOX archive into msgvault.

msgvault import-mbox <identifier> <export-file>

The export file may be a plain .mbox/.mbx file or a .zip containing one or more MBOX files.

Flag	Default	Description
`--source-type`	`mbox`	Source type recorded in database (e.g., `hey` for HEY.com)
`--label`	—	Label to apply to all imported messages
`--no-resume`	`false`	Start fresh, ignoring interrupted progress
`--checkpoint-interval`	`200`	Save progress every N messages
`--no-attachments`	`false`	Skip writing attachments to disk

See Importing Local Email for usage examples.

import-emlx

Import Apple Mail .emlx files into msgvault.

msgvault import-emlx <identifier> <mail-dir>

The mail directory should be an Apple Mail mailbox tree containing .mbox or .imapmbox directories, each with a Messages/ subdirectory of .emlx files. You can also point directly at a single .mbox directory. Labels are derived from directory names.

Flag	Default	Description
`--source-type`	`apple-mail`	Source type recorded in database
`--no-resume`	`false`	Start fresh, ignoring interrupted progress
`--checkpoint-interval`	`200`	Save progress every N messages
`--no-attachments`	`false`	Skip writing attachments to disk

See Importing Local Email for usage examples.

search

Search the archive with Gmail-like query syntax.

msgvault search <query> [flags]

Flag	Description
`-n`, `--limit N`	Maximum number of results (default: 50)
`--offset N`	Skip first N results
`--json`	Output results as JSON

See Searching for the full operator reference.

tui

Launch the interactive terminal interface.

msgvault tui [flags]

Flag	Description
`--force-sql`	Force SQLite queries instead of Parquet
`--no-cache-build`	Skip automatic cache build/update

export-eml

Export a message as a .eml file. Accepts either a numeric database ID or a Gmail message ID.

msgvault export-eml <id> [flags]

Flag	Description
`-o`, `--output <path>`	Output file (default: `<gmail_id>.eml`, use `-` for stdout)

export-attachment

Export an attachment by its SHA-256 content hash.

msgvault export-attachment <content-hash> [flags]

Flag	Description
`-o`, `--output <path>`	Output file path (use `-` for stdout)
`--base64`	Output raw base64 to stdout
`--json`	Output as JSON with base64-encoded data

The --json, --base64, and --output flags are mutually exclusive.

See Exporting Data for usage examples.

export-attachments

Export all attachments from a message as individual files.

msgvault export-attachments <message-id> [flags]

Flag	Description
`-o`, `--output <dir>`	Output directory (default: current directory)

Accepts internal numeric IDs or Gmail message IDs. See Exporting Data for usage examples.

export-token

Export a browser-created OAuth refresh token to a remote msgvault instance.

Use this for headless deployments (NAS, cloud VM, any remote server) that cannot run a browser flow.

msgvault export-token <email> [flags]

Flag	Description
`--to <url>`	Remote msgvault URL (or `MSGVAULT_REMOTE_URL`)
`--api-key <key>`	API key (or `MSGVAULT_REMOTE_API_KEY`)
`--allow-insecure`	Allow HTTP for trusted networks (for example Tailscale)

export-token uploads ~/.msgvault/tokens/<email>.json to /api/v1/auth/token/<email>, saves it in the remote token store, and posts account metadata to /api/v1/accounts.

verify

Verify local archive integrity against Gmail.

msgvault verify <email> [flags]

Flag	Description
`--sample N`	Messages to sample (default: 100)

stats

Show archive statistics.

msgvault stats

list-senders

List top senders by message count.

msgvault list-senders [flags]

Flag	Description
`-n`, `--limit N`	Number of results (default: 50)
`--after YYYY-MM-DD`	Only messages after this date
`--before YYYY-MM-DD`	Only messages before this date
`--json`	Output as JSON

list-domains

List top sender domains by message count.

msgvault list-domains [flags]

Flag	Description
`-n`, `--limit N`	Number of results (default: 50)
`--after YYYY-MM-DD`	Only messages after this date
`--before YYYY-MM-DD`	Only messages before this date
`--json`	Output as JSON

list-labels

List all labels with message counts.

msgvault list-labels [flags]

Flag	Description
`-n`, `--limit N`	Number of results (default: 50)
`--after YYYY-MM-DD`	Only messages after this date
`--before YYYY-MM-DD`	Only messages before this date
`--json`	Output as JSON

build-cache

Build or update the Parquet analytics cache.

msgvault build-cache [flags]

Flag	Description
`--full-rebuild`	Discard existing cache and rebuild

cache-stats

Show statistics about the analytics cache.

msgvault cache-stats

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.

serve

Start the web server with optional background sync scheduling.

msgvault serve

The serve command has no CLI flags. All configuration (port, bind address, API key, CORS, account schedules) is read from your config.toml. See Web Server for endpoint documentation and Configuration for config options.

setup

Run the first-run setup wizard for OAuth and optional remote deployment.

msgvault setup

If configured for a remote server, this command generates <MSGVAULT_HOME>/nas-bundle with:

config.toml ready for container deployment
client_secret.json
docker-compose.yml

The wizard also stores remote URL/API key in remote config block so export-token can use it without extra flags.

show-message

Show full message details.

msgvault show-message <id> [flags]

Flag	Description
`--json`	Output as JSON

list-accounts

List synced email accounts.

msgvault list-accounts [flags]

Flag	Description
`--json`	Output as JSON

update-account

Update account settings.

msgvault update-account <email> [flags]

Flag	Description
`--display-name`	Set a display name for the account

list-deletions

List pending and recent deletion batches.

msgvault list-deletions

show-deletion

Show details of a deletion batch.

msgvault show-deletion <batch-id>

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

delete-staged

Execute staged deletions. This permanently deletes messages from Gmail.

msgvault delete-staged [batch-id] [flags]

Flag	Description
`-y`, `--yes`	Skip confirmation prompt
`--trash`	Move to trash instead of permanent delete
`--dry-run`	Show what would be deleted without deleting
`-l`, `--list`	List staged deletion batches
`--account`	Filter to a specific account

repair-encoding

Fix UTF-8 encoding issues in existing messages.

msgvault repair-encoding

update

Update msgvault to the latest version.

msgvault update [flags]

Flag	Description
`--check`	Check for updates without installing
`-y`, `--yes`	Skip confirmation prompt
`-f`, `--force`	Force update even if already on the latest version

version

Print version, commit, build date, and platform information.

msgvault version

quickstart

Print a quickstart guide for AI agents.

msgvault quickstart