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, 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:
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.
Compose › shop
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:
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.
Coolify › Apps
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