Command line (developer preview)

The foldmail command: its current state, commands, options, rule files and exit codes.

Developer preview. foldmail is not included in the FOLD app. It currently exists as a build from the FOLD source code for development and testing. It works on its own local data store, not on the data of the FOLD app, which the macOS sandbox keeps in the app’s container. The command line therefore does not see the mail you have in the app, and mail it queues is not sent by the app. Its messages and help text are currently in German.

This page describes what the preview does today. Commands, options and output may change before the command line ships.

Commands

Command	What it does
`foldmail accounts`	Lists the accounts
`foldmail mailboxes --account <name>`	Lists the folders of an account with unread and total counts
`foldmail search <query>`	Searches with the search syntax; `list` is an alias
`foldmail read <id>`	Shows a message; `--headers` leaves out the text. Without a locally stored body, the preview is shown
`foldmail flag <id…> --add <flag> --remove <flag>`	Sets or removes flags and tags, for example `\Seen`, `\Flagged` or `important`; both options can be repeated
`foldmail delete <id…>`	Removes messages from the local store; explicit IDs are required
`foldmail compose --from <addr> --to <addr>`	Builds the message and writes it to standard output
`foldmail send --account <name> --from <addr> --to <addr>`	Same as `compose --enqueue`: puts the message into the outbox
`foldmail outbox list --account <name>`	Lists the outbox
`foldmail outbox cancel <id>`	Takes a waiting message back out of the outbox
`foldmail filter run --rules <file>`	Runs a rule file; preview unless `--apply` is given
`foldmail help`	Shows the help; so does `foldmail` without arguments

The command line does not send mail itself. send and compose --enqueue only put the message into the command line’s outbox; foldmail does not deliver it, and the FOLD app does not read that outbox. The built-in help still shows its examples with fold; the command is foldmail.

Options

Option	Used with	Meaning
`--json`	all	Output as JSON (indented, sorted keys, ISO 8601 dates). The structure is not versioned yet
`--quiet`	all	Only IDs, or only the number of changed messages
`--limit <n>`	`search`	Maximum number of results, default 100
`--offset <n>`	`search`	Skip the first n results
`--account <name>`	`mailboxes`, `send`, `compose --enqueue`, `outbox list`	Account display name or address
`--headers`	`read`	Headers only
`--add`, `--remove <flag>`	`flag`	Flag or tag to set or remove
`--from`, `--to`, `--cc`, `--bcc`, `--subject`, `--body`	`compose`, `send`	Message fields; `--to`, `--cc`, `--bcc` can be repeated. Without `--body`, remaining arguments form the text
`--enqueue`	`compose`	Queue instead of printing
`--delay <seconds>`	`send`, `compose --enqueue`	Wait before sending, as an undo window
`--rules <file>`	`filter run`	Rule file in JSON
`--apply`	`filter run`	Apply the rules instead of previewing

In the command line, account: and from-account: filter by account display name or address. in: has no effect here either.

Pass a query as one quoted argument. A separate argument that starts with a minus is read as an option and dropped, so write foldmail search 'from:anna -is:read', or put -- before a query that starts with a minus: foldmail search -- '-is:read'.

Rule files

filter run reads rules with the same structure as the app’s filter rules, written as JSON:

{
  "schemaVersion": 1,
  "rules": [
    {
      "name": "Newsletters",
      "match": "from:newsletter@example.com",
      "actions": [{ "type": "markRead" }, { "type": "addFlag", "flag": "newsletter" }],
      "stopOnMatch": false
    }
  ]
}

Action types: markRead, markUnread, addFlag and removeFlag (with flag), delete, move (with mailbox), forward (with to, a list) and autoReply (with body). With --apply, a rule file that contains move, forward or autoReply is refused before anything changes; the preview still shows its matches.

Exit codes

Code	Meaning
0	Success
1	General error, for example the store cannot be opened, a search operator is not supported (`has:attachment`), a message body or attachment is not available, or an outbox entry can no longer be cancelled
2	Usage error: unknown command, missing option or option value, unreadable rule file, invalid query or message ID
3	Nothing found: empty result, unknown message or folder, or no rule matched
4	The message data is incomplete or unreadable

If an account in the command line’s store uses Fortress Mode, foldmail refuses to run and exits with 1, so it never writes unencrypted data into an encrypted store.

Examples

foldmail search 'from:anna is:unread' --json
foldmail search 'is:unread' --quiet | xargs foldmail flag --add '\Seen'
foldmail compose --from me@example.com --to anna@example.com --subject Hi --body 'Test' > mail.eml
foldmail filter run --rules ~/rules.json
foldmail filter run --rules ~/rules.json --apply