### Clone and Setup Matcha Project

Source: https://github.com/floatpane/matcha/blob/master/CONTRIBUTING.md

Clone the Matcha repository and install its dependencies using Go modules.

```bash
git clone https://github.com/floatpane/matcha.git
cd matcha
go mod tidy
```

--------------------------------

### matcha install

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/Features/CLI.md

Install a plugin from a URL or a local file.

```APIDOC
## matcha install

### Description
Install a plugin from a URL or a local file.

### Usage
```bash
matcha install <url_or_file>
```

### Examples
**Install from the official plugin repository:**
```bash
matcha install https://raw.githubusercontent.com/floatpane/matcha/master/plugins/hello.lua
```

**Install from a third-party URL:**
```bash
matcha install https://raw.githubusercontent.com/someone/repo/main/my_plugin.lua
```

**Install from a local file:**
```bash
matcha install ~/Downloads/custom_plugin.lua
```

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

--------------------------------

### Install Matcha via Winget

Source: https://context7.com/floatpane/matcha/llms.txt

Install Matcha on Windows using Winget. This is the recommended method for Windows users.

```bash
# Windows — Winget
winget install --id=floatpane.matcha
```

--------------------------------

### Install Plugin from URL

Source: https://github.com/floatpane/matcha/blob/master/plugins/README.md

Install a plugin directly from a provided URL. Ensure the URL points to a valid plugin file.

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

--------------------------------

### Matcha PGP Configuration Example

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/Features/PGP.md

Example of how PGP settings are stored per account in Matcha's configuration file. Adjust paths and booleans according to your setup.

```json
{
  "accounts": [
    {
      "email": "you@example.com",
      "pgp_public_key": "/home/you/.config/matcha/pgp/public.asc",
      "pgp_private_key": "/home/you/.config/matcha/pgp/private.asc",
      "pgp_sign_by_default": true,
      "pgp_encrypt_by_default": false
    }
  ]
}
```

--------------------------------

### Enable and Start Systemd Service

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/Features/DAEMON.md

Commands to enable the Matcha daemon service to start on boot and to start it immediately on a Linux system using systemd.

```bash
systemctl --user enable matcha-daemon
systemctl --user start matcha-daemon
```

--------------------------------

### Install Matcha via Flatpak

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/installation.md

Install Matcha using Flatpak by providing the URL to the Flatpak reference file.

```bash
flatpak install https://matcha.floatpane.com/matcha.flatpakref
```

--------------------------------

### Browse and Install Plugins

Source: https://github.com/floatpane/matcha/blob/master/README.md

Use these commands to manage plugins within the Matcha terminal client. The marketplace command browses plugins, install adds a new plugin, and config allows for configuration of installed plugins.

```bash
matcha marketplace                # browse plugins in the TUI
```

```bash
matcha install <url_or_file>      # install a plugin
```

```bash
matcha config <plugin_name>       # configure an installed plugin
```

--------------------------------

### Install Plugin via CLI

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/Features/CLI.md

Install a plugin from a URL or a local file. Plugins are saved to ~/.config/matcha/plugins/ and must have a .lua extension.

```bash
matcha install <url_or_file>
```

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

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

```bash
matcha install ~/Downloads/custom_plugin.lua
```

--------------------------------

### Run Matcha after installation

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/installation.md

Execute the 'matcha' command in your terminal after installation to run the application.

```bash
matcha
```

--------------------------------

### Install pcscd and ccid on Fedora

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/Features/PGP.md

Install the necessary packages for YubiKey and smartcard support on Fedora. Enable and start the pcscd service.

```bash
sudo dnf install pcsc-lite ccid
sudo systemctl enable --now pcscd.socket
```

--------------------------------

### Install Plugin from Local File

Source: https://github.com/floatpane/matcha/blob/master/plugins/README.md

Install a plugin by specifying the local file path. The plugin will be copied to the user's configuration directory.

```bash
matcha install path/to/my_plugin.lua
```

--------------------------------

### Handle Startup Event

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/Features/Plugins.md

Execute code when Matcha starts up and all plugins are loaded using the 'startup' event.

```lua
matcha.on("startup", function()
  matcha.log("plugin ready")
end)
```

--------------------------------

### Install Matcha via Snap

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/installation.md

Install Matcha using the Snap package manager. This is a convenient method for systems that support Snap.

```bash
sudo snap install matcha
```

--------------------------------

### Install Plugin from TUI Marketplace

Source: https://github.com/floatpane/matcha/blob/master/plugins/README.md

Use this command to interactively browse and install plugins from the Matcha TUI marketplace. Navigate with j/k or arrow keys, select with Enter, and quit with q.

```bash
matcha marketplace
```

--------------------------------

### Install and Configure AI Rewrite Plugin

Source: https://context7.com/floatpane/matcha/llms.txt

Install the `ai_rewrite.lua` plugin using the `matcha install` command. Configure AI provider details in the `ai_rewrite.lua` file. Press `Ctrl+R` in the composer to use.

```bash
# Install the plugin
matcha install https://raw.githubusercontent.com/floatpane/matcha/master/plugins/ai_rewrite.lua

