Kiri Developers

WINDOW PLACES

Tabs, pages and columns

When your plugin has more to show than a note, it gets room in four places, each asked for on its own: a tab on a page, a line at the top of a page, a column in a list, and a page or a section of its own in the sidebar. In every one you send data, a list of blocks or a cell, and Kiri draws it in the window’s own look. You never send HTML. What people see will be in the Kiri docs under Tabs, pages and columns when 1.0 ships.

A tab, from handler to windowKiri’s windowopens the Coolify tabKiri drawsits own partsKiriasks, then checksthe blocksthe plugin’s boxplugin.tab(“compose-project”)→ facts, buttonsopentarget: shopblocksdrawkiri.refresh(“tab”)
How a tab gets drawn. When someone opens the tab, Kiri calls the plugin's tab handler with the one project on screen. The handler answers with blocks, plain data, and Kiri draws them with its own parts, theme and language direction. A refresh from the plugin asks Kiri to call it again.

A tab, and a line at the top

Add one tab to each kind of page you name. It goes after Kiri’s own tabs:

on Page Kiri’s tabs, then yours
container A container’s page Overview, Logs, Terminal, Files
compose-project A Compose project’s page Structure, Services, Compose file, Logs, Deploys
image An image’s page Layers, Security
build A build’s page Steps, Layers, Security

You can also add one line to the facts at the top of those pages, such as “Deployed · prod, 2 min ago” beside a project’s state. Coolify does both:

[window]
tabs = [{ on = "compose-project", label = "Coolify" }]
facts = ["compose-project"]

The prompt shows Add a tab to: Compose projects and Add a line to the top of: Compose projects. Kiri asks for the tab’s blocks when it’s opened, and again when you call kiri.refresh("tab"). Each handler gets the page’s one thing, as a menu item does:

No Rust version · showing TypeScriptNo Python version · showing TypeScript
plugin.tab("compose-project", async (project, kiri) => {
  const d = await kiri.store.get(`deploy:${project.name}`);
  if (!d) return [{ empty: { title: "Not deployed yet", text: "Use Deploy to › Coolify on this project." } }];
  return [
    { facts: [["Deployed to", `${d.target} · ${d.server}`], ["Address", d.url], ["Last deploy", d.when]] },
    { buttons: [{ label: "Open in Coolify", url: d.link }, { label: "See deploys", page: "Deploys" }] },
  ];
});

plugin.fact("compose-project", async (project, kiri) => {
  const d = await kiri.store.get(`deploy:${project.name}`);
  return d ? { label: "Deployed", value: `${d.target}, ${d.ago}` } : null;
});
plugin.Tab("compose-project", func(p plugin.Target, k *plugin.Kiri) ([]plugin.Block, error) {
	d, ok, err := loadDeploy(k, p.Name) // your own code, reading k.Store
	if err != nil || !ok {
		return []plugin.Block{plugin.Empty("Not deployed yet", "Use Deploy to › Coolify on this project.")}, err
	}
	return []plugin.Block{
		plugin.Facts([][2]string{{"Deployed to", d.Target + " · " + d.Server}, {"Address", d.URL}, {"Last deploy", d.When}}),
		plugin.Buttons(plugin.Button{Label: "Open in Coolify", URL: d.Link}, plugin.Button{Label: "See deploys", Page: "Deploys"}),
	}, nil
})

plugin.Fact("compose-project", func(p plugin.Target, k *plugin.Kiri) (*plugin.FactLine, error) {
	d, ok, err := loadDeploy(k, p.Name)
	if err != nil || !ok {
		return nil, err
	}
	return &plugin.FactLine{Label: "Deployed", Value: d.Target + ", " + d.Ago}, nil
})

A tab’s label is up to 16 characters: one tab per plugin on each kind of page, and one line at the top. Return nothing, null or an empty list, and your tab or line isn’t drawn on that page.

Kiri

Compose › shop

3 of 3 running~/code/shop Deployed · prod, 2 min ago
StructureServicesCompose fileLogsDeploys Coolify
Deployed toprod · coolify.example.com
Last deployfinished 2 minutes ago
Open in CoolifySee deploys
What Kiri draws from the handlers above: Coolify's tab after Kiri's five, and its line at the top of the page. The names and values, the address and the buttons are Kiri's own parts.

A column in a list

Add one column to each list you name: containers, compose, images or volumes. The heading is up to 12 characters. Each cell is a badge Kiri draws: up to 12 characters and a tone, plain, good, warning or bad.

[window]
columns = [{ on = "images", label = "Trivy" }]

The prompt line is Add a column to: Images. Kiri asks for the cells of the rows on screen when it draws the list, and again after kiri.refresh("column"). Give each cell a sort value, so the column sorts by what matters rather than by its text:

