CLI reference on perch docs

perch init

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

perch init [OPTIONS]

Description

init writes a self-contained perch.yaml and initializes the SQLite database without contacting mxRaven. It is intended for local testing or for deployments where mxRaven is provisioned separately.

If –email is set, init also creates the first account and its default mailbox set. Use –self-signed to generate a local TLS certificate for LAN clients.

Notes

The config is written with mode 0600 and the data directory with mode 0700.
–force overwrites an existing configuration.

Options

Option	Description
`--config <value>`	configuration file (default: ~/.config/perch/perch.yaml)
`--data-dir <value>`	data directory
`--hostname <value>`	server hostname (default: “localhost”)
`--email <value>`	first account email
`--name <value>`	first account display name
`--password <value>`	first account password (prompted when empty)
`--self-signed`	generate a self-signed TLS certificate
`--force`	overwrite an existing configuration
`--help, -h`	show help

Examples

perch init --data-dir ~/.local/share/perch --hostname localhost --email you@example.com

perch init --self-signed --hostname mail.lan --email you@example.com

perch setup

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

perch setup [OPTIONS]

Description

setup calls the mxRaven control plane to provision a workspace domain, MTA listener, optional submission listener, API keys, inbound route, sending-domain policy, and optional S3_STORE rule. It then writes perch.yaml.

The control-plane token is used only during setup and is never written to the config. Listener and S3 secrets are written inline unless you replace them with *_env references.

perch serve

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

perch serve [OPTIONS]

Description

serve runs in the foreground and starts the configured IMAP, IMAPS, submission, and SMTPS listeners plus the mxRaven WebSocket consumer and S3 reconciler.

It logs to stderr, drains connections on SIGTERM/SIGINT for up to five seconds, and reloads certificate files on SIGHUP when tls.cert_file and tls.key_file are set. It does not fork, write a PID file, or support socket activation.

perch account

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

perch account [OPTIONS] COMMAND

Description

Manage local mailbox accounts. Creating an account also creates the default mailbox set: INBOX, Sent, Drafts, Trash, Junk, and Archive.

Notes

Passwords are hashed with Argon2id.
Account changes are written to SQLite and apply without restarting serve.

Options

Option	Description
`--help, -h`	show help

Commands

Command	Description
perch account add	create an account
perch account list	list accounts
perch account passwd	change an account password
perch account disable	disable an account
perch account enable	enable an account

Examples

perch account add --email you@example.com

perch account list

perch account passwd --email you@example.com

perch account add

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

perch account add [OPTIONS]

Description

Create an account, its primary address, and default mailboxes in one transaction. If –password is omitted, perch prompts on a terminal.

Notes

The account is enabled immediately.

Options

Option	Description
`--config <value>`	configuration file (default: ~/.config/perch/perch.yaml)
`--email <value>`	account email
`--name <value>`	display name
`--password <value>`	password (prompted when empty)
`--help, -h`	show help

Examples

perch account add --email you@example.com --name 'Your Name'

perch account list

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

perch account list [OPTIONS]

Description

Print account ID, primary address, display name, disabled state, and creation time.

Options

Option	Description
`--config <value>`	configuration file (default: ~/.config/perch/perch.yaml)
`--help, -h`	show help

Examples

perch account list

perch account passwd

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

perch account passwd [OPTIONS]

Description

Replace the account’s Argon2id password hash. Existing IMAP and submission sessions are not terminated.

Notes

Prompts for the new password when –password is omitted.

Options

Option	Description
`--config <value>`	configuration file (default: ~/.config/perch/perch.yaml)
`--email <value>`	account email
`--password <value>`	new password (prompted when empty)
`--help, -h`	show help

Examples

perch account passwd --email you@example.com

perch account disable

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

perch account disable [OPTIONS]

Description

Disable prevents new IMAP and submission logins without deleting messages. Use enable to reverse it.

Options

Option	Description
`--config <value>`	configuration file (default: ~/.config/perch/perch.yaml)
`--email <value>`	account email
`--help, -h`	show help

Examples

perch account disable --email you@example.com

