Kiri Developers

PUBLISH

Test and publish a plugin

A plugin goes through four commands on its way to other people. kiri plugin dev runs it while you write it. kiri plugin check and kiri plugin test tell you it’s right. kiri plugin publish builds it, signs it and sends it to the marketplace. Each one runs in Kiri, on your computer or in CI, and none of them needs anything else installed.

Run it while you write it

kiri plugin dev builds the plugin in the folder, shows you its install prompt once, and installs it for you alone, marked From a folder · not signed. Then it watches the folder: each time you save, it builds the plugin again and reloads it, in under a second for most WebAssembly plugins. Kiri’s window and every docker command use the new build straight away.

It prints the plugin’s log and its activity as they happen, refused calls included, so a missing permission shows the moment the code asks for it:

zsh: kiri plugin dev
$ kiri plugin dev
  … the install prompt, once …
  Install? [y/N] y
  ✓ built in 0.6 s · WebAssembly 1.1 MB
  ✓ coolify loaded. Watching src/ and kiri-plugin.toml. Ctrl+C stops watching.
  14:20:03  ✓  coolify  hello: deploy coolify, action open, tab compose-project, section Coolify
  14:20:11  ✓  coolify  page Apps: 4 rows
  14:20:11     coolify  log: fetched 4 apps from coolify.example.com in 182 ms
  14:20:15  ✗  coolify  column images (needs: Add a column to: Images)
  ↻ src/main.ts changed
  ✓ built in 0.4 s · reloaded

When a save makes the plugin ask for more, dev shows only the new lines under It now also asks to: and asks again, as an update from the marketplace would. A line you refuse stays refused until you stop dev. Ctrl+C stops watching; the plugin stays installed from the folder until you kiri plugin rm it.

See the places it uses

kiri plugin dev --outline, or Outline places on the plugin’s page in the Plugins view, draws a dashed line round everything the plugin puts in the window, with the place’s name and how much of its limit the plugin uses. A note at 23 of 24 characters is about to be cut short in German.

Kiri
DockerContainersComposeImagesKiriPluginsSettingsCoolifyAppsServersDeploys

shop

Coolifyprod · deployed 2 h agoC · fact · 22 of 48
StructureServicesCompose fileLogsDeploys Coolify
webrunningC · tab · 7 of 16
apirunning
dbrunning
Kiri 1.0.0 prod: deploying · A · 17 of 24VM running3 of 3 running
Outline places, while kiri plugin dev runs. Each place the plugin uses gets a dashed line, its letter and its limit: here the Coolify tab on a Compose project, the line it adds to the page's head, and its note in the status bar.

Check it, then test it

kiri plugin check

kiri plugin check reads kiri-plugin.toml and the built code together, without running anything. It finds what would stop the plugin installing or starting: a handler the file doesn’t list, a key with nothing behind it, a label over its limit, a secret with no for, a host written as a wildcard domain, a translation file missing words. kiri-plugin.toml shows its output. It exits with 1 when there’s a problem, so it fits in CI.

kiri plugin test

kiri plugin test runs the plugin against jobs you write down, and compares what it does with what you expect. Each case runs in a fresh box with the same pass the plugin gets when it’s installed, so a call the file doesn’t allow is refused in a test too. Tests never reach the internet or your real containers: the websites, containers, images and settings are fakes you describe.

Test files are TOML, in tests/, and the same whatever language the plugin is in:

# tests/apps.toml
[fake]
settings = { server = "https://coolify.test", token = "test-token" }
containers = [{ name = "shop-web-1", image = "shop-web", state = "running", ports = [8080] }]
images = [{ ref = "nginx:1.27", size = "48MB" }]

[[fake.site]]
url = "https://coolify.test/api/v1/applications"
status = 200
body = '[{"uuid": "a1", "name": "shop", "status": "running"}]'

[[case]]
name = "lists apps"
job = { command = "apps" }
expect = { exit = 0, output = "shop", sent = [{ url = "https://coolify.test/api/v1/applications", header = "Authorization: Bearer test-token" }] }

[[case]]
name = "the tab shows the app"
job = { tab = "compose-project", target = "shop" }
expect = { blocks = ["facts", "buttons"], text = "running" }