# Open for configuration
matcha config ai_rewrite
```

```lua
-- OpenAI
local API_URL = "https://api.openai.com/v1/chat/completions"
local API_KEY = "sk-proj-YOUR_OPENAI_API_KEY"
local MODEL   = "gpt-4o-mini"

-- Ollama (local, no key needed)
local API_URL = "http://localhost:11434/v1/chat/completions"
local API_KEY = ""
local MODEL   = "llama3"

-- Google Gemini
local API_URL = "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions"
local API_KEY = "YOUR_GEMINI_API_KEY"
local MODEL   = "gemini-1.5-flash"

-- Anthropic Claude (via LiteLLM proxy)
-- pip install litellm && litellm --model claude-3-5-sonnet-20241022 --api_key YOUR_KEY
local API_URL = "http://localhost:4000/v1/chat/completions"
local API_KEY = ""
local MODEL   = "claude-3-5-sonnet-20241022"
```

--------------------------------

### Install Matcha via Nix

Source: https://context7.com/floatpane/matcha/llms.txt

Install or run Matcha on Linux or macOS using Nix. This command allows running Matcha directly or installing it via Nix.

```bash
# Linux / macOS — Nix
nix run github:floatpane/matcha
```

--------------------------------

### Install Plugin using curl

Source: https://github.com/floatpane/matcha/blob/master/plugins/README.md

Download a plugin using curl and save it directly to the Matcha plugins directory. This is useful for scripting or automated setups.

```bash
curl -sL https://raw.githubusercontent.com/floatpane/matcha/master/plugins/hello.lua \
  -o ~/.config/matcha/plugins/hello.lua
```

--------------------------------

### Install Matcha via Winget on Windows

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/installation.md

Install Matcha on Windows using the Winget package manager. This is the recommended method for Windows.

```powershell
winget install --id=floatpane.matcha
```

--------------------------------

### Manage Matcha Plugins via Marketplace and Install

Source: https://context7.com/floatpane/matcha/llms.txt

Browse, install, and configure Lua plugins for Matcha from the terminal. Use `matcha marketplace` for an interactive TUI, `matcha install` with URLs or local file paths, and `matcha config` to edit plugin settings or the main configuration.

```bash
# Open interactive TUI marketplace (j/k to navigate, Enter to install, q to quit)
matcha marketplace
```

```bash
# Install a plugin from the official registry by URL
matcha install https://raw.githubusercontent.com/floatpane/matcha/master/plugins/hello.lua
```

```bash
# Install from a third-party URL
matcha install https://raw.githubusercontent.com/someone/repo/main/my_plugin.lua
```

```bash
# Install from a local file
matcha install ~/Downloads/custom_plugin.lua
```

```bash
# Edit a plugin's settings in $EDITOR
matcha config ai_rewrite        # opens ~/.config/matcha/plugins/ai_rewrite.lua
```

```bash
# Edit main config
matcha config                   # opens ~/.config/matcha/config.json
```

--------------------------------

### Install pcscd and ccid on Debian/Ubuntu

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/Features/PGP.md

Install the necessary packages for YubiKey and smartcard support on Debian/Ubuntu systems. Enable and start the pcscd service.

```bash
sudo apt install pcscd libccid
sudo systemctl enable --now pcscd.socket
```

--------------------------------

### Install pcscd and ccid on Arch Linux

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/Features/PGP.md

Install the necessary packages for YubiKey and smartcard support on Arch Linux. Enable and start the pcscd service.

```bash
sudo pacman -S pcsclite ccid
sudo systemctl enable --now pcscd.socket
```

--------------------------------

### Event: startup

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/Features/Plugins.md

Fired once when Matcha starts up, after all plugins have been loaded. Useful for initialization tasks.

```APIDOC
## Event: startup

