Share a plugin

Whoever installs your plugin approves it on their own machine, whichever way it reaches them. Sharing a plugin never shares an approval.

Through git

Push the plugin’s folder to a public repository. Anyone can install it from there:

gr plugin install github.com/you/greeter
gr plugin install github.com/you/plugins/greeter        # a folder inside the repository
gr plugin install github.com/you/greeter@v0.2.0         # a branch, tag or commit
gr plugin install https://git.example.com/you/greeter.git

A link to the repository or a folder on GitHub, GitLab, Codeberg or Bitbucket works too, as copied from the browser. Graphide fetches public repositories over HTTPS, up to 64 MiB, and reads the files without checking anything out, so nothing in the repository runs while it is fetched.

An install records the commit it came from. Without @, gr plugin update follows the repository’s default branch; with one, it stays at what you named. Each update is a new version, and waits for approval.

For a team

To give everyone working in a repository the same plugins, list them in that repository’s .graphide/plugins.toml, each pinned to the exact contents you reviewed:

[plugins.greeter]
source = "github.com/you/greeter@v0.2.0"
hash = "6f5b8e0a0cb9d575bfaa41ecdeb715b1ee02bdae239bc104dcf73afe40700f20"

gr plugin hash <folder> prints a folder’s hash, offline. Commit the file. Each teammate then runs, in the repository:

gr plugin install --from-repo

Every plugin is fetched from its source and checked against its hash. One whose contents differ is refused. Each person still approves each plugin for themselves, and the plugins run in that repository only. Until then, gr plugin list --root . shows them as suggested.

Your own list works the same way without hashes: name sources in [plugins.<name>] of your config.toml and run gr plugin install --from-config on a new machine.

In the plugin store

The store lists open-source plugins. Anyone can find and install one by its name:

gr plugin install store:greeter
gr plugin install store:greeter@0.2.0

To publish, the plugin’s folder needs one of these licences in a LICENSE, LICENCE or COPYING file at its root: MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, MPL-2.0, LGPL-2.1-only, LGPL-3.0-only, GPL-2.0-only, GPL-3.0-only, AGPL-3.0-only or Unlicense. You also need to be signed in.

gr plugin publish ./greeter                    # or a repository link

The first time, you choose a public publisher handle, which accepts the Publisher Terms. Then gr plugin publish makes a draft, shows you the same review a person sees before approving, and asks you to type yes on your terminal. A draft you leave waits; confirm it later with gr plugin publish --confirm greeter@0.1.0, or drop it with gr plugin unpublish greeter@0.1.0.

• A plugin’s first version, and any version that asks for something the last listed one did not, waits for review by Graphide’s staff. A version that asks for nothing new is listed when you confirm it.
• Each version must be higher than every version you confirmed before.
• The name is yours once you publish it.
• Only a person confirms or withdraws a version, on their own terminal; the daemon refuses one that comes from inside an agent.

If a listed version turns out to be unsafe, staff can pull it. Graphide checks the store when the daemon starts and once a day: a version that was pulled is switched off on every machine that has it, and gr plugin list and the app’s Plugins page say why. You may switch it on again.

Update and roll back

gr plugin update greeter      # fetch the newest version; it waits for approval
gr plugin rollback greeter    # put back the version you approved before

The same daily check finds updates to plugins from the store, and gr plugin list names them.

Bring in a VS Code or Zed extension

Themes, icon sets, languages and snippets from an editor extension can become a plugin:

gr plugin import open-vsx:dracula-theme.theme-dracula
gr plugin import zed:catppuccin
gr plugin import ./some-extension.vsix

open-vsx: fetches from Open VSX, and zed: from Zed’s registry. A .vsix, a Zed extension’s .tar.gz or an unpacked extension’s folder works too. The import keeps only data: no script, native program or other WebAssembly is ever copied, and it lists what did not carry over. The plugin it writes waits for your approval like any other. Imported themes then appear among your theme choices by their names.