WINDOW PLACES
Settings and notices
Your plugin doesn’t draw a settings screen. It lists the fields it needs in kiri-plugin.toml, and Kiri draws them in Settings next to the feature they belong to, keeps secrets in the system’s own store, and lets your code use a token without ever reading it. Your plugin can also tell people something: a notice in the window, or a system notification once they switch those on. What people see will be in the Kiri docs under Settings and notices when 1.0 ships.
Declare the fields
Each field is one [[settings]] table in kiri-plugin.toml. These are Coolify’s:
[[settings]]
key = "server"
label = "Server address"
type = "url"
required = true
reach = true # the plugin may reach the address typed here
[[settings]]
key = "token"
label = "API token"
help = "Paste a token from Coolify › Keys"
type = "secret"
use = "header" # Kiri adds it to requests; the plugin never reads it
header = "Authorization: Bearer {}"
for = "server" # added only to requests to the address in "server"
Six kinds of field, each drawn the way Kiri draws its own settings:
type |
Kiri draws |
|---|---|
text |
A text box |
url |
A text box that takes only a web address |
number |
A number box |
switch |
An on and off switch |
choice |
A menu of the choices |
secret |
A box that hides what’s typed, then shows Set and Change |
Kiri places the fields from what your plugin adds: with share in [adds] they go in Settings → Sharing, with deploy in Settings → Deploy, and otherwise in your plugin’s own tab under a Plugins heading. A plugin with a section in the sidebar and settings = true gets a button on the section’s heading that opens the same place. Where Kiri pushes images for a deploy is Kiri’s own setting, at the top of Settings → Deploy, so a deploy plugin never asks for it.
Coolify
A field has no prompt line of its own, but two kinds add one, because they let the plugin do more: reach = true adds Reach the address you type in its settings (only that address, and only once it’s typed), and a secret adds a line for its use, below.
Secrets your code never reads
Kiri keeps secrets in the system’s own store: the Keychain on macOS, Credential Manager on Windows, and the Secret Service on Linux. On a machine without one, such as a CI runner, Kiri reads KIRI_SECRET_<PLUGIN>_<KEY> from the environment, such as KIRI_SECRET_COOLIFY_TOKEN. There are two kinds:
use |
Prompt line | What happens |
|---|---|---|
"header" (the default) |
Use a token you type, without reading it | Never given to your plugin. When your code calls kiri.http.fetch with { secret: "token" }, Kiri adds header to the request on the way out, and only if the URL is where for points. |
"program" |
Read a key you type, to start its program | For a container plugin whose program needs the key itself, such as tailscaled. Kiri gives it to the program when it starts, in the variable env names, and nowhere else. A company can block this line for every plugin. |
Either way, kiri.settings.get("token") returns only { set: true } or { set: false }. Prefer header: it’s the line people say yes to most easily.
Check connection
Handle plugin.settings.check and your settings pane gets a Check connection button. Your handler gets the values as typed, before they’re saved, and a kiri.http.fetch with secret uses the typed token. Answer with one line, ok or not; Kiri shows it beside the button, green or red. It has 10 seconds.
import { plugin } from "@kiri/sdk";
plugin.settings.check(async (values, kiri) => {
const res = await kiri.http.fetch(`${values.server}/api/v1/servers`, { secret: "token" });
if (res.status === 401) return { ok: false, text: "Coolify refused the token. Make a new one in Coolify › Keys." };
return { ok: true, text: `Connected · ${(await res.json()).length} servers` };
});plugin.SettingsCheck(func(v plugin.Settings, k *plugin.Kiri) plugin.CheckResult {
req, _ := http.NewRequest("GET", v.String("server")+"/api/v1/servers", nil)
resp, err := k.HTTP().Do(plugin.WithSecret(req, "token"))
if err != nil {
return plugin.CheckResult{OK: false, Text: "Coolify didn't answer."}
}
if resp.StatusCode == 401 {
return plugin.CheckResult{OK: false, Text: "Coolify refused the token. Make a new one in Coolify › Keys."}
}
return plugin.CheckResult{OK: true, Text: "Connected"}
})People change fields from a terminal with kiri plugin set NAME KEY=VALUE. A secret is never typed on the command line: kiri plugin set NAME KEY asks for it, or reads it from a pipe. A company can set a field for everyone and lock it, so read settings when you need them rather than assuming the value you saw first.
Notices
Ask to show notices, and your plugin can put up the same small box Kiri uses at the bottom right of the window, with your mark and name, up to 120 characters and at most one button:
[window]
notices = true
await kiri.notify({
text: "shop is live on prod: https://shop.example.com",
kind: "success",
button: { label: "Open", url: "https://shop.example.com" },
});k.Notify(plugin.Notice{
Text: "shop is live on prod: https://shop.example.com",
Kind: "success",
Button: &plugin.Button{Label: "Open", URL: "https://shop.example.com"},
})kiri.notify(Notice {
text: "shop is live on prod: https://shop.example.com".into(),
kind: Kind::Success,
button: Some(Button::new("Open", Where::Url("https://shop.example.com".into()))),
..Default::default()
}).await?;The prompt line is Show notices in the window. kind is info, success, warning or error; Kiri colours the notice and keeps it on screen as long as its own notices of that kind. One notice every 10 seconds per plugin: extra ones are dropped and counted in the person’s activity record, so a noisy plugin shows up there. A notice is for something that happened while someone was doing something else, such as a deploy going live. The answer to a click on one of your menu items, plugin.say, is a notice too, and needs no permission.
System notifications
With notifications = true, your plugin can reach people while Kiri’s window is closed: in Notification Center on macOS, in Windows notifications, and in the desktop’s notifications on Linux. The prompt line is Send system notifications, if you switch them on, and that’s what happens: they stay off until the person switches on Send system notifications in your plugin’s settings.
[window]
notifications = true
await kiri.notify({ text: "Deploy to prod failed: the health check timed out.", kind: "error", system: true });
One system notification a minute at most. While they’re off, Kiri shows the same text as a notice in the window if your plugin may show notices, and otherwise drops it and counts it. The system’s own Focus and Do Not Disturb rules still apply.
© 2026 Kiri · The SDK is open source under the Apache License 2.0 · Docs · runkiri.com