perch account enable

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

perch account enable [OPTIONS]

Description

Re-enable a previously disabled account.

Options

Option	Description
`--config <value>`	configuration file (default: ~/.config/perch/perch.yaml)
`--email <value>`	account email
`--help, -h`	show help

Examples

perch account enable --email you@example.com

perch alias

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

perch alias [OPTIONS] COMMAND

Description

Aliases map additional addresses to an account. A catch-all is stored as *@domain and accepts any local part for that domain.

Notes

Plus-addressing (user+tag@domain) works without an explicit alias.

Options

Option	Description
`--help, -h`	show help

Commands

Command	Description
perch alias add	add an alias or catch-all
perch alias remove	remove an alias
perch alias list	list aliases for an account

Examples

perch alias add --account you@example.com --address sales@example.com

perch alias add --account you@example.com --catch-all --address example.net

perch alias list --account you@example.com

perch alias add

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

perch alias add [OPTIONS]

Description

Add an exact address alias, or use –catch-all with a domain to route all unmatched addresses at that domain to the account. The address must not already belong to another account.

Options

Option	Description
`--config <value>`	configuration file (default: ~/.config/perch/perch.yaml)
`--account <value>`	account email
`--address <value>`	alias address or domain
`--catch-all`	route all unmatched addresses at –address
`--help, -h`	show help

Examples

perch alias add --account you@example.com --address sales@example.com

perch alias add --account you@example.com --catch-all --address example.net

perch alias remove

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

perch alias remove [OPTIONS]

Description

Remove an alias address or catch-all from the address table. Messages already delivered are unaffected.

Options

Option	Description
`--config <value>`	configuration file (default: ~/.config/perch/perch.yaml)
`--address <value>`	alias address
`--help, -h`	show help

Examples

perch alias remove --address sales@example.com

perch alias list

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

perch alias list [OPTIONS]

Description

List the addresses and catch-all domains assigned to an account.

Options

Option	Description
`--config <value>`	configuration file (default: ~/.config/perch/perch.yaml)
`--account <value>`	account email
`--help, -h`	show help

Examples

perch alias list --account you@example.com

perch mailbox

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

perch mailbox [OPTIONS] COMMAND

Description

Inspect mailbox metadata stored in SQLite. This reads the local database directly and does not require serve to be running.

Notes

The mailbox command is local-only; use perch mail list for a remote IMAP server.

Options

Option	Description
`--help, -h`	show help

Commands

Command	Description
perch mailbox list	list mailboxes for an account

Examples

perch mailbox list --account you@example.com

perch mailbox list

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

perch mailbox list [OPTIONS]

Description

Print each mailbox name, special-use attribute, and subscription state for an account.

Options

Option	Description
`--config <value>`	configuration file (default: ~/.config/perch/perch.yaml)
`--account <value>`	account email
`--help, -h`	show help

Examples

perch mailbox list --account you@example.com

perch mail

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

perch mail [OPTIONS] COMMAND

Description

The mail command group is a scriptable IMAP and SMTP client. list, search, and fetch talk IMAP; send talks SMTP; caps prints the SMTP EHLO extensions of a submission server.

Credentials and TLS flags are shared. IMAP flags are local to list/search/fetch; SMTP flags are local to send/caps.

Notes

If –server or –smtp-server is omitted, the matching listener is taken from –config.
Use –plaintext or –smtp-plaintext only for trusted loopback listeners.
Password sources: –password-file, –password-stdin, PERCH_IMAP_PASSWORD, or an interactive prompt.

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)
`--help, -h`	show help

Commands

Command	Description
perch mail list	list mailboxes
perch mail search	search message metadata
perch mail fetch	fetch raw messages
perch mail send	compose and send a message
perch mail caps	show the SMTP extensions advertised by a submission server

Examples

perch mail list --server imaps://mail.example.com --username you@example.com

perch mail search -q 'unseen from:alice' --json

perch mail fetch -q 'from:alice' --format mbox > alice.mbox

perch mail send --from you@example.com --to alice@example.com \
 --subject Hello --body 'Hi Alice'

