# Share and install plugins

Publish a plugin as a Git repository or in the catalog, install one from someone else, and check its permissions before you enable it.

A plugin is a folder, so you share it through a Git repository. Anyone can install it with `loam plugin install`. An install never enables the plugin: you read its permissions first, then enable it yourself.

## Publish a plugin

Make the plugin folder the root of a Git repository, and push it. Write a README that says what the plugin does and which permissions it asks for.

```bash
cd ~/Notes/.loam/plugins/word-count
git init
git add .
git commit -m "Word count plugin"
git remote add origin <git url>
git push -u origin HEAD
```

The compiled library stays in `.loam/cache/`, outside the plugin folder, so it is not shared. Each person builds the plugin on their own Mac.

## Install a plugin

Run `loam plugin install` with the Git URL. Loam clones the repository, checks `plugin.json`, builds the plugin, and puts it in `.loam/plugins/<id>/`. It installs the highest release tag, or the default branch when there are no tags. The plugin stays off. In the app, Settings > Plugins has a field that installs from a Git URL too.

```bash
loam --vault ~/Notes plugin install <git url>
```

It prints the id, the folder, the version, the permissions the plugin declares, and whether it built. This is the output for a plugin folder installed from disk, with the build log shortened:

```text
{
  "built" : true,
  "id" : "hello",
  "log" : "<the Swift build output>",
  "path" : "/Users/you/Notes/.loam/plugins/hello",
  "permissions" : [
    "vault.read"
  ],
  "version" : "0.1.0"
}
```

Install refuses a folder without a valid `plugin.json`, and an id that is already installed or built in.

## Check the permissions, then enable

Permissions are declared, not enforced. A plugin runs inside the app with the app access, and Loam does not check its code against the list. Read the list, and enable only plugins you trust.

| Permission | What it means | Risk |
| --- | --- | --- |
| `vault.read` | Read your notes | low |
| `ui` | Add views, panels and commands to the window | low |
| `vault.write` | Change your notes | medium |
| `disk.read` | Read files outside this vault | medium |
| `local-service` | Talk to programs running on your Mac, over a local socket or port | medium |
| `audio` | Record or play sound | medium |
| `clipboard` | Read and change the clipboard | medium |
| `network` | Talk to servers on the internet | high |
| `shell` | Run programs on your Mac | high |

Loam shows a permission it does not know as unknown, and treats it as high risk.

Enable the plugin when you agree: `loam --vault ~/Notes plugin enable <id>`. In the app, Settings > Plugins shows the permissions in a sheet before it turns the plugin on. `loam plugin enable` does not show them, so read the permissions that `plugin install` printed, or `plugin.json`, first.

Enabling records your approval on this Mac, in `~/Library/Application Support/Loam/trusted-plugins.json`, not in the vault. A copy of the vault at another path does not load the plugin until you enable it there.

## Release a new version

Bump `version` in `plugin.json`, commit, then tag the commit. Installs take the highest tag. Without tags, they follow the default branch. Set `minSDK` in `plugin.json` when the plugin needs a newer app: `loam guide` prints the app's plugin SDK version.

```bash
git tag v1.2.0
git push --tags
```

## Update and roll back

These commands work on plugins installed from git or from the catalog. An update that asks for a new permission disables the plugin until you enable it again.

```bash
loam --vault ~/Notes plugin outdated
loam --vault ~/Notes plugin update <id>
loam --vault ~/Notes plugin rollback <id>
```

`plugin outdated` lists the plugins that have a newer version. `plugin update --all` updates every plugin, and `plugin rollback` goes back to the version the last update replaced.

## The public catalog

`loam plugin catalog [query]` lists the plugins of the public catalog, and `loam plugin install --catalog <id>` installs one. Settings > Plugins shows the same list with an Install button. The catalog pins each plugin version to a commit, and the install refuses any other commit.

To list your plugin, open a pull request on [the catalog repository](https://github.com/Azilone/loam-community) that adds its repository, tag and commit to `index.json`.

## Turn off or remove a plugin

`loam plugin disable <id>` turns a plugin off. `loam plugin remove <id>` moves its folder to `.trash/plugins/`, deletes its compiled cache, and turns it off.

> **Tip:** For AI agents: `loam guide share` covers installing and sharing. `loam plugin list` shows the source, the state and any load error of each plugin.