CLI Commands

Matcha provides several subcommands for non-interactive use. These work without launching the TUI and are ideal for scripts, cron jobs, and AI agent integration.

matcha send

Send an email directly from the command line.

matcha send --to <recipients> --subject <subject> [flags]

Flags

Flag	Description
--to	Recipient(s), comma-separated (required)
--subject	Email subject (required)
--body	Email body (Markdown supported). Use "-" to read from stdin
--from	Sender account email. Defaults to first configured account
--cc	CC recipient(s), comma-separated
--bcc	BCC recipient(s), comma-separated
--attach	Attachment file path. Can be repeated for multiple files
--signature	Append default signature (default: true). Use --signature=false to disable
--sign-smime	Sign with S/MIME. Uses account default if not set
--encrypt-smime	Encrypt with S/MIME
--sign-pgp	Sign with PGP. Uses account default if not set

Examples

Simple email:

matcha send --to alice@example.com --subject "Meeting tomorrow" --body "Can we meet at 2pm?"

Send from a specific account:

matcha send --from work@company.com --to client@example.com --subject "Invoice" \
  --body "Please find the invoice attached." --attach ~/Documents/invoice.pdf

Multiple recipients with CC:

matcha send --to alice@example.com,bob@example.com --cc manager@example.com \
  --subject "Project update" --body "The project is on track."

Read body from stdin (useful for piping):

cat ~/notes/report.md | matcha send --to team@example.com --subject "Weekly Report" --body -

Multiple attachments:

matcha send --to alice@example.com --subject "Files" --body "Here are the files." \
  --attach report.pdf --attach data.csv

Without signature:

matcha send --to alice@example.com --subject "Quick note" --body "Thanks!" --signature=false

Account Selection

The --from flag matches against both the login email and fetch email of your configured accounts. If omitted, the first configured account is used.

# Use your work account
matcha send --from work@company.com --to someone@example.com --subject "Hi" --body "Hello"

Exit Codes

Code	Meaning
0	Email sent successfully
1	Error (missing flags, bad config, send failure)

matcha apply

Apply a patch you received by email — the output of git format-patch / git send-email — to a local working tree. This is matcha's "git-mail" workflow: review a patch in your inbox, then apply it without leaving the terminal.

matcha apply [patch-file] [flags]

The patch is read from patch-file, or from stdin when no file is given (or when the file is -). Matcha never runs git — it parses the email and writes the file changes directly, confined to the target directory.

Flags

Flag	Description
--repo	Working tree to apply into (default: current directory)
--check	Validate only — report what would change, write nothing (dry run)
--reverse	Unapply the patch instead of applying it
--series	Treat the input as an mbox and apply the whole patch series in order
-h	Show help

Examples

Apply a saved patch to a project:

matcha apply fix.patch --repo ~/src/myproject

Pipe a patch straight from git:

git format-patch -1 --stdout | matcha apply --repo .

Dry-run before committing to it:

matcha apply --check fix.patch --repo ~/src/myproject

Apply a whole series from an mbox:

matcha apply series.mbox --series --repo ~/src/myproject

Undo a patch you applied:

matcha apply --reverse fix.patch --repo ~/src/myproject

How it behaves

• Transactional (per patch). Every hunk is matched in memory before anything is written. If a hunk does not apply, the file is left untouched and the command exits non-zero — you never get a half-applied file.
• Offset-tolerant, context-exact. A patch still applies when surrounding edits have shifted the target lines, but the context itself must match — matcha will not silently patch the wrong place.
• Path-confined. Patches whose paths try to escape --repo (via ../ or an absolute path) are rejected before any file is touched.
• Series caveat. --series is transactional per patch, not across the whole series: if patch 3 of 5 conflicts, patches 1–2 are already written. Use --check --series first to validate the whole set.

Matcha does not create a git commit, move HEAD, or touch the index — it only edits files. Commit the result yourself once you are happy with it.

Under the hood, matcha apply uses the standalone go-mailpatch (parsing) and go-patchapply (applying) libraries, extracted from matcha.

