1# Matcha Plugin Marketplace
 2
 3This directory contains the official Matcha plugin collection and the plugin registry that powers the marketplace.
 4
 5## Installing Plugins
 6
 7### From the TUI Marketplace
 8
 9Browse and install plugins interactively:
10
11```bash
12matcha marketplace
13```
14
15Use `j/k` or arrow keys to navigate, `Enter` to install, and `q` to quit. You can also access the marketplace from Matcha's main menu.
16
17### From a URL
18
19```bash
20matcha install https://raw.githubusercontent.com/floatpane/matcha/master/plugins/hello.lua
21```
22
23### From a Local File
24
25```bash
26matcha install path/to/my_plugin.lua
27```
28
29### Using curl
30
31```bash
32curl -sL https://raw.githubusercontent.com/floatpane/matcha/master/plugins/hello.lua \
33  -o ~/.config/matcha/plugins/hello.lua
34```
35
36Plugins are installed to `~/.config/matcha/plugins/` and loaded automatically on next startup.
37
38## Configuring Plugins
39
40Open a plugin file in your editor to configure it:
41
42```bash
43matcha config hello          # opens ~/.config/matcha/plugins/hello.lua in $EDITOR
44matcha config                # opens ~/.config/matcha/config.json in $EDITOR
45```
46
47## Submitting Your Plugin
48
49Anyone can add their plugin to the marketplace by submitting a PR to this repository.
50
51### Steps
52
531. **Write your plugin** as a `.lua` file following the [Plugin API docs](https://docs.matcha.email/Features/Plugins).
54
552. **Add an entry to `registry.json`** in this directory:
56
57   ```json
58   {
59     "name": "my_plugin",
60     "title": "My Plugin",
61     "description": "A short description of what your plugin does.",
62     "file": "my_plugin.lua",
63     "url": "https://raw.githubusercontent.com/YOUR_USER/YOUR_REPO/main/my_plugin.lua"
64   }
65   ```
66
673. **Submit a pull request** to [floatpane/matcha](https://github.com/floatpane/matcha).
68
69### Registry Fields
70
71| Field         | Required | Description                                                                 |
72|---------------|----------|-----------------------------------------------------------------------------|
73| `name`        | yes      | Unique identifier (lowercase, underscores). Must match the filename without `.lua`. |
74| `title`       | yes      | Human-readable name shown in the marketplace.                               |
75| `description` | yes      | One or two sentences describing what the plugin does.                       |
76| `file`        | yes      | The `.lua` filename that gets saved to the user's plugins directory.        |
77| `url`         | no       | Direct download URL for the plugin file. If omitted, defaults to this repo's `plugins/` directory. |
78
79### Guidelines
80
81- Keep plugins focused — one plugin, one purpose.
82- Include a comment header in your `.lua` file with a description:
83  ```lua
84  -- my_plugin.lua
85  -- A short description of what this plugin does.
86  ```
87- Test your plugin with the latest version of Matcha before submitting.
88- Do not include external dependencies — plugins run in a sandboxed Lua environment.
89- The `url` field should point to a raw file URL that stays stable (use a tagged release or `main` branch).
90
91## Browsing Online
92
93Visit the [Plugin Marketplace](https://docs.matcha.email/marketplace) on the Matcha documentation site to browse all available plugins with one-line install commands.