# Install a plugin (/use/install-a-plugin)

Add a plugin's shared types, with the guidance agents read and the edge types they use, to your instance by name or from a file, update it, and remove it.



A **plugin** adds types that every app and agent can share, such as tickets, under `common`. Each type comes with guidance that tells an agent how to fill it, and the plugin brings the edge types they use and, for some, a connector. Only a plugin adds a `common` type. **You need** the CLI signed in to your instance, as the [Quickstart](/quickstart) leaves you.

## Install by name [#install-by-name]

```bash
marfa plugins install tickets
```

Output:

```text
installed tickets 0.0.13 with 5 types
```

The CLI reads the plugin from the latest release of [withmarfa/plugins](https://github.com/withmarfa/plugins). The release's `plugins.json` lists each plugin with the SHA-256 of its bundle, and **the CLI checks the bundle before it sends it** to your instance, which fetches nothing itself. A bundle that doesn't match, or a release the CLI can't read, exits `3` with `plugins_unreachable` and installs nothing. `MARFA_PLUGINS_URL` names another release address.

**Installing is one write:** every type and edge type of the plugin goes in, or none does. Each type then names its plugin: `marfa types get common.ticket` answers `provenance.origin` as `plugin`, and `provenance.plugin` with the name and version.

## Install from a file or a folder [#install-from-a-file-or-a-folder]

A bundle, `<name>.plugin.json`, installs as it is. A plugin's source folder is built into one first, and the CLI prints the SHA-256 of what it built:

```bash
marfa plugins install ./tickets.plugin.json
marfa plugins install ./tickets --version 0.0.13
```

A folder installs at `0.0.0` without `--version`. [Plugin format](/reference/plugin-format) says what a folder and a bundle hold.

## Update a plugin [#update-a-plugin]

Install it again. The same version answers `tickets 0.0.13 is already installed` and changes nothing. **A newer version may only add**, such as fields, status words, enum values and types:

| Answer | Why |
| - | - |
| `409 plugin_narrows` | The version would remove or narrow something; `details.changes` names each change. |
| `409 plugin_version_older` | The version is older than the one installed. |
| `409 plugin_child_conflict` | The version gives a type a field that one of your own types beneath it declares differently. Change your type, then install again. |

## What installing needs [#what-installing-needs]

Your own sign-in can install any plugin. A key needs `schema.write`, write on each of the plugin's types and edge types, and `connectors.manage` when the plugin has a connector. **Only you write guidance**, so an app's sign-in, or a key an app made, is refused `403 forbidden` for a plugin whose types carry it. A first install is also refused:

| Answer | Why |
| - | - |
| `409 plugin_needs_newer_server` | The plugin needs a later Marfa: [upgrade](/run/upgrade) first. |
| `409 type_exists` | The instance already holds one of the plugin's types, and the plugin didn't install it. |
| `409 connector_source_held` | Another plugin's connector, a connector you run yourself or a key already holds the source the plugin's connector names. `details` names which. |
| `403 forbidden` | A type sits under `core`, `system`, `marfa`, `app` or `user`, which `details.namespace` names. |

**A plugin's connector runs on a connector host** you link to your instance: [Run a plugin's connector](/use/run-a-plugin-connector).

## List and remove plugins [#list-and-remove-plugins]

`marfa plugins list` shows every plugin installed, and `marfa plugins get tickets` one, with its types and the fingerprint of the bundle it came from.

```bash
marfa plugins remove tickets
```

Output:

```text
removed tickets; its 5 types and their items stay
```

**Removing a plugin deletes no item.** Its types, edge types and items stay, and keep naming the plugin; a connector it brought stops, and its settings and mapping go ([Remove a host or a plugin](/use/run-a-plugin-connector#remove-a-host-or-a-plugin)). [Change a type](/build/change-a-type) deletes a type you no longer want. Exports and backups carry the plugins installed.

The rules behind this page are in the [plugins](https://github.com/withmarfa/marfa/blob/main/conformance/spec/plugins.md) chapter of the contract.