Exit Codes

Code	Meaning
0	Patch applied (or, with --check, would apply) cleanly
1	Error (parse failure, hunk conflict, unsafe path, missing/existing file)

matcha marketplace

Open the interactive plugin marketplace in the terminal. Fetches the plugin registry from GitHub and displays a browsable list of available plugins.

matcha marketplace

Use j/k or arrow keys to navigate, Enter to install a plugin, and q to quit. Installed plugins are marked with an [installed] badge.

You can also access the marketplace from Matcha's main menu, or browse the online marketplace.

matcha install

Install a plugin from a URL or a local file.

matcha install <url_or_file>

Examples

Install from the official plugin repository:

matcha install https://raw.githubusercontent.com/floatpane/matcha/master/plugins/hello.lua

Install from a third-party URL:

matcha install https://raw.githubusercontent.com/someone/repo/main/my_plugin.lua

Install from a local file:

matcha install ~/Downloads/custom_plugin.lua

Plugins are saved to ~/.config/matcha/plugins/ and loaded automatically on next startup. The file must have a .lua extension.

matcha contacts export

Export your contacts cache to JSON or CSV format.

matcha contacts export [flags]

Flags

Flag	Description
-f	Output format: json or csv (default: json)
-o	Output file path. If omitted, prints to stdout
--no-header	Omit CSV header row (CSV format only)
-h	Show help

Examples

Export as JSON to stdout:

matcha contacts export

Export as CSV to stdout:

matcha contacts export -f csv

Export to a file:

matcha contacts export -o ~/contacts.json
matcha contacts export -f csv -o ~/contacts.csv

Export CSV without headers:

matcha contacts export -f csv --no-header

If encryption is enabled, you will be prompted for your password before the contacts can be read.

Output Format

JSON exports an array of contact objects with name, email, last_used, and use_count fields.

CSV exports a header row (name,email,last_used,use_count) followed by one row per contact. Use --no-header to omit the header row.

matcha dict

Manage spellcheck dictionaries. Dictionaries are downloaded from the wooorm/dictionaries Hunspell repository and stored in ~/.config/matcha/dicts/<lang>.dic.

matcha dict add <language-code>      # download and install a dictionary
matcha dict remove <language-code>   # delete an installed dictionary
matcha dict list                     # show installed dictionaries

The English dictionary (en) is downloaded automatically the first time you open the composer — matcha dict add is only needed for additional languages.

Examples

matcha dict add en-GB     # British English
matcha dict add de        # German
matcha dict add fr        # French
matcha dict add es        # Spanish
matcha dict add ru        # Russian
matcha dict list
matcha dict remove fr

Language codes match the directory names under dictionaries/ in the upstream repository.

matcha config

Open a configuration file in your $EDITOR (falls back to vi).

matcha config [plugin_name]

Examples

Open the main config file:

matcha config

Opens ~/.config/matcha/config.json.

Open a plugin for configuration:

matcha config ai_rewrite

Opens ~/.config/matcha/plugins/ai_rewrite.lua so you can edit settings like API keys or model names.

matcha update

Check for and install the latest version of Matcha.

matcha update

Automatically detects your installation method (Homebrew, Snap, Flatpak, WinGet, or binary) and updates accordingly.

matcha oauth

Manage OAuth2 authorization for Gmail and Outlook.

matcha oauth auth <email>                        # Authorize an account (opens browser, auto-detects provider)
matcha oauth auth <email> --provider outlook     # Specify provider explicitly
matcha oauth token <email>                       # Print a fresh access token
matcha oauth revoke <email>                      # Revoke and delete stored tokens

matcha gmail is kept as an alias for backwards compatibility.

Client credentials are stored per provider:

• Gmail: ~/.config/matcha/oauth_client.json — see the Gmail setup guide
• Outlook: ~/.config/matcha/oauth_client_outlook.json — see the Outlook setup guide

matcha version

Print the current version.

matcha --version
matcha -v
matcha version