No Go version · showing TypeScriptNo Python version · showing TypeScript
plugin.column("images", async (refs, kiri) => {
  const cells = {};
  for (const ref of refs) {
    const r = await kiri.store.get(`scan:${ref}`);
    cells[ref] = !r ? { text: "not scanned", tone: "plain", sort: -1 }
      : r.critical ? { text: `${r.critical} critical`, tone: "bad", sort: 1000 + r.critical }
      : r.high ? { text: `${r.high} high`, tone: "warning", sort: r.high }
      : { text: "clean", tone: "good", sort: 0 };
  }
  return cells;
});
plugin::column("images", |rows, kiri| async move {
    let mut cells = HashMap::new();
    for row in rows {
        let cell = match load_scan(&kiri, &row.name).await? {   // your own code, reading kiri.store()
            None => Cell::new("not scanned", Tone::Plain).sort(-1),
            Some(r) if r.critical > 0 => Cell::new(format!("{} critical", r.critical), Tone::Bad).sort(1000 + r.critical),
            Some(r) if r.high > 0 => Cell::new(format!("{} high", r.high), Tone::Warning).sort(r.high),
            Some(_) => Cell::new("clean", Tone::Good).sort(0),
        };
        cells.insert(row.name, cell);
    }
    Ok(cells)
});

A row with no cell stays empty. A cell can carry a tip, which shows on hover. People hide a column with a right-click on its heading, and the widths they gave Kiri’s own columns stay as they were.

A page or a section in the sidebar

A plugin with one list worth its own screen asks for a page. Every plugin page sits under one Plugins heading, below Kiri’s own groups. A plugin that is nearly a product of its own asks for a section instead: a heading of its own with two to five pages, and a settings button on the heading. A plugin has a page or a section, never both.

# the Trivy scanner
[window]
page = { label = "Scans" }
# Coolify
[window]
section = { name = "Coolify", pages = ["Apps", "Servers", "Deploys"], settings = true }

The prompt lines are Add a page to the sidebar: Scans and Add its own section to the sidebar: Coolify, 3 pages. Kiri asks about a section as a separate question at install, and someone can say no and keep the rest of your plugin, so a plugin with a section must still work without it. The settings button opens your pane in Settings.

plugin.page draws each page by its name. A label is up to 20 characters. The count beside it is the number of rows in its first table, unless you return your own:

plugin.page("Apps", async (kiri) => {
  const apps = await coolify(kiri, "/applications");
  return {
    count: apps.length,
    blocks: [{
      table: {
        columns: ["App", "Server", "State", "Address"],
        rows: apps.map((a) => ({
          key: a.uuid,
          cells: [a.name, a.server, { text: a.state, tone: a.state === "running" ? "good" : "plain" }, a.fqdn ?? "none yet"],
          menu: [{ label: "Open in Coolify", action: "open-app" }, { label: "Stop", action: "stop-app", ask: "Stop {name} on Coolify?" }],
        })),
      },
    }],
  };
});

A row’s menu items run your own actions on that row, with the row’s key as the target. They belong to the page, so they need no line of their own in the prompt, and an ask works as it does in a menu.

Kiri
KiriModulesSharePluginsSettingsPlugins Scans · 6Coolify ⚙ Apps · 2Servers · 2Deploys

Coolify › Apps

AppServerStateAddress
shopprodrunningshop.example.com⋯
docsprodrunningdocs.example.com⋯
The sidebar with the Trivy scanner's page under the Plugins heading, and Coolify's section with three pages and a settings button. Coolify's Apps page is the table from the handler above, each row with its ⋯ menu.

The blocks Kiri draws

Tabs, pages and sections are lists of blocks, the same parts Kiri’s own pages use:

Block What it is
table Columns and rows, each row with an optional ⋯ menu of your actions. Sorts and searches like Kiri’s lists.
tiles Up to four numbers with a label each, such as “3 critical”.
facts Names and values, as at the top of a container’s page.
form Fields, as in [[settings]], and a button that sends them to one of your actions.
log Lines that follow as they arrive, like a container’s Logs tab.
buttons Up to three. Each opens a page, a tab or a link, or runs one of your actions.
notice One line with a tone, for something people should know.
text A plain paragraph.
empty A title, a sentence and one button, for when there’s nothing to show yet.

The types are in the Plugin API. Tab, fact, column and page handlers have 5 seconds to answer; when time runs out, Kiri keeps what it last drew. While Kiri’s VM sleeps, the window shows the last blocks you sent, and opening a page or pressing a button wakes it.

Words and languages

Kiri tells your plugin the window’s language as kiri.lang, such as de or pt-BR, so the blocks you send can be in it. Labels in kiri-plugin.toml are translated from your own files, lang/de.toml and the like, with English when there’s none. Kiri never runs your words through its own dictionary, and it lays out your page right to left in Arabic, Persian and Central Kurdish, as it does its own. A label that fits in English may not in German: kiri plugin dev --outline shows how much of each limit you use.

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