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 installs one. The CLI checks and builds them with no server.
Source folder
tickets/
plugin.json
types/
common.ticket.json
common.ticket.md
edge-types/
blocks.jsonplugin.jsonholds the identity fields below, and an optionalconnectorobject. It names noversion: a release stamps one from its tag, andmarfa plugins checkrefuses aversionhere.types/<id>.jsonholds a type definition, as Type definition describes.<id>.mdbeside it is the type's guidance, at most 1,000 characters.edge-types/<id>.jsonholds an edge type, as Register an edge type takes it.- A file not named after its
idis refusedfile_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
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 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
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 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 lists every answer.
Connector
The connector object describes the connector the plugin brings, which a connector host 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 does. |
edge_types | The 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
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 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
marfa plugins check <folder> judges a folder as installing it would, with no server: plugin.json, each type as marfa types check 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 chapter of the contract, and the CLI chapter holds the commands'.