# Plugin format (/reference/plugin-format)

What a plugin's source folder, its bundle and a release's index of bundles hold, and the commands that check and build them.



A plugin is written as a **source folder**, built into a **bundle** that installs it, and listed with other bundles in a release's **index**. [Install a plugin](/use/install-a-plugin) installs one. The CLI checks and builds them with no server.

## Source folder [#source-folder]

```text
tickets/
  plugin.json
  types/
    common.ticket.json
    common.ticket.md
  edge-types/
    blocks.json
```

* **`plugin.json`** holds the identity fields below, and an optional `connector` object. It names no `version`: a release stamps one from its tag, and `marfa plugins check` refuses a `version` here.
* **`types/<id>.json`** holds a type definition, as [Type definition](/catalog/type-definition) describes. `<id>.md` beside it is the type's guidance, at most 1,000 characters.
* **`edge-types/<id>.json`** holds an edge type, as [Register an edge type](/reference/api/edge-types/registerEdgeType) takes it.
* **A file not named after its `id`** is refused `file_name_mismatch`, in the check, the bundle and the install alike.

A type sits under `common` or a root of the plugin's own. One under `core`, `system`, `marfa`, `app` or `user` is refused `403 forbidden`. A type's parent outside the plugin is one Marfa ships, a `common` type, or a type the installer may write.

## Identity fields [#identity-fields]

`plugin.json` and the bundle hold each of these, and the bundle carries them as they are:

| Field | Rule |
| - | - |
| `name` | Lowercase words and numbers joined by hyphens, starting with a word, at most 64 characters, such as `tickets`. |
| `title` | The name people see, at most 100 characters. |
| `description` | What the plugin adds, in a sentence, at most 300 characters. |
| `mark` | An icon ID, as a type's [display hints](/catalog/type-definition#display-hints) take one, such as `lucide:ticket`. |
| `maker` | Who made the plugin, at most 64 characters. |
| `marfa` | The oldest Marfa release it works with, such as `0.0.92`. A later release than the server's is refused `409 plugin_needs_newer_server`. |

## Bundle [#bundle]

`marfa plugins bundle <folder> --version 1.2.0` writes `<name>.plugin.json` in the current folder, or the one `--output` names. The bundle is one JSON object with `format` set to `1`, the identity fields, and:

| Field | Holds |
| - | - |
| `version` | The plugin's version, such as `1.2.0`; `0.0.0` without `--version`. |
| `types` | Each type definition, with its `.md` file as `guidance`. |
| `edge_types` | Each edge type. |
| `connector` | The [connector object](#connector) from `plugin.json`, if it names one. |

A bundle with any other field is refused `400 validation_error`. **The instance records the SHA-256 of the bundle's bytes** as the plugin's `fingerprint`, so build a release once and install the same file everywhere. [Install a plugin](/reference/api/plugins/installPlugin) lists every answer.

## Connector [#connector]

The `connector` object describes the connector the plugin brings, which a [connector host](/use/run-a-plugin-connector) runs. Installing a plugin with one needs `connectors.manage`, and a field it doesn't define is refused `400 validation_error`, naming its path.

| Field | Rule |
| - | - |
| `source` | Required. The source its key holds, 1 to 200 characters with no whitespace at either end, not `.` or `..`, and not starting with `oauth:`, `restored:` or `connector-host:`. One source belongs to one plugin: one another plugin or a registration holds is refused `409 connector_source_held`, and a newer version must keep it. |
| `source_name` | Required. The source's name people see, at most 100 characters. |
| `source_mark` | An icon ID for the source. |
| `kinds` | Required, at least one. Each kind of record it brings: `name` (lowercase letters, digits and underscores), `type` (one of the bundle's types), `direction` (`in`, `out` or `both`), and an optional `default_mapping` that sets only `tier`, `status_overrides` and `fields` on that type, as [a mapping](/use/map-a-connector) does. |
| `edge_types` | The [edge types](/build/edges#edge-types) it writes, each named once: the bundle's own, or ones Marfa ships whose ends aren't `system` types, such as `attached-to`. Any other is refused `400 validation_error`. Its key writes each, and a newer version may drop one. |
| `settings` | Each setting it reads: `name`, `label`, `kind` (`text`, `number`, `boolean` or `choice`), `required`, and optionally `secret` (text only), `default` (of its kind, never on a secret) and `choices` (a `choice` setting only). |
| `sign_in` | For a connector that signs in: `kind` `oauth2`, `provider` `google`, `scopes`, and the settings that hold the client ID, the client secret and the token, the last two secret. |
| `runs` | Required. `{ "on": "host" }`. |

## Release index [#release-index]

`marfa plugins index <folder>` writes `plugins.json` beside the bundles in a folder. `marfa plugins install <name>` reads it from a release to find a bundle and check its bytes. WithMarfa publishes its plugins as a GitHub Release of [withmarfa/plugins](https://github.com/withmarfa/plugins/releases) for each version, holding every plugin's bundle, `plugins.json` and `checksums.txt`, with build provenance:

| Field | Holds |
| - | - |
| `format` | `1`. |
| `plugins` | One entry for each bundle: its identity fields, `version`, `has_connector`, `bundle` (the file name) and `sha256`. |

## Check a folder [#check-a-folder]

`marfa plugins check <folder>` judges a folder as installing it would, with no server: `plugin.json`, each type as [`marfa types check`](/build/check-type-definitions) judges one but with `common` types taken and the roots above refused, and each edge type against Marfa's own and the folder's. It exits `1` with each problem and its path.

The rules behind this page are in the [plugins](https://github.com/withmarfa/marfa/blob/main/conformance/spec/plugins.md) chapter of the contract, and the [CLI chapter](https://github.com/withmarfa/marfa/blob/main/conformance/spec/cli.md#plugins) holds the commands'.
