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.

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.

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:

{
  "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.

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.

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.

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 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.