WINDOW PLACES
Menu items and commands
Every row in Kiri’s lists has a menu, opened with its ⋯ button or a right-click. Your plugin can add items to the menus of the kinds of row it names, and each item works on the one row it was opened on. Every item is also a command, kiri plugin NAME ACTION TARGET, so what you add to a menu works from a terminal, a script or CI too. What people see will be in the Kiri docs under Menu items and commands when 1.0 ships.
Pick the menus
Each item names the kind of row it’s on. There are six:
on |
Whose menu | Kiri’s own items, before yours |
|---|---|---|
container |
A container in Containers, and on its page | Open address, Ports…, Pause or Resume, Share with ›, Remove |
compose-service |
A service row inside a Compose project | Open address, Ports…, Pause or Resume, Show in compose file, Share with › |
compose-project |
A project row in Compose, and on the project’s page | Open project, Restart all, Deploy to ›, Remove project |
image |
An image in Images, and on its page | Run…, Pull, Scan with ›, Remove |
volume |
A volume in Volumes | Copy name, Remove |
build |
A build in Builds | Open build, Remove from history |
Networks, pods, Kubernetes services and USB devices take no plugin items. Kiri builds every menu in the same order: its own items, then its choices that plugins join (Share with ›, Deploy to ›, Scan with ›), a line, the plugins’ items with their marks in install order, a line, and Remove last. Your items are never where Remove is, and never look like Kiri’s own. To join Share with, Deploy to or Scan with, see Share, deploy, scan.
Add an item
List items under [adds] actions in kiri-plugin.toml. Each has a name your code knows it by, the kind it’s on, and the label people read:
[adds]
actions = [
{ name = "open", on = "compose-project", label = "Open in Coolify", label_key = "coolify.app" },
]
The install prompt shows one line for all your items: Add items to the menu of: Compose projects. An item can say when it shows:
| Key | Shows the item only | For |
|---|---|---|
when = "running", "stopped" or "any" |
when the container or service is in that state | containers, Compose services |
from = "ghcr.io/acme/" |
for images whose name starts with this | images |
label_key = "coolify.app" |
for rows that carry this label | containers, Compose projects |
Handle the click
Register a handler for each item’s name. It gets the row that was clicked and answers with plugin.say (a notice with your mark, up to 120 characters) or plugin.open (one of your pages, your tab on that row’s page, or a link):
import { plugin } from "@kiri/sdk";
plugin.action("open", async (target, kiri) => {
const app = await kiri.store.get(`app:${target.name}`);
if (!app) return plugin.say(`${target.name} isn't deployed to Coolify yet.`);
return plugin.open({ url: `https://coolify.example.com/project/${app}` });
});plugin.Action("open", func(t plugin.Target, k *plugin.Kiri) plugin.Result {
app, ok, err := k.Store.Get("app:" + t.Name)
if err != nil || !ok {
return plugin.Say(t.Name + " isn't deployed to Coolify yet.")
}
return plugin.Open(plugin.Where{URL: "https://coolify.example.com/project/" + string(app)})
})plugin::action("open", |target, kiri| async move {
match kiri.store().get(&format!("app:{}", target.name)).await {
Ok(Some(app)) => plugin::open(Where::Url(format!(
"https://coolify.example.com/project/{}", String::from_utf8_lossy(&app)))),
_ => plugin::say(format!("{} isn't deployed to Coolify yet.", target.name)),
}
});The handler gets exactly one thing: the row. Every target has its kind, name and id. A container or service also has its image, state and ports if your plugin may see containers ([needs] containers), and an image has its size and date if it may see images. You never get the whole list from a click, even when your permissions would let you read it. An action has 30 seconds to answer; after that Kiri shows “your plugin didn’t answer”.
Ask before it changes something
An item with ask makes Kiri ask before your handler is called. Kiri draws the question, names your plugin, and fills {name} with the row’s name. Your handler isn’t called unless the person presses the button. Acme’s release plugin asks before it promotes an image:
[adds]
actions = [
{ name = "promote-prod", on = "image", from = "ghcr.io/acme/", label = "Promote to prod", ask = "Promote {name} to prod?" },
]
Two items, then a submenu
Two of your items show at the top of a menu. With three or more for the same kind of row, they go in a submenu named after your plugin, so no plugin pushes the others out of sight. Each label is up to 32 characters.
Images
Commands
Add commands of your own under [adds] commands. They always sit under kiri plugin and your plugin’s name, so a plugin never takes a word Docker or Kiri uses, now or later. help is the line --help prints, and args names the arguments:
[adds]
commands = [
{ name = "apps", help = "List your Coolify apps and where they run" },
{ name = "servers", help = "List your Coolify servers and their chips" },
{ name = "logs", help = "Show an app's logs from Coolify", args = "APP" },
]
The prompt line is Add commands: kiri plugin coolify apps, servers, logs. The handler gets the arguments and an output, and returns an exit code (0 when it returns nothing):
plugin.command("apps", async (args, out, kiri) => {
const res = await kiri.http.fetch(`${await kiri.settings.get("server")}/api/v1/applications`, { secret: "token" });
for (const app of await res.json()) out.line(`${app.name} ${app.status} ${app.fqdn ?? ""}`);
});plugin.Command("apps", func(args []string, out *plugin.Output, k *plugin.Kiri) int {
server, _ := k.Settings.Get("server")
req, _ := http.NewRequest("GET", server.String()+"/api/v1/applications", nil)
resp, err := k.HTTP().Do(plugin.WithSecret(req, "token"))
if err != nil {
out.Error(err.Error())
return 1
}
var apps []struct{ Name, Status, FQDN string }
json.NewDecoder(resp.Body).Decode(&apps)
for _, a := range apps {
out.Line(a.Name + " " + a.Status + " " + a.FQDN)
}
return 0
})out.table prints columns, out.json prints a value, and out.error writes to standard error. Every command also takes --json, which turns table and line into JSON for scripts.
Every menu item is a command too
kiri plugin NAME ACTION TARGET runs any of your menu items from a terminal. An item with ask asks there too, and --yes answers for a script. kiri plugin NAME --help lists both:
$ kiri plugin coolify --help
Coolify 1.0.0, by kiri
Commands:
apps List your Coolify apps and where they run
servers List your Coolify servers and their chips
logs APP Show an app's logs from Coolify
Menu items:
open PROJECT Open in Coolify
$ kiri plugin acme-release promote-prod ghcr.io/acme/shop-api:1.4.0 --yes
✓ Acme release: promotedA command runs with the same pass as everything else your plugin does. On Windows it runs where Kiri’s engine runs, in WSL, so it behaves the same as on a Mac or Linux.
These words belong to kiri plugin itself, so no plugin can take them as its name: search, install, ls, show, set, update, enable, disable, rm, activity, logs, hide, unhide, request, new, dev, check, test, build, key and publish. kiri plugin check refuses a manifest that uses one.
© 2026 Kiri · The SDK is open source under the Apache License 2.0 · Docs · runkiri.com