CLI Reference (original) (raw)

Global Flags

init-db

Initialize the SQLite database.

add-account

Add a Gmail account and authorize via OAuth.

msgvault add-account <email>

msgvault add-account <email> --headless

msgvault add-account <email> --oauth-app <name>

add-imap

Add an IMAP account for syncing mail from any standard IMAP server.

msgvault add-imap --host <hostname> --username <email>

The command prompts interactively for your password (never accepted as a flag to avoid shell history exposure). For scripting or Docker, set MSGVAULT_IMAP_PASSWORD or pipe via stdin:

MSGVAULT_IMAP_PASSWORD="..." msgvault add-imap --host imap.example.com --username user@example.com

# or

echo "$PASS" | msgvault add-imap --host imap.example.com --username user@example.com

It tests the connection before saving credentials.

Credentials are stored in tokens/imap_<hash>.json with restricted file permissions (0600). Use app-specific passwords when your provider supports them.

After adding an account, sync it with msgvault sync-full. IMAP accounts use the same sync and sync-full commands as Gmail. See Setup Guide for a walkthrough.

add-o365

Add a Microsoft 365 or Outlook.com account via OAuth2 with XOAUTH2 IMAP authentication.

msgvault add-o365 <email>

The command opens your browser for Microsoft OAuth consent, then configures IMAP with XOAUTH2 automatically. The correct IMAP host is auto-detected: outlook.office.com for personal accounts (hotmail.com, outlook.com, live.com, msn.com) and outlook.office365.com for organizational accounts.

Requires a [microsoft] section with client_id in config.toml. See the OAuth Setup guide for Azure AD app registration.

After adding the account, sync it with msgvault sync-full.

sync-full

Download all messages from a Gmail account. When called without an email argument, syncs all configured accounts.

msgvault sync-full [email] [flags]

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.

import-mbox

Import a local MBOX archive into msgvault.

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

The export file may be a plain mbox file (any extension) or a .zip containing one or more .mbox/.mbx files.

See Importing Local Email for usage examples.

import-emlx

Import Apple Mail .emlx files into msgvault. Can auto-discover accounts from macOS Accounts4.sqlite or accept explicit arguments.

# Auto-discover accounts (reads ~/Library/Accounts/Accounts4.sqlite)

msgvault import-emlx

# Specify mail directory

msgvault import-emlx <mail-dir>

# Legacy form: explicit identifier and directory

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.

See Importing Local Email for usage examples.

import-whatsapp

Import messages from a decrypted WhatsApp msgstore.db SQLite database.

msgvault import-whatsapp <msgstore.db> --phone <your-number>

The --phone flag is required and must be in E.164 format (e.g., +447700900000).

See Text Messages for usage examples.

import-imessage

Import messages from the local iMessage database on macOS. Requires Full Disk Access in System Settings.

Reads from ~/Library/Messages/chat.db by default. This is a read-only operation.

See Text Messages for usage examples.

import-gvoice

Import texts, calls, and voicemails from a Google Voice Takeout export.

msgvault import-gvoice <takeout-voice-dir>

The directory must be the “Voice” folder from a Google Takeout export, containing Calls/ and Phones.vcf.

See Text Messages for usage examples.

search

Search the archive with Gmail-like query syntax.

msgvault search <query> [flags]

See Searching for the full operator reference.

tui

Launch the interactive terminal interface.

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]

export-attachment

Export an attachment by its SHA-256 content hash.

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

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]

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]

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]

stats

Show archive statistics.

list-senders

List top senders by message count.

msgvault list-senders [flags]

list-domains

List top sender domains by message count.

msgvault list-domains [flags]

list-labels

List all labels with message counts.

msgvault list-labels [flags]

build-cache

Build or update the Parquet analytics cache.

msgvault build-cache [flags]

cache-stats

Show statistics about the analytics cache.

query

Run arbitrary SQL against the Parquet analytics cache using an in-memory DuckDB engine.

msgvault query <sql> [flags]

If the analytics cache is stale, it is automatically rebuilt before the query runs.

See SQL Queries for available views and example queries.

mcp

Start the Model Context Protocol server for AI assistant integration.

See MCP Server for configuration and tool reference.

serve

Start the web server with optional background sync scheduling.

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.

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]

list-accounts

List synced email accounts.

msgvault list-accounts [flags]

update-account

Update account settings.

msgvault update-account <email> [flags]

list-deletions

List pending and recent deletion batches.

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

delete-staged

Execute staged deletions. This permanently deletes messages from Gmail.

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

repair-encoding

Fix UTF-8 encoding issues in existing messages.

update

Update msgvault to the latest version.

version

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

completion

Generate a shell completion script.

msgvault completion [bash|zsh|fish|powershell]

To load completions:

Bash:

source <(msgvault completion bash)

# Permanent (Linux):

msgvault completion bash > /etc/bash_completion.d/msgvault

# Permanent (macOS with Homebrew):

msgvault completion bash > $(brew --prefix)/etc/bash_completion.d/msgvault

Zsh:

msgvault completion zsh > "${fpath[1]}/_msgvault"

If shell completion is not already enabled, add autoload -U compinit; compinit to your ~/.zshrc first.

Fish:

msgvault completion fish > ~/.config/fish/completions/msgvault.fish

PowerShell:

msgvault completion powershell | Out-String | Invoke-Expression

quickstart

Print a quickstart guide for AI agents.