Environment

Variable	Purpose
`PERCH_IMAP_USER`	default account username
`PERCH_IMAP_PASSWORD`	account password

perch mail list

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

perch mail list [OPTIONS]

Description

List mailboxes on the selected IMAP server. The default output is a table; –json writes one JSON object per line.

Aliases: ls.

Notes

–subscribed requires server support for LIST-EXTENDED.

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)
`--json`	write one JSON object per mailbox
`--subscribed`	only list subscribed mailboxes
`--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 list --server 127.0.0.1:1143 --plaintext --username you@example.com

perch mail list --server imaps://mail.example.com --username you@example.com --json

Environment

Variable	Purpose
`PERCH_IMAP_USER`	default account username
`PERCH_IMAP_PASSWORD`	account password

perch mail search

Mon, 01 Jan 0001 00:00:00 +0000

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.

perch mail fetch

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

perch mail fetch [OPTIONS]

Description

Fetch complete RFC 5322 messages selected by UID, query, or –all. The default format writes one .eml per message when –dest is a directory, or raw bytes to stdout for a single message.

mbox writes a standard mbox stream. maildir creates tmp/new/cur and preserves message flags.

Aliases: get.

Notes

BODY.PEEK[] is used unless –mark-seen is set.
Writing eml to stdout requires exactly one message.
–dest is a directory for eml/maildir and a file for mbox.
Existing files are not overwritten unless –overwrite is passed.

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 fetch from (default: “INBOX”)
`--query, -q <value>`	search expression
`--uids <value>`	explicit UID set, for example 1,3:5,10:*
`--all`	fetch every message in the mailbox
`--limit, -n <value>`	maximum messages (0 means unlimited) (default: 0)
`--format, -f <value>`	eml, mbox, or maildir (default: “eml”)
`--dest, -d, -o <value>`	destination directory (eml/maildir) or file (mbox); default stdout
`--mark-seen`	let the server set \Seen (default uses BODY.PEEK)
`--overwrite`	overwrite an existing eml/mbox destination
`--reverse`	fetch newest first instead of oldest first
`--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 fetch --uids 42 > message.eml

perch mail fetch -q 'from:alice' --format mbox > alice.mbox

perch mail fetch -q 'unseen' --format maildir --dest ~/Mail

perch mail fetch -q 'unseen' --dest ./messages

Environment

Variable	Purpose
`PERCH_IMAP_USER`	default account username
`PERCH_IMAP_PASSWORD`	account password

perch mail send

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

perch mail send [OPTIONS]

Description

Compose a MIME message and submit it through SMTP. Text and HTML bodies are combined as multipart/alternative; attachments wrap the result in multipart/mixed.

Bodies come from –body/–body-file and –html-body/–html-file, or stdin when it is not a terminal. Attachments are base64 encoded and content types are detected from the file extension or contents.

Notes