### Description
Fired once when Matcha starts, after all plugins are loaded.

### Example
```lua
matcha.on("startup", function()
  matcha.log("plugin ready")
end)
```
```

--------------------------------

### Install Matcha into Nix profile

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/installation.md

Install Matcha into your Nix profile for system-wide access using Nix flakes.

```bash
nix profile install github:floatpane/matcha
```

--------------------------------

### Install Matcha via Homebrew on macOS

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/installation.md

Use Homebrew to tap the repository and install the Matcha package. This is the recommended method for macOS.

```bash
brew tap floatpane/matcha
brew install floatpane/matcha/matcha
```

--------------------------------

### Install and Run LiteLLM Proxy

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/setup-guides/ai-rewrite.md

Installs the LiteLLM Python package and starts a local proxy server. This server translates OpenAI-formatted requests for use with non-compatible APIs like Anthropic Claude.

```bash
pip install litellm
litellm --model claude-3-5-sonnet-20241022 --api_key YOUR_ANTHROPIC_API_KEY
```

--------------------------------

### Install Matcha via Snap

Source: https://context7.com/floatpane/matcha/llms.txt

Install Matcha on Linux using Snap. This method is suitable for Linux distributions that support Snap packages.

```bash
# Linux — Snap
sudo snap install matcha
```

--------------------------------

### Install Matcha via Flatpak

Source: https://context7.com/floatpane/matcha/llms.txt

Install Matcha on Linux using Flatpak. This method is suitable for Linux distributions that support Flatpak.

```bash
# Linux — Flatpak
flatpak install https://matcha.floatpane.com/matcha.flatpakref
```

--------------------------------

### Example: Emacs-style Navigation Keybinds

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/Features/Keybinds.md

This JSON configuration demonstrates how to set up Emacs-style navigation keybinds for global actions like quitting, canceling, and moving up/down.

```json
{
  "global": {
    "quit": "ctrl+x",
    "cancel": "esc",
    "nav_up": "ctrl+p",
    "nav_down": "ctrl+n"
  }
}
```

--------------------------------

### Matcha Configuration File Example

Source: https://context7.com/floatpane/matcha/llms.txt

Example JSON configuration file for Matcha, specifying email accounts, mailing lists, and UI preferences. Passwords are not stored here since v0.19.0.

```json
{
  "accounts": [
    {
      "id": "unique-id-1",
      "name": "John Doe",
      "email": "john@gmail.com",
      "service_provider": "gmail",
      "fetch_email": "john@gmail.com",
      "send_as_email": "john@alias.example"
    },
    {
      "id": "unique-id-2",
      "name": "Work Email",
      "email": "john@company.com",
      "service_provider": "custom",
      "fetch_email": "john@company.com",
      "imap_server": "imap.company.com",
      "imap_port": 993,
      "smtp_server": "smtp.company.com",
      "smtp_port": 587
    }
  ],
  "mailing_lists": [
    {
      "name": "Team",
      "addresses": ["alice@example.com", "bob@example.com"]
    }
  ],
  "theme": "Matcha",
  "enable_split_pane": true,
  "disable_images": false,
  "hide_tips": true,
  "language": "en"
}
```

--------------------------------

### Example Matcha Configuration

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/Configuration.md

This JSON object demonstrates a typical configuration for Matcha, including multiple accounts with different service providers and settings, mailing list configurations, and UI preferences. Passwords are omitted in this example.

```json
{
  "accounts": [
    {
      "id": "unique-id-1",
      "name": "John Doe",
      "email": "john@gmail.com",
      "service_provider": "gmail",
      "fetch_email": "john@gmail.com",
      "send_as_email": "john@alias.example",
      "smime_cert": "/home/jane/.certs/jane_smime_cert.pem",
      "smime_key": "/home/jane/.certs/jane_smime_private.pem"
    },
    {
      "id": "unique-id-2",
      "name": "Work Email",
      "email": "john@company.com",
      "service_provider": "custom",
      "fetch_email": "john@company.com",
      "imap_server": "imap.company.com",
      "imap_port": 993,
      "smtp_server": "smtp.company.com",
      "smtp_port": 587
    }
  ],
  "mailing_lists": [
    {
      "name": "Team",
      "addresses": ["alice@example.com", "bob@example.com"]
    }
  ],
  "theme": "Matcha",
  "enable_split_pane": true,
  "disable_images": true,
  "hide_tips": true
}
```

--------------------------------

### Install AI Rewrite Plugin

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/setup-guides/ai-rewrite.md

Installs the AI Rewrite plugin from a GitHub URL. This is the initial step to enable AI rewriting capabilities in Matcha.

```bash
matcha install https://raw.githubusercontent.com/floatpane/matcha/master/plugins/ai_rewrite.lua
```

--------------------------------

### Build Matcha from Source

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/installation.md

Build the Matcha executable from source code using the Go compiler. Ensure Go is installed and you are in the project's root directory.

```bash
go build .
```

--------------------------------

### Install Matcha from AUR on Arch Linux

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/installation.md

Install the unofficial Matcha package from the Arch User Repository (AUR) using an AUR helper like 'yay'.

```bash
yay -S matcha-client-bin
```

--------------------------------

### matcha marketplace

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/Features/CLI.md

Open the interactive plugin marketplace in the terminal to browse and install plugins.

```APIDOC
## matcha marketplace

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

