Got Your Back (GYB): Backing Up Gmail from the Command Line

If you want to save a local copy of your Gmail account and restore it later, use Got Your Back (GYB), a command-line tool for backing up and restoring Gmail. It works with personal Gmail and Google Workspace accounts. You use a command-line tool by typing commands in a terminal instead of clicking through menus. You grant GYB access to Gmail through Google, and GYB saves messages in a backup folder on your computer. GYB’s official documentation describes its setup, backup, and restore options.

Choose GYB when you want a Gmail backup that you can restore to Gmail. If you want to keep email as files you can read and search on your computer, choose mailmd is a free, open source alternative. It copies email into Markdown files, one file per message. Choose based on what you want to do with the local copy: restore messages to Gmail, or browse and search messages as files.

How GYB backs up Gmail #

GYB connects to Gmail and saves the backup in a folder named GYB-GMail-Backup followed by the account’s email address. Use --local-folder to choose a different folder. GYB’s estimate action counts messages in All Mail, Gmail’s folder that includes archived messages. By default, the estimate leaves out Spam and Trash. Add --spam-trash to include those folders in backup, estimate, or count actions. The GYB documentation says that restoring a backup to its original Gmail account restores backed-up messages that were later deleted, without making duplicates.

GYB asks Google for permission to access Gmail. On first use, run the estimate command:

gyb --email you@example.com --action estimate

GYB opens a web page where you grant access. The authorization applies to Gmail data, not the account’s other Google data. For a personal Gmail account, the first setup may also require an OAuth consent screen, where you enter an application name and email addresses before creating credentials in Google’s APIs & Services dashboard.

After you grant access, start a backup with:

gyb --email you@example.com --action backup

Use Gmail search syntax to narrow the backup. For example, this command backs up messages marked important or starred:

gyb --email you@example.com --action backup --search "is:important OR is:starred"

The --search option leaves out Spam and Trash, even when you search with in:anywhere. Add --spam-trash to include those folders. Compare the estimated count with Gmail before relying on it. The estimate leaves out Spam and Trash unless you request them.

Install GYB and verify the download #

On Windows, GYB’s official documentation offers an MSI installer and a ZIP archive containing the executable. It also provides a source archive. The documentation advises most users to avoid the Python source version. For the ZIP route, it suggests extracting the files directly to C:\, placing the executable at C:\gyb\gyb.exe.

On macOS and Linux, GYB’s setup requires Python 3. The official wiki lists an installation command for each platform. Follow its current instructions instead of copying a command from an old tutorial. The same wiki covers first-run setup and authorization.

GYB needs access to your email, so download it from the project’s official channels and verify the file before running it. The project’s build verification instructions show how to use the GitHub CLI command gh attestation verify to check whether the project built a binary or package. A successful check prints ✓ Verification succeeded!.

Restore messages carefully #

To restore a backup to the same Gmail account, use GYB’s restore action. GYB checks which backed-up messages have since been deleted and restores those messages without duplicating messages that remain in the account. To restore into a different Gmail account, specify the original backup folder; the --label-restored option adds a label to restored messages.

GYB also supports restoring MBOX files. MBOX is a mailbox file format used by Google Takeout and other tools. Google Workspace administrators can use the restore-group action to import messages into a Google Group. This action has limits: it does not preserve labels, read/unread status, or stars, and the Groups Migration API rejects messages larger than 16 MB.

GYB’s deletion actions work differently from backup and restore, so use them with care. The purge action permanently deletes Gmail messages. Running it without a search filter empties the mailbox, including Spam and Trash, and GYB’s documentation warns that the mailbox itself cannot restore those messages. Make a backup before using purge, and do not use it unless you intend to delete the matching mail. The purge-labels action removes user labels but does not delete messages.

When mailmd is the better fit #

GYB backs up and restores Gmail. mailmd saves email as files on your computer. It works with IMAP mailboxes, which use a standard protocol for accessing email on a mail server. mailmd connects to Gmail through the Gmail API and to Outlook.com and Microsoft mailboxes through Microsoft Graph. These connections use an OAuth app, a registration that lets mailmd request access to your account. You create the registration in Google Cloud or Microsoft Entra. For IMAP providers that require an app password, mailmd tells you to use one.

mailmd saves each message as a Markdown file, a plain-text document format, and puts the message headers in a metadata block at the top called frontmatter. mailmd converts HTML email into readable Markdown, saves attachments beside the message, and organizes folders and years as directories. It also creates an index.jsonl file that scripts can filter with jq. You can search the files with tools such as rg or grep, open them in an editor, and include the archive in a normal backup or Git repository. With --keep-raw, mailmd also saves the original .eml file.

mailmd requests read access and opens mail folders in read-only mode. It does not mark messages as read or move them. It also does not delete messages or send mail. Each time mailmd syncs, it adds new messages and updates read and starred marks. If you stop a sync with Ctrl-C, mailmd continues from the saved data the next time you run it. mailmd never deletes archive files, including when a message has been deleted from the server; it marks that message as deleted on the server. Spam and trash are excluded unless you ask for them, and Gmail syncs All Mail so archived messages are included.

Choose mailmd to keep a readable, searchable file archive from one or more mailbox providers. Choose GYB to back up and restore Gmail. mailmd is not a mail client, does not import files back into a mailbox, does not convert mail to PST or PDF, and does not free mailbox storage by itself. Deleting messages from the mailbox remains a separate action. Its logins are stored outside the archive, readable only by your user, and mailmd runs without telemetry or a mailmd server.

To try mailmd, visit mailmd.dev or use its GitHub repository for installation instructions. You can also start a coding agent in the mail folder and ask it to examine the files. The agent sends the contents it reads to the company that provides its AI model.