Bodies are quoted-printable unless –8bitmime is set; attachments are base64.
SMTPUTF8 is detected from non-ASCII envelope addresses and extra headers; force it with –smtputf8.
Bcc recipients are envelope-only and never appear in headers.
SIZE is sent automatically and checked against the server’s advertised limit.

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)
`--from <value>`	sender address (default: –username)
`--to <value>...`	recipient address or list; repeatable
`--cc <value>...`	Cc recipient address or list; repeatable
`--bcc <value>...`	Bcc recipient address or list; repeatable
`--reply-to <value>...`	Reply-To address or list; repeatable
`--subject, -s <value>`	message subject
`--body <value>`	plain-text body
`--body-file <value>`	read the plain-text body from a file (use - for stdin)
`--html-body <value>`	HTML body
`--html-file <value>`	read the HTML body from a file (use - for stdin)
`--attach, -a <value>...`	attach a file; repeatable
`--header, -H <value>...`	add an extra header (Name: Value); repeatable
`--in-reply-to <value>`	Message-ID being replied to
`--references <value>`	space-separated Message-IDs for References
`--8bitmime`	send UTF-8 text with BODY=8BITMIME
`--smtputf8`	force SMTPUTF8 (usually detected automatically)
`--dry-run, -n`	write the composed message to stdout without sending
`--verbose, -v`	print SMTP capabilities and delivery details to stderr
`--smtp-server, -S <value>`	SMTP submission server (smtps://host, smtp://host, or host[:port]); defaults from –config
`--smtp-plaintext`	connect to SMTP without TLS (use only on trusted networks)
`--smtp-starttls`	require STARTTLS for SMTP
`--smtp-implicit-tls`	use implicit TLS for SMTP (usually port 465)
`--smtp-insecure`	skip SMTP TLS certificate verification
`--smtp-ca-file <value>`	PEM CA bundle used to verify the SMTP server certificate
`--help, -h`	show help

Examples

perch mail send --from you@example.com --to alice@example.com \
 --subject Hello --body 'Hi Alice'

echo 'Body from stdin' | perch mail send --from you@example.com \
 --to alice@example.com --subject Hello

perch mail send --from you@example.com --to alice@example.com \
 --subject Report --body-file message.txt --html-file message.html \
 --attach report.pdf

perch mail send ... --dry-run > message.eml

Environment

Variable	Purpose
`PERCH_IMAP_USER`	default account username and sender
`PERCH_IMAP_PASSWORD`	account password

perch mail caps

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

perch mail caps [OPTIONS]

Description

Connect to the configured submission server, perform EHLO, and print the advertised extensions. No message is sent and no credentials are used.

Aliases: capabilities.

Notes

The local perch relay advertises PIPELINING, 8BITMIME, ENHANCEDSTATUSCODES, SIZE, SMTPUTF8, STARTTLS, and AUTH on loopback or TLS.
It does not expose DSN, CHUNKING, BINARYMIME, REQUIRETLS, or DELIVERBY.

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)
`--smtp-server, -S <value>`	SMTP submission server (smtps://host, smtp://host, or host[:port]); defaults from –config
`--smtp-plaintext`	connect to SMTP without TLS (use only on trusted networks)
`--smtp-starttls`	require STARTTLS for SMTP
`--smtp-implicit-tls`	use implicit TLS for SMTP (usually port 465)
`--smtp-insecure`	skip SMTP TLS certificate verification
`--smtp-ca-file <value>`	PEM CA bundle used to verify the SMTP server certificate
`--help, -h`	show help

Examples

perch mail caps

perch mail caps --smtp-server smtp.mxraven.email:587

perch doctor

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

perch doctor [OPTIONS]

Description

Run integrity and connectivity checks for SQLite/FTS5, TLS certificate files, DNS, S3, and configured mxRaven listeners. The command exits non-zero when a check fails.

Notes

Run as the same user that runs serve so file permissions match.

Options

Option	Description
`--config <value>`	configuration file (default: ~/.config/perch/perch.yaml)
`--help, -h`	show help

Examples

perch doctor --config /etc/perch/perch.yaml

perch backup

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

perch backup [OPTIONS] <destination.db>

Description

Use SQLite’s online backup API to write a consistent copy while serve is running. The destination must not already exist.

Notes

Safe alongside serve because SQLite WAL mode allows concurrent readers and writers.

Options

Option	Description
`--config <value>`	configuration file (default: ~/.config/perch/perch.yaml)
`--help, -h`	show help

Examples

perch backup --config /etc/perch/perch.yaml /var/lib/perch/backups/perch-$(date +%F).db

perch reconcile

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

perch reconcile [OPTIONS]

Description

Scan the configured S3 bucket and bind objects written by mxRaven to local message metadata. Requires storage.mode=s3.

Notes

serve runs this at startup and every storage.s3.reconcile_every (default 5m).

Options

Option	Description
`--config <value>`	configuration file (default: ~/.config/perch/perch.yaml)
`--help, -h`	show help

Examples

perch reconcile --config /etc/perch/perch.yaml

perch gc

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

perch gc [OPTIONS]

Description

Remove orphaned local blobs, dead letters older than –dead-letter-age, enforce the S3 spool limit, and optionally delete S3 objects for deleted messages. An incremental vacuum runs by default.

Notes

–s3-delete is ignored in SQLite mode.
Without –s3-delete, S3 tombstones accumulate.

Options

Option	Description
`--config <value>`	configuration file (default: ~/.config/perch/perch.yaml)
`--dry-run`	report what would be removed
`--s3-delete`	delete S3 objects for deleted messages
`--dead-letter-age <value>`	delete dead letters older than this (default: 720h0m0s)
`--vacuum`	run incremental vacuum after cleanup
`--spool`	enforce storage.s3.spool_max_bytes
`--help, -h`	show help

Examples

perch gc --config /etc/perch/perch.yaml --dry-run

perch gc --config /etc/perch/perch.yaml --s3-delete

perch outbound

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

perch outbound [OPTIONS] COMMAND

Description

Inspect the outbound table populated by the submission relay. It shows acceptance and later delivery attempts reported by mxRaven.

Options

Option	Description
`--help, -h`	show help

Commands

Command	Description
perch outbound list	list submitted messages

Examples

perch outbound list --account you@example.com

perch outbound list

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

perch outbound list [OPTIONS]

Description

Print recent outbound submissions, optionally filtered by account. –limit defaults to 100.

Options

Option	Description
`--config <value>`	configuration file (default: ~/.config/perch/perch.yaml)
`--account <value>`	filter by account email
`--limit <value>`	maximum rows (default: 100)
`--help, -h`	show help

Examples

perch outbound list --limit 20

perch version

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

perch version [OPTIONS]

Description

Print the version embedded at build time, or the module version for go install builds.

Options

Option	Description
`--help, -h`	show help

Examples

perch version

perch

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

perch [OPTIONS] COMMAND

Description

perch runs a local IMAP server and authenticated submission endpoint, backed by mxRaven for inbound MX, outbound delivery, SPF/DKIM/DMARC, IP reputation, and spam filtering.

Messages are stored in SQLite or offloaded to S3. The same binary provides administrative commands and a scriptable mail client for IMAP and SMTP.

Notes

Run perch help <command> or see the per-command manpages for details.
The default configuration path is $XDG_CONFIG_HOME/perch/perch.yaml.
perch does not need a public IP, port forwarding, or inbound SMTP ports.

Options

Option	Description
`--help, -h`	show help
`--version, -v`	print the version

Commands

Command	Description
perch init	create a local configuration and optional first account
perch setup	create the mxRaven domain, listeners, keys, and routes
perch serve	run IMAP, submission, and the notification consumer
perch account	add, list, password, disable, or enable accounts
perch alias	manage address aliases and catch-all domains
perch mailbox	list mailboxes for an account
perch mail	list, search, fetch, and send mail
perch doctor	check the database, TLS, S3, and mxRaven connectivity
perch backup	write a consistent SQLite backup
perch reconcile	force one S3 bucket reconciliation pass
perch gc	remove orphan blobs, old dead letters, and S3 tombstones
perch outbound	list submitted messages and delivery status
perch version	print the version

Examples

perch setup --workspace my-workspace --domain example.com --hostname localhost

perch account add --email you@example.com

perch serve --config ~/.local/share/perch/perch.yaml

perch mail list --server 127.0.0.1:1143 --plaintext --username you@example.com

CLI reference on perch docs

perch init

Synopsis

Description

Notes

Options

Examples

See also

perch setup

Synopsis

Description

perch serve

Synopsis

Description

perch account

Synopsis

Description

Notes

Options

Commands

Examples

See also

perch account add

Synopsis

Description

Notes

Options

Examples

See also

perch account list

Synopsis

Description

Options

Examples

See also

perch account passwd

Synopsis

Description

Notes

Options

Examples

See also

perch account disable

Synopsis

Description

Options

Examples

See also

perch account enable

Synopsis

Description

Options

Examples

See also

perch alias

Synopsis

Description

Notes

Options

Commands

Examples

See also

perch alias add

Synopsis

Description

Options

Examples

See also

perch alias remove

Synopsis

Description

Options

Examples

See also

perch alias list

Synopsis

Description

Options

Examples

See also