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:
$ 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 · reloadedWhen 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.
shop
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.
$ 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 sOne 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.
-
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 loginsigns you in. -
Make a signing key. The first time, Kiri asks you to pick a publisher name, which goes in every plugin’s
publisherkey 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 createTo publish from CI,
kiri plugin key create --for-ciprints a key to keep in the CI’s secrets asKIRI_PLUGIN_KEY. Each key can be removed from your account on its own. -
Publish from the plugin’s folder.
kiri plugin publishrunscheckandtest, builds, signs and uploads. It stops at the first failure.
$ 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