Configuration

Configuration

The tools accept command-line arguments, existing OS environment variables, an optional .env file, and built-in defaults in this precedence order:

1. Command-line arguments
2. Existing OS environment variables
3. .env values
4. Script defaults

Create a local configuration from the committed template:

cp .env.example .env

.env is ignored by Git. Never commit credentials or include them in screenshots and logs.

Accounts

SRC_IMAP_HOST="imap.gmail.com"
SRC_IMAP_USERNAME="source@gmail.com"
SRC_IMAP_PASSWORD="source-app-password"

DEST_IMAP_HOST="imap.example.com"
DEST_IMAP_USERNAME="destination@example.com"
DEST_IMAP_PASSWORD="destination-password"

Configure either a password or OAuth2 for each account, not both:

SRC_IMAP_PASSWORD=""
SRC_OAUTH2_CLIENT_ID="application-client-id"
SRC_OAUTH2_CLIENT_SECRET="google-client-secret-if-required"
SRC_ACCOUNT_TYPE="auto"

A host is an account boundary. When overriding a host, also provide its username and authentication method from the same or a higher-precedence source so credentials cannot silently be sent to a different endpoint.

See OAuth2 for provider registration and authentication details.

Local paths

BACKUP_LOCAL_PATH="./my_backup"
SRC_LOCAL_PATH=""
DEST_LOCAL_PATH=""

BACKUP_LOCAL_PATH is the backup destination, restore source, and default local count target. Compare can use separate source and destination local paths.

Safety and performance

MAX_WORKERS=4
BATCH_SIZE=10
DELETE_FROM_SOURCE="false"
DEST_DELETE="false"
PRESERVE_FLAGS="false"
PRESERVE_LABELS="false"

Boolean options have positive and negative command forms, such as --src-delete / --no-src-delete and --dest-delete / --no-dest-delete. Explicit negative flags are useful when inherited configuration enables a destructive option.

For the full canonical template and field comments, see .env.example.