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 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 gmail

Manage Gmail OAuth2 authorization.

matcha gmail auth <email>     # Authorize a Gmail account (opens browser)
matcha gmail token <email>    # Print a fresh access token
matcha gmail revoke <email>   # Revoke and delete stored tokens

Requires OAuth2 client credentials in ~/.config/matcha/oauth_client.json. See the Gmail setup guide for details.

matcha version

Print the current version.

matcha --version
matcha -v
matcha version