LARCH(1)

📦 version 1.1.2, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

💌 larch(1) — the manual, but make it slay 💌

okay bestie, sit down, grab a strawberry 🍓, because we're about to talk about larch, a general commands manual page that is genuinely one of the most useful little tools ever and I need you to be obsessed with it the way I am.

✨ NAME ✨

larch — copy messages from one IMAP server to another. that's it. that's the whole vibe. your mail, teleported. 🦋

🌸 SYNOPSIS 🌸

larch [options]

larch [--from URI] [--to URI]

two whole ways to run it. pick your fighter. 💅

👑 DESCRIPTION 👑

so <rainbow>Larch</rainbow> is a tool that copies messages from one IMAP server to another — quickly and safely, no cap. it's smart enough not to copy messages that already exist on the destination (it's giving ✨emotional intelligence✨) and robust enough to deal with interruptions caused by flaky connections or misbehaving servers. like, servers throwing tantrums and Larch is just standing there unbothered. 🫶

and Larch is particularly well-suited for copying email to, from, or between Gmail accounts. highkey its moment. 💖

🎀 OPTIONS 🎀

💜 Server options

  • --from, -f URI — the URI of the source IMAP server. where the mail is coming FROM bestie.
  • --from-folder, -F FOLDER — the source folder to copy from. default is INBOX.
  • --from-pass, -p PASSWD — source server password. default is to prompt the user (so it doesn't just live in your shell history like a menace).
  • --from-user, -u USER — source server username. default is to prompt the user.
  • --to, -t URI — the URI of the destination IMAP server. where the mail is going TO.
  • --to-folder, -T FOLDER — the destination folder to copy to. default is INBOX.
  • --to-pass, -P PASSWD — destination server password. default is to prompt the user.
  • --to-user, -U USER — destination server username. default is to prompt the user.

🌈 Copy options

  • --all, -a — copy all folders recursively. go big or go home. 🔥
  • --all-subscribed, -s — copy all subscribed folders recursively. only the ones you actually signed up for.
  • --delete, -d — delete messages from the source after copying them, or if they already exist at the destination. it's giving "moving out, not just visiting" 💀
  • --exclude PATTERN [ PATTERN... ] — a list of mailbox names/patterns that shouldn't be copied. not invited to the party. 🚫
  • --exclude-file FILE — a filename containing mailbox names/patterns that shouldn't be copied. same energy, but the list lives in a file.
  • --expunge, -x — expunge deleted messages from the source. bye bye forever 👋
  • --sync-flags, -S — sync message flags from the source to the destination for messages that already exist at the destination. so your read/unread and stars stay iconic. ⭐

🧚 General options

  • --config, -c FILE — specify a non-default config file to use. default is ~/.larch/config.yaml.
  • --database FILE — specify a non-default message database to use. default is ~/.larch/larch.db.
  • --dry-run, -n — don't actually make any changes. a little dress rehearsal, no commitment. 🩰
  • --max-retries NUM — maximum number of times to retry after a recoverable error. default is 3.
  • --no-create-folder — don't create destination folders that don't already exist. if it's not there, it's not there, periodt.
  • --ssl-certs FILE — path to a trusted certificate bundle to use to verify server SSL certificates.
  • --ssl-verify — verify server SSL certificates. safety first bestie 🛡️
  • --verbosity, -V STR — output verbosity: debug, info, warn, error, or fatal. default is info.
  • --version, -v — print version and exit.
  • --help, -h — show a help message.

🍓 CONFIGURATION 🍓

so like — yes, you can control Larch entirely from the command line, but ngl that gets inconvenient if you need to specify a lot of options, or if you run Larch frequently and can't always remember which options to use. and honestly? relatable. using a configuration file can simplify things. 💅

by default, Larch looks for a config file at ~/.larch/config.yaml and uses it if found. you may specify a custom config file using the --config command line option.

the Larch configuration file is a simple YAML ⟨http://yaml.org/⟩ file that may contain multiple sections, each with a different set of options, as well as a special default section. the options in the default section will be used unless they're overridden either in another config section or on the command line. so default is like the group chat, and the other sections are the DMs that get to override. 📱

here's a sample Larch config file, verbatim, because I would never mess with your config:

# Copy all subscribed folders by default
default:
  all-subscribed: true

# Copy mail from Gmail to my server, excluding stuff I don't want.
gmail to my server:
  from: imaps://imap.gmail.com
  from-user: example
  from-pass: secret

  to: imaps://mail.example.com
  to-user: example
  to-pass: secret

  exclude:
    - "[Gmail]/Sent Mail"
    - "[Gmail]/Spam"
    - "[Gmail]/Trash"

# Copy mail from my INBOX to Gmail's INBOX
my inbox to gmail inbox:
  all-subscribed: false

  from: imaps://mail.example.com
  from-folder: INBOX
  from-user: example
  from-pass: secret

  to: imaps://imap.gmail.com
  to-folder: INBOX
  to-user: example
  to-pass: secret

this file contains three sections. the options from default will be used in all other sections as well unless they're overridden. okay so it's less "group chat" and more "group project where everyone inherits the same base rules". 🫠

to specify which config section you want Larch to use, just pass its name on the command line — use quotes if the name contains spaces:

larch 'gmail to my server'

and if you specify additional command line options, they'll override options in the config file:

larch 'gmail to my server' --from-user anotheruser

running Larch with no command line arguments will cause the default section to be used. with the example above, this will result in an error since the default section doesn't contain the required from and to options — but if you only need to use Larch with a single configuration, you could use the default section for everything and save yourself some typing on the command line. efficiency queen 👑

💖 FILES 💖

  • ~/.larch/config.yaml

🌸 EXAMPLE 🌸

okay bestie, so here's the tea: Larch lives on the command line, that's her whole thing 💅. All the examples below run Larch using only command line arguments — but lowkey you can also drop these options into a config file and run Larch with no arguments at all if that's more your vibe. Your call, you're the main character here ✨

🦋 the bare minimum

At minimum?? You gotta tell her where to pull from and where to push to — that's a source server and a destination server, in the form of IMAP URIs:

larch --from imap://mail.example.com \
      --to imap://imap.gmail.com

Larch will prompt you for the usernames and passwords she needs, then sync the contents of the source's INBOX folder to the destination's INBOX folder. no cap, that's it 🫶

🔒 securing the bag with SSL

Wanna connect using SSL? Just specify a URI that starts with imaps:// and you're golden:

larch --from imaps://mail.example.com \
      --to imaps://imap.gmail.com

📁 syncing a specific folder (not INBOX)

If you'd like to sync a specific folder other than INBOX, tell her which one with --from-folder and --to-folder. Folder names containing spaces must be enclosed in quotes, bestie, don't skip that part:

larch --from imaps://mail.example.com \
      --to imaps://imap.gmail.com \
      --from-folder 'Sent Mail' --to-folder 'Sent Mail'

🌈 syncing literally everything

To sync all folders, use the --all option — or --all-subscribed if you only want to sync the subscribed ones:

larch --from imaps://mail.example.com \
      --to imaps://imap.gmail.com --all

🙈 don't make new folders

By default Larch will create folders on the destination server if they don't already exist. To prevent this, add the --no-create-folder option:

larch --from imaps://mail.example.com \
      --to imaps://imap.gmail.com --all \
      --no-create-folder

🚫 excluding folders

You can prevent Larch from syncing one or more folders by using the --exclude option, which accepts multiple arguments. yes, multiple. she's flexible like that 💖

larch --from imaps://mail.example.com \
      --to imaps://imap.gmail.com --all \
      --exclude Spam Trash Drafts "[Gmail]/*"

📝 when your exclusion list gets out of hand

If your exclusion list is long or complex, create a text file with one exclusion pattern per line and tell Larch to load it with the --exclude-file option:

larch --from imaps://mail.example.com \
      --to imaps://imap.gmail.com --all \
      --exclude-file exclude.txt

⭐ wildcards & regex, because of course

The wildcard characters * and ? are supported in exclusion lists. You may also use a regular expression by enclosing a pattern in forward slashes — so the previous example could be achieved with the pattern:

/(Spam|Trash|Drafts|\[Gmail]\/.*)/

slay, honestly 🔥

👑 AUTHORS 👑

Adapted from the program's documentation for Debian by Martín Ferrari <tincho@tincho.org> 💜

and that's a wrap, bestie 🎀 this whole page is LARCH(1) — Larch's very own manual, section 1, stamped with whatever date it's carrying, straight from the Larch docs themselves. go forth and sync responsibly, you absolute icon ✨🦋💅

📦 where this page comes from