[[case]]
name = "a server that's down says so"
job = { page = "Apps" }
fake.site = [{ url = "https://coolify.test/api/v1/applications", status = 502 }]
expect = { blocks = ["notice"], text = "Coolify didn't answer" }
In a case What it is
job What Kiri sends. One of check (with image), share, deploy, scan (with image), action (with target), command (with args), tab, fact, column, page, settings.check or event. Fields as in the Plugin API.
fake Changes to the file’s [fake] for this case only.
expect.verdict, expect.reason A check’s answer, and words its reason must contain.
expect.status, expect.notice What the plugin left in its status bar note, and any notice it showed. "" means none.
expect.output, expect.exit A command’s output must contain these words; its exit code.
expect.blocks, expect.text The kinds of blocks a tab or page drew, in order, and words they must contain.
expect.share, expect.deploy The states a share or deploy went through, such as ["live", "ended"].
expect.sent Requests the plugin made, with the header Kiri added for a secret. The plugin’s code never sees test-token; the test checks that Kiri sent it, to the right place only.
expect.refused Permission lines you expect to be refused. A refused call that isn’t listed fails the case.

A request to a site the test doesn’t fake fails with UnavailableError, and the test says which address it was.

zsh
$ kiri plugin test
  coolify 1.0.0 · 3 files · 11 cases
  ✓ apps.toml       3 passed
  ✓ deploy.toml     5 passed
  ✗ settings.toml   2 passed, 1 failed

  ✗ settings.toml › a wrong token says so
    expected the settings check to say "token", got:
      ok: false, "Coolify didn't answer"
    sent: GET https://coolify.test/api/v1/version (401)

  10 passed, 1 failed in 1.4 s

One build, every system

A WebAssembly plugin always runs in Kiri’s Linux side, so it behaves the same on a Mac, on Windows and on Linux. There’s no key for the system in kiri-plugin.toml, and no call that says which one it is: test once and it holds on all three. A container plugin is a Linux container on every system too. kiri plugin build builds its image for both arm64 and amd64, and publishing refuses an image with only one.

Build and sign it

kiri plugin build puts the plugin in an OCI image: the WebAssembly or the container image, kiri-plugin.toml, the lang folder and the listing files. Kiri installs plugins from such images by digest, so what’s installed is exactly what you built. --tag names the image if you want to push it to a registry of your own; Your first plugin does that.

To publish, you need a publisher account and a signing key.

  1. Sign in to your Kiri account. It’s the account Kiri Share uses, so if you share, you’re already signed in; if not, kiri share login signs you in.

  2. Make a signing key. The first time, Kiri asks you to pick a publisher name, which goes in every plugin’s publisher key and can’t be changed once a plugin is listed. Kiri keeps the private half of the key in your system’s keychain and adds the public half to your publisher account:

    kiri plugin key create

    To publish from CI, kiri plugin key create --for-ci prints a key to keep in the CI’s secrets as KIRI_PLUGIN_KEY. Each key can be removed from your account on its own.

  3. Publish from the plugin’s folder. kiri plugin publish runs check and test, builds, signs and uploads. It stops at the first failure.

zsh
$ kiri plugin publish
  coolify 1.1.0 by kiri
  ✓ check
  ✓ test: 11 passed
  ✓ built sha256:4e0a91c7d2b8… · WebAssembly 1.1 MB
  ✓ signed with key "laptop" (added 3 Nov 2026)
  ✓ uploaded

  Automatic checks
    ✓ signature matches the publisher
    ✓ files: nothing outside the plugin
    ✓ scanned: no known problems
    ✓ started in a box and said hello
    ✓ permissions: the same as 1.0.0

  Listed. People on 1.0.0 get it at their next daily check, without being asked.

After you publish

Review. Every upload goes through five automatic checks: the signature, the files, the permissions against the version before, a scan, and a test start in a box. A person looks as well the first time a plugin is listed, and whenever an update asks for more. An upload that passes and asks for nothing new is listed in minutes. Review has what each check looks for, what a person looks at, and what ranks mean.

The listing and updates. The marketplace builds the listing from the plugin’s own files, with a listing/ folder for the longer description, logo, screenshots and What’s new. People get a new version at their next daily check: quietly when it asks for the same or less, after a yes when it asks for more. A version you got wrong can be withdrawn with kiri plugin publish --withdraw. The marketplace has the details.

© 2026 Kiri · The SDK is open source under the Apache License 2.0 · Docs · runkiri.com