Synopsis
perch mail search [OPTIONS]Description
Search a mailbox with IMAP SEARCH and print metadata for matching messages. Results are newest first by default; –reverse flips the order.
Bare query words search the message text. Supported keys: from, to, cc, bcc, subject, body, text, header:Name=Value, since, before, on, sent-since, sent-before, sent-on, seen, unseen, answered, unanswered, flagged, unflagged, deleted, undeleted, draft, undraft, larger, smaller, uid, flag/keyword, and unflag/unkeyword.
Aliases: find.
Notes
- The default limit is 50; –limit 0 means unlimited.
- The mailbox is examined read-only, so search does not change flags.
Options
| Option | Description |
|---|---|
--username, -u <value> | account username (env PERCH_IMAP_USER) |
--password <value> | account password (prefer PERCH_IMAP_PASSWORD or –password-file) |
--password-file <value> | read the account password from a file |
--password-stdin | read the account password from stdin |
--timeout <value> | connection timeout (default: 30s) |
--config <value> | configuration file (default: ~/.config/perch/perch.yaml) |
--mailbox, -m <value> | mailbox to search (default: “INBOX”) |
--query, -q <value> | search expression (see the examples in –help) |
--uids <value> | explicit UID set, for example 1,3:5,10:* |
--limit, -n <value> | maximum results (0 means unlimited) (default: 50) |
--reverse | oldest first instead of newest first |
--json | write one JSON object per message |
--server, -s <value> | IMAP server (imaps://host, imap://host, or host[:port]); defaults from –config |
--plaintext | connect to IMAP without TLS (use only on trusted networks) |
--starttls | require STARTTLS for IMAP |
--insecure | skip IMAP TLS certificate verification |
--ca-file <value> | PEM CA bundle used to verify the IMAP server certificate |
--help, -h | show help |
Examples
perch mail search -q 'from:alice since:2026-01-01'
perch mail search -q 'unseen larger:1M' --json
perch mail search --uids 12,14 --limit 0Environment
| Variable | Purpose |
|---|---|
PERCH_IMAP_USER | default account username |
PERCH_IMAP_PASSWORD | account password |