Kiri Developers

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):

No Python version · showing TypeScript
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?" },
]
Kiri
AR Acme release asksPromote ghcr.io/acme/shop-api:1.4.0 to prod?
CancelPromote to prod
The question Kiri draws from ask. It names the plugin and the image. The plugin's promote-prod handler runs only after Promote to prod is pressed, or with --yes from a terminal.

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.

Kiri

Images

ghcr.io/acme/shop-api:1.4.0148 MB⋯
Run…PullScan with ›
AR Acme release ›
Remove
Promote to stagingPromote to prodShow release notes
Acme release adds three items to images, so Kiri puts them in a submenu under the plugin's name and mark, after Kiri's Scan with › and before Remove.

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):

No Rust version · showing TypeScriptNo Python version · showing TypeScript
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:

zsh
$ 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: promoted

A 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