### Usage
```bash
matcha marketplace
```

### Interaction
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](https://docs.matcha.floatpane.com/marketplace).
```

--------------------------------

### Update Matcha via CLI

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/usage.md

Run this command to check for and install the latest version of Matcha. It automatically detects your installation method.

```bash
matcha update
```

--------------------------------

### Registry Entry JSON Example

Source: https://github.com/floatpane/matcha/blob/master/plugins/README.md

Example of a JSON entry for the registry.json file when submitting a new plugin. Ensure all required fields are present and accurate.

```json
{
  "name": "my_plugin",
  "title": "My Plugin",
  "description": "A short description of what your plugin does.",
  "file": "my_plugin.lua",
  "url": "https://raw.githubusercontent.com/YOUR_USER/YOUR_REPO/main/my_plugin.lua"
}
```

--------------------------------

### Configure Plugin or Settings

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/Features/Plugins.md

Opens an installed plugin's configuration file in the editor for modification. If no plugin name is provided, it opens the main `config.json`.

```bash
matcha config hello          # opens ~/.config/matcha/plugins/hello.lua
```

```bash
matcha config                # opens ~/.config/matcha/config.json
```

--------------------------------

### Run Matcha using Nix flakes

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/installation.md

Execute Matcha directly from its GitHub repository using Nix flakes without a formal installation.

```bash
nix run github:floatpane/matcha
```

--------------------------------

### Matcha Daemon Commands

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/Features/DAEMON.md

Commands to manage the Matcha background daemon. Use these to start, stop, check status, or run the daemon in the foreground.

```bash
matcha daemon start    # Start the daemon in the background
matcha daemon stop     # Stop the running daemon
matcha daemon status   # Show daemon status (PID, uptime, accounts)
matcha daemon run      # Run the daemon in the foreground (for systemd/launchd)
```

--------------------------------

### Configure Matcha Daemon as a systemd User Service

Source: https://context7.com/floatpane/matcha/llms.txt

Set up the Matcha daemon to run as a systemd user service on Linux. This involves creating a `.service` file in `~/.config/systemd/user/` and then enabling and starting the service using `systemctl`.

```ini
# ~/.config/systemd/user/matcha-daemon.service
[Unit]
Description=Matcha Email Daemon
After=network-online.target

[Service]
ExecStart=/usr/bin/matcha daemon run
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target
```

```bash
systemctl --user enable matcha-daemon
systemctl --user start matcha-daemon
```

--------------------------------

### Example: Single-Key Actions in Inbox

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/Features/Keybinds.md

This JSON configuration shows an example of mapping single keys to various actions within the inbox area, such as delete, archive, refresh, and tab navigation.

```json
{
  "inbox": {
    "delete": "x",
    "archive": "e",
    "refresh": "g",
    "open": "enter",
    "visual_mode": "V",
    "next_tab": "n",
    "prev_tab": "p"
  }
}
```

--------------------------------

### Configure S/MIME Account Settings

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/Features/SMIME.md

Example JSON configuration for an email account with S/MIME enabled. Ensure paths to your certificate and private key are correct.

```json
{
  "accounts": [
    {
      "email": "you@example.com",
      "smime_cert": "/home/you/.certs/cert.pem",
      "smime_key": "/home/you/.certs/private.pem",
      "smime_sign_by_default": true
    }
  ]
}
```

--------------------------------

### Matcha Daemon Status Output

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/Features/DAEMON.md

Example output when checking the status of the running Matcha daemon. It shows the process ID, uptime, and configured accounts.

```bash
$ matcha daemon status
Daemon running (PID 12345)
Uptime: 2h 15m
Accounts: 2
  - alice@gmail.com
  - bob@outlook.com
```

--------------------------------

### Template Interpolation Example

Source: https://github.com/floatpane/matcha/blob/master/i18n/README.md

Demonstrates simple variable substitution in a template string using a map of data. This system is designed for basic replacement without complex logic.

```go
template := "Update available: {latest} (current: {current})"
data := map[string]interface{}{
    "latest": "1.5.0",
    "current": "1.4.0",
}
result := Interpolate(template, data)
// → "Update available: 1.5.0 (current: 1.4.0)"
```

--------------------------------

### Launch Matcha TUI

Source: https://context7.com/floatpane/matcha/llms.txt

Launch the interactive terminal user interface (TUI) for Matcha after installation or building from source.

```bash
# Launch the TUI
matcha
```

--------------------------------

### Launchd Property List for Matcha Daemon

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/Features/DAEMON.md

Configuration file for launchd to manage the Matcha daemon as a background agent on macOS. This ensures the daemon starts automatically.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.matcha.daemon</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/matcha</string>
        <string>daemon</string>
        <string>run</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>
```

--------------------------------

### Open Text Input Prompt

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/Features/Plugins.md

Use matcha.prompt within a composer key binding to get user input. The callback is invoked with the user's text upon pressing Enter.

```lua
matcha.bind_key("ctrl+r", "composer", "rewrite", function(state)
  matcha.prompt("Enter instruction:", function(input)
    matcha.log("User typed: " .. input)
    -- Use matcha.http() + matcha.set_compose_field() to process and update the body
  end)
end)
```

--------------------------------

### Configure YubiKey for PGP with GnuPG

Source: https://context7.com/floatpane/matcha/llms.txt

Install necessary packages for YubiKey support on Linux and configure GnuPG's smart card daemon to share the YubiKey between GnuPG and Matcha. This prevents `LIBUSB_ERROR_BUSY` errors.

```bash
# Prerequisites for YubiKey on Linux
sudo pacman -S pcsclite ccid          # Arch
sudo apt install pcscd libccid        # Debian/Ubuntu
sudo systemctl enable --now pcscd.socket

# Share YubiKey between GnuPG and Matcha (prevents LIBUSB_ERROR_BUSY)
echo -e "disable-ccid\npcsc-shared" >> ~/.gnupg/scdaemon.conf
gpgconf --kill scdaemon
```

--------------------------------

### matcha.http(options)

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/Features/Plugins.md

Makes an HTTP request. It accepts an options table and returns a response table on success or nil and an error string on failure. Supports GET, POST, PUT, DELETE, and other methods. Headers and request bodies can be provided. Response includes status, body, and headers. Requests time out after 10 seconds and response bodies are capped at 1MB. Only http and https URLs are allowed.

```APIDOC
## matcha.http(options)

### Description
Make an HTTP request. Takes a single options table and returns two values: a response table on success, or `nil` plus an error string on failure.

### Parameters
#### Options table
- `url` (string, yes) - Request URL (http or https only)
- `method` (string, no) - HTTP method (default `"GET"`)
- `headers` (table, no) - Request headers as key-value pairs
- `body` (string, no) - Request body

### Response table
- `status` (number) - HTTP status code (e.g. 200)
- `body` (string) - Response body (capped at 1 MB)
- `headers` (table) - Response headers (lowercase keys)

### Limits
Requests time out after 10 seconds. Response bodies are capped at 1 MB. Only `http://` and `https://` URLs are allowed.

### Request Example
```lua
-- GET request
local res, err = matcha.http({ url = "https://api.example.com/status" })
if err then
  matcha.log("error: " .. err)
  return
end
matcha.log("status: " .. res.status)

-- POST request with headers and body
local res, err = matcha.http({
  url     = "https://hooks.slack.com/services/xxx",
  method  = "POST",
  headers = { ["Content-Type"] = "application/json" },
  body    = '{"text":"New email received!"}',
})
```
```

--------------------------------

### Keybind Conflict Warning Example

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/Features/Keybinds.md

When two actions within the same area share a keybind, Matcha displays a warning message in the start menu. This example shows a conflict in the 'inbox' area for the 'd' key.

```text
⚠ keybind conflict in inbox: "d" used for both "delete" and "archive"
```

--------------------------------

### Manage Matcha Background Email Daemon

Source: https://context7.com/floatpane/matcha/llms.txt

Control the Matcha background email daemon for persistent IMAP connections, mail syncing, notifications, and instant TUI startup. Use `start`, `status`, `stop`, or `run` commands. The `run` command is suitable for systemd/launchd.

```bash
# Start daemon in background
matcha daemon start
```

```bash
# Check status
matcha daemon status
```

```bash
# Stop daemon
matcha daemon stop
```

```bash
# Run in foreground (for use with systemd/launchd)
matcha daemon run
```

--------------------------------

### Translation Manager Usage Example

Source: https://github.com/floatpane/matcha/blob/master/i18n/README.md

Demonstrates how TUI components use the Translation Manager's T, Tn, and Tpl functions for simple, pluralized, and templated translations respectively. Ensure the manager is initialized and translations are loaded before use.

```go
import "github.com/floatpane/matcha/i18n"

func render() string {
    title := i18n.GetManager().T("composer.title")
    count := i18n.GetManager().Tn("inbox.unread", 5, map[string]interface{}{
        "count": 5,
    })
    return title + " - " + count
}
```

--------------------------------

### Conventional Commits Examples

Source: https://github.com/floatpane/matcha/blob/master/CONTRIBUTING.md

Examples of commit messages following the Conventional Commits specification.

```git
feat(compose): add CC/BCC field support
```

```git
fix(imap): handle connection timeout gracefully
```

```git
docs: update installation instructions
```

--------------------------------

### Load Hello Plugin on Startup

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/Features/Plugins.md

A basic Lua plugin that logs a message to the Matcha console upon successful startup.

```lua
local matcha = require("matcha")

matcha.on("startup", function()
  matcha.log("hello plugin loaded")
end)
```

--------------------------------

### Install CCID Driver

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/Features/PGP.md

Install the CCID driver, which is required for smart card readers like the YubiKey to communicate with the system.

```bash
# Arch Linux
sudo pacman -S ccid

# Debian/Ubuntu
sudo apt install libccid
```

--------------------------------

### Build and Run Matcha

Source: https://github.com/floatpane/matcha/blob/master/CONTRIBUTING.md

Commands to build the Matcha executable and run it.

```bash
make build     # builds to bin/matcha
```

```bash
make run       # builds and runs in one step
```

--------------------------------

### Build Matcha from Source

Source: https://context7.com/floatpane/matcha/llms.txt

Build the Matcha executable from its Go source code. This requires a Go development environment.

```bash
# Build from source
go build .
```

--------------------------------

### Register Startup and Shutdown Event Hooks

Source: https://context7.com/floatpane/matcha/llms.txt

Logs messages on plugin startup and shutdown. Requires `require("matcha")`.

```lua
local matcha = require("matcha")

-- Fired once on startup
matcha.on("startup", function()
  matcha.log("plugin loaded")
end)

-- Fired on shutdown
matcha.on("shutdown", function()
  matcha.log("goodbye")
end)
```

--------------------------------

### Configure Matcha Daemon as a launchd Agent (macOS)

Source: https://context7.com/floatpane/matcha/llms.txt

Configure the Matcha daemon to run as a launchd agent on macOS. Create a `.plist` file in `~/Library/LaunchAgents/` and then load it using `launchctl`.

```xml
<!-- ~/Library/LaunchAgents/com.matcha.daemon.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key><string>com.matcha.daemon</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/matcha</string>
        <string>daemon</string>
        <string>run</string>
    </array>
    <key>RunAtLoad</key><true/>
    <key>KeepAlive</key><true/>
</dict>
</plist>
```

```bash
launchctl load ~/Library/LaunchAgents/com.matcha.daemon.plist
```

--------------------------------

### Open Main Configuration File with Matcha

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/Features/CLI.md

Use this command to open the main configuration file for Matcha. This file is typically located at `~/.config/matcha/config.json`.

```bash
matcha config
```

--------------------------------

### Perform HTTP GET Request

Source: https://context7.com/floatpane/matcha/llms.txt

Makes an HTTP GET request to a specified URL and logs the status and body. Requires `require("matcha")`.

```lua
local matcha = require("matcha")

-- GET request
local res, err = matcha.http({ url = "https://api.example.com/status" })
if err then
  matcha.log("request failed: " .. err)
  return
end
matcha.log("HTTP " .. res.status .. ": " .. res.body)
```

--------------------------------

### Configure Matcha

Source: https://github.com/floatpane/matcha/blob/master/plugins/README.md

Open the main Matcha configuration file (config.json) in your default editor.

```bash
matcha config                # opens ~/.config/matcha/config.json in $EDITOR
```

--------------------------------

### Plugin Directory Structure

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/Features/Plugins.md

Illustrates the expected file and directory structure for placing Lua plugins in the Matcha configuration directory.

```text
~/.config/matcha/plugins/
├── hello.lua
├── notify_github.lua
└── my_plugin/
    └── init.lua
```

--------------------------------

### Implementing a Pluralization Function

Source: https://github.com/floatpane/matcha/blob/master/i18n/README.md

Provides an example of how to implement a language-specific pluralization function based on CLDR rules.

```go
// In plural_rules.go
func YourLanguagePlural(n int) PluralForm {
    // Implement CLDR rules for your language
    if n == 1 {
        return One
    }
    return Other
}
```

--------------------------------

### Open Plugin Configuration File with Matcha

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/Features/CLI.md

Use this command to open a specific plugin's configuration file. This is useful for editing settings such as API keys or model names for plugins like `ai_rewrite`.

```bash
matcha config ai_rewrite
```

--------------------------------

### Matcha Lock Screen Example

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/Features/Encryption.md

This is the lock screen displayed when Matcha is launched with encryption enabled. Enter your password to unlock.

```text
matcha is locked

> ********

enter: unlock | ctrl+c: quit
```

--------------------------------

### Registering a New Language

Source: https://github.com/floatpane/matcha/blob/master/i18n/README.md

Demonstrates how to register a new language locale, including its code, name, directionality, and pluralization function.

```go
package languages

import "github.com/floatpane/matcha/i18n"

func init() {
    i18n.RegisterLanguage(&i18n.Locale{
        Code:       "xx",
        Name:       "YourLanguage",
        NativeName: "YourLanguageInNativeScript",
        Direction:  "ltr",  // or "rtl" for Arabic, Hebrew, etc.
        PluralFunc: i18n.YourLanguagePlural,
    })
}
```

--------------------------------

### Render Matcha Application

Source: https://github.com/floatpane/matcha/blob/master/public/index.html

Initializes the React root and renders the main Matcha application component. Ensure the 'root' element exists in your HTML.

```javascript
const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<window.MatchaApp />);
```

--------------------------------

### Install Claude Code Skill

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/Features/AI_AGENTS.md

Symlink the `send-email` skill to your global Claude Code skills directory to make it available in all projects.

```bash
mkdir -p ~/.claude/skills
ln -s /path/to/matcha/.claude/skills/send-email ~/.claude/skills/send-email
```

--------------------------------

### Open Configuration File via CLI

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/Features/CLI.md

Open a configuration file in your default editor (or vi if none is set). Optionally specify a plugin name to open its specific configuration.

```bash
matcha config [plugin_name]
```

--------------------------------

### Start and Verify pcscd Service

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/Features/PGP.md

Ensure the pcscd service is running and enabled to manage smart card connections, which is necessary for YubiKey detection.

```bash
# Start pcscd
sudo systemctl enable --now pcscd.socket

