GMAIL-ARCHIVER(1)

NAME
gmail-archiver - gmail-archiver v0.0.0

Locally archive Gmail emails.

COMMANDS

  gmail-archiver

Archive Gmail emails and move them to the trash.

    gmail-archiver [OPTIONS] EMAIL [OUT_DIR]

Options

--no-delete
    Do not move emails to trash.

-a, --auth-only
    Only authorise the user.

-d, --debug
    Enable debug level logging.

--debug-imap
    Enable debug level logging for IMAP.

-r, --force-refresh
    Force refresh the token.

    Arguments

EMAIL
    Required argument

OUT_DIR
    Optional argument

CONFIGURATION

Create a file at ${CONFIG_DIR}/gmail-archiver/config.toml. On Linux this is typically ~/.config/gmail-archiver/config.toml. The application will print the configuration file path on every run.

The file must contain the following:

    [tool.gmail-archiver]
    client_id = 'client-id.apps.googleusercontent.com'
    client_secret = 'client-secret'

You must set up a project on Google Cloud and it must have the Gmail API enabled.

Then in APIs and services, choose Credentials, + Create credentials and OAuth client ID.

•   Application type: Web application

•   Name: any name

    Copy and paste the client ID and secret into the above file.

    You should protect the above file. Set it to as limited of a permission set as possible. Example: chmod 0400 ~/.config/gmail-archiver/config.toml.

    Why not use Keyring? Keyring is inappropriate for automated scenarios, unless it is purposely made insecure.

AUTHORISATION

When run, if anything is invalid about the OAuth data, you will be prompted to create it.

    $ gmail-archiver email@gmail.com
    Using authorisation database: /home/user/.cache/gmail-archiver/oauth.json
    Using authorisation file: /home/user/.config/gmail-archiver/config.toml
    https://accounts.google.com/o/oauth2/v2/auth?client_id=....
    Visit displayed URL to authorize this application. Waiting...

In your browser, click Continue and then in the browser you will see the text: Authorisation redirect completed. You may close this window. At that point the archiving will begin.

    Visit displayed URL to authorize this application. Waiting...
    127.0.0.1 - - [17/May/2025 00:50:21] "GET /?code=...&scope=https://mail.google.com/ HTTP/1.1" 200 -
    INFO: Logging in.
    INFO: Deleting emails: False
    INFO: Archiving 200 messages.

Due to the method of authorisation for OAuth, if you need to run this on a server, you must run this tool on a machine with one (and the ability to run a localhost server) to get the first access token. Once this is done, transfer configuration and the OAuth authorisation data to the server. From that point, the access token will be refreshed when necessary. You must do this for every email you plan to archive.

The OAuth authorisation file is also printed at startup. Example on Linux: ~/.config/cache/gmail-archiver/oauth.json. It will be stored with mode 0600.

AUTHOR
Andrew Udvare <audvare@gmail.com>

COPYRIGHT
2025