auberge bichon reconcile-folders

Synopsis

auberge bichon reconcile-folders [--host <HOST>] [--account <EMAIL>] [OPTIONS]

Description

Reconciles Bichon account sync_folders from the live IMAP folder list.

Policy:

• Include all folders by default.
• Exclude folders with SPECIAL-USE \Junk and \Trash.
• Fallback for legacy IMAP servers without SPECIAL-USE: exclude common leaf names (spam, junk, junk mail, junk email, trash, deleted items, deleted messages, bin). The fallback is case-insensitive and matches on the leaf segment (Archive/Spam matches; Spamtastic does not).
• Apply per-account additive overrides from config.toml:

[bichon.account_overrides."me@example.com"]
extra_excluded_folders = ["Newsletters", "Receipts/2019"]

Tip

extra_excluded_folders matches the full mailbox path, case-sensitively. Use the exact name returned by Bichon’s list-mailboxes API (e.g. "Receipts/2019", not "receipts/2019"). Unlike the SPECIAL-USE / leaf-name fallback, this is intentionally precise so operators can target individual sub-folders without false positives.

Default is dry-run (read-only).

Tip

On Bichon >= 2.0 the remote folder list is served from a cache. On a cold cache Bichon lists the mailboxes in the background and the command polls until the list is ready (up to 120s) before computing the diff, so the first run after a Bichon restart can take noticeably longer.

Options

Option	Description	Default
-H, –host HOST	Target host running Bichon (prompted on a TTY)	prompted
–apply	Commit sync_folders updates in Bichon	false
–account EMAIL	Reconcile only one account email (prompted on a TTY, [all accounts] offered first)	All
-o, –output FORMAT	Output format (human, json)	human

Omit -H on a terminal and the host picker is drawn, as rescan already did. It cannot hang in a script: with no terminal a lone configured host is implied, and a roster holding several fails naming the flag rather than waiting for an answer nobody can give. Omit --account off a terminal and every account is reconciled; a filter nobody can be asked for means all.

An --account Bichon does not report is an error naming the accounts it does. It used to be matched by plain equality, so a typo filtered every account away and the run reported 0 folders added across 0 accounts as a success.

Bichon API base URL

The base URL for the Bichon API is resolved in this order (first match wins):

1. Per-host override in config.toml:

   [bichon.hosts.auberge]
   base_url = "https://bichon.auberge.example.com"
   
   [bichon.hosts.staging]
   base_url = "https://bichon.staging.example.com"

   Recommended when you operate more than one Bichon instance: each --host <name> resolves to its own URL.

2. Global override bichon_base_url:

   bichon_base_url = "https://bichon.example.com"

3. Derived from domain (default):

   domain = "example.com"
   bichon_subdomain = "bichon"   # optional, defaults to "bichon"

   Yields https://bichon.example.com.

If neither a per-host override, a global bichon_base_url, nor domain is set, the command fails with an explicit error naming the host.

A host whose Bichon reports no accounts at all fails the same way: Bichon reports no accounts on '<host>'. rescan and verify-coverage refuse in the same words, because all three reach the Bichon API through one place. Reconciling against an empty roster used to print an empty plan and exit 0, which reads as “nothing to do” when the truth is “nothing to do it to”.

Required config keys

Key	Purpose
bichon_api_token	Bearer token for the Bichon API. Required.
bichon.hosts.<name>.base_url	Per-host base URL override. Optional.
bichon_base_url	Global base URL override. Optional.
bichon_subdomain	Subdomain when deriving from domain. Optional.
domain	Domain used for default URL derivation.
bichon.account_overrides.<email>.extra_excluded_folders	Per-account exclusions (full path, case-sensitive).

Examples

# Pick the host and the account interactively
auberge bichon reconcile-folders

# Dry-run all accounts
auberge bichon reconcile-folders --host auberge

# Apply changes
auberge bichon reconcile-folders --host auberge --apply

# Single account only
auberge bichon reconcile-folders --host auberge --account me@example.com --apply

# Structured output
auberge bichon reconcile-folders --host auberge --output json