# Verify it's running
systemctl status pcscd.socket
```

--------------------------------

### matcha config

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/Features/CLI.md

Open a configuration file in your default editor.

```APIDOC
## matcha config

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

### Usage
```bash
matcha config [plugin_name]
```
```

--------------------------------

### Enable Split View via Configuration File

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/Features/SPLIT_VIEW.md

Add this JSON key-value pair to your `~/.config/matcha/config.json` file to enable the split pane view.

```json
"enable_split_pane": true
```

--------------------------------

### Move and make executable binary

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/installation.md

Manually move the downloaded binary to your system's PATH and make it executable. Replace 'executable_name' with the actual binary name.

```bash
mv matcha /usr/local/bin/
chmod +x /usr/local/bin/executable_name
```

--------------------------------

### Manage OAuth Tokens for Outlook

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/setup-guides/outlook.md

Use these commands to manage OAuth tokens for your Outlook account with Matcha. Ensure you have Python 3 installed for OAuth2 functionality.

```bash
matcha oauth token your@outlook.com
```

```bash
matcha oauth revoke your@outlook.com
```

```bash
matcha oauth auth your@outlook.com
```

--------------------------------

### Trust Self-Signed Certificate on Linux (Debian/Ubuntu)

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/Features/SMIME.md

Install a self-signed certificate on Debian-based Linux systems. This involves copying the certificate and updating the CA certificate store.

```bash
sudo cp ~/.certs/cert.pem /usr/local/share/ca-certificates/my-smime.crt
sudo update-ca-certificates
```

--------------------------------

### Configure Specific Plugin

Source: https://github.com/floatpane/matcha/blob/master/plugins/README.md

Open the configuration file for a specific plugin in your default editor. Replace 'hello' with the name of the plugin.

```bash
matcha config hello          # opens ~/.config/matcha/plugins/hello.lua in $EDITOR
```

--------------------------------

### Systemd Service File for Matcha Daemon

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/Features/DAEMON.md

Configuration file for systemd to manage the Matcha daemon as a user service on Linux. Ensure the ExecStart path is correct for your installation.

```ini
[Unit]
Description=Matcha Email Daemon
After=network-online.target

[Service]
ExecStart=/usr/bin/matcha daemon run
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target
```

--------------------------------

### matcha.http(options) — HTTP Requests

Source: https://context7.com/floatpane/matcha/llms.txt

Enables plugins to make HTTP requests to external services. Supports GET and POST methods with custom headers and bodies.

```APIDOC
## matcha.http(options) — HTTP Requests

Allows plugins to make HTTP requests to external services.

### Parameters
- **options** (table) - A table containing request configuration:
  - **url** (string) - The URL to request.
  - **method** (string, optional) - The HTTP method (default: "GET").
  - **headers** (table, optional) - A table of request headers.
  - **body** (string, optional) - The request body for methods like POST.

### Returns
- **res** (table) - The response object, containing `status` (number) and `body` (string).
- **err** (string) - An error message if the request failed.

### Example
```lua
local matcha = require("matcha")

-- GET request
local res, err = matcha.http({ url = "https://api.example.com/status" })
if err then
  matcha.log("request failed: " .. err)
  return
end
matcha.log("HTTP " .. res.status .. ": " .. res.body)

-- POST with headers and JSON body
matcha.http({
  url     = "https://hooks.slack.com/services/T000/B000/xxxx",
  method  = "POST",
  headers = { ["Content-Type"] = "application/json" },
  body    = '{"text":"New email received"}',
})
```

### Limits
- 10s timeout
- 1 MB response cap
- HTTP/HTTPS only
```

--------------------------------

### Manage OAuth Tokens

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/setup-guides/gmail.md

Commands to manage your Gmail OAuth tokens. Use 'token' to get a fresh token, 'revoke' to delete stored tokens, and 'auth' to re-authorize.

```bash
# Get a fresh access token (auto-refreshes if expired)
matcha oauth token your@gmail.com
```

```bash
# Revoke and delete stored tokens
matcha oauth revoke your@gmail.com
```

```bash
# Re-authorize (e.g. after token expiry in testing mode)
matcha oauth auth your@gmail.com
```

--------------------------------

### Trust Self-Signed Certificate on Linux (Fedora/RHEL)

Source: https://github.com/floatpane/matcha/blob/master/docs/docs/Features/SMIME.md

Install a self-signed certificate on Fedora or RHEL-based Linux systems. This involves copying the certificate and updating the system's trust store.

```bash
sudo cp ~/.certs/cert.pem /etc/pki/ca-trust/source/anchors/my-smime.pem
sudo update-ca-trust
```