Console

Added in 2.1

It runs on the machine the server runs on, and shows the statuses, words and colours of the web UI. The CLI stays as it is: the console is a third way in, not a replacement.

Open it

Run kraft console in a terminal. It refuses, with one sentence, when:

• stdin or stdout is not a terminal, such as in a pipe: it needs one to draw in;
• it runs inside a Kraft worker, where KRAFT_WORK_ITEM_ID is set;
• the server on Kraft's port is another instance, with a different run directory.

With no server answering, it opens anyway and says so on every screen.

Opening and leaving

The console notes when you quit it, in console-seen.json in the instance's run directory. Opened again, a dim line under the top line says what moved since then, counted from the board: since 14:02 · 2 finished · 1 needs you, since 14:02 · nothing finished · nothing needs you when items only moved on, or nothing changed since 14:02. It goes after a minute or at your first key.

An item restored from the archive does not count as finished. The first time you open the console there is no such line, and none when the file does not hold a time that could be true.

While it is open, an item that finishes gets one toast: ✓ merged !42 · Fix the parser, or ✓ completed · ... with no merge request. Several at once read ✓ 3 finished.

When you quit, one plain line stays in the terminal: kraft console · 2 need you · 3 running, kraft console · nothing needs you · 3 running on their own, or kraft console · nothing needs you, and nothing is running. It is not printed when the console ends on an error, or never reached the server.

The top line

Every screen keeps the top line. It starts with ◆ kraft, and the screen you are on is drawn as a pill in the accent colour.

Keys

The footer lists the keys of the screen you are on.

The Board

The Board lists every item in the web UI's groups and order: Needs you, Running, Not started and Done, in one rounded panel. Each group's name and count is a separator line inside it; a group with no rows shown shares the next one's line, as in Not started 0 ─ Done 12 ›. Done is folded to its count. Archived items are not shown.

Each item is one line: a bar in its state's colour, the first 8 characters of its id, its title, what it is doing or waiting for in the web UI's words, its chain when that is not default, and how long ago it last changed.

With every repo shown, the repo's name joins the chain; the repo and the chain each have their own colour. A title too long for its column ends in …. In a window under 80 columns the chain, repo and age columns drop.

The row under the cursor opens a second line under its title: its repo, its chain (default too) and where it stands on the chain, the node it is on marked ●.

Running work

An item whose agent, or an escalation turn, is at work has a spinner in place of its bar, turning through · ✢ ✳ ✶ ✻ ✽. Its age column reads as every row's does, since it last changed. A queued or waiting item is in Running but does not spin.

One clock moves every spinner and running time, eight times a second, only while one is on screen. A spinner redraws its own cell, never the list.

A live update redraws the list without moving your place in it. If the item under the cursor goes (archived, say), the cursor moves to its neighbour.

The Board starts on the repo the console was opened in, as kraft view list does, or on every repo when it was opened outside a connected one.

With nothing filed, the Board says so. When nothing needs you, one muted line under Needs you says so, and how many items run on their own. A filter that matches nothing says "nothing here for this filter".

a, r, p and t are in the footer only while the server allows them for the selected item. Esc in their dialog sends nothing. Afterwards a toast says what the server did, in the CLI's words: a resume that found no free slot says the item is queued, not resumed. An approve's or a reject's toast starts with ✓. A refusal shows in the server's own words, and the Board and the peek read again.

The peek

The peek follows the selected item under the Board's panel, in its own panel titled with the item's id and status. It starts closed in a window under 30 rows; v opens and closes it at any size. It reads the item once the cursor stops, not for every row passed.

The Item

Enter on an item, a, or an item chosen with Ctrl+P opens it. Esc goes back.

Its header is a rounded panel. The top two lines name the item, its repo and chain, and its status in the web UI's words, with what it has spent and when it last changed.

A running item has a working line under them, ✻ implement · task 3 of 5 · 4m 12s, without the spend the line above says. Its time is the running session's, as the web's item page times it; with no session running, no time shows.

A stopped item has a banner instead: the server's reason and, where the web UI gives one, the way on. Then its chain, with the node it stands on in the accent colour, and its tabs.

The tab shown is a pill in the accent colour. ← and →, Tab and Shift+Tab, or [ and ], step through the five tabs, round the end; clicking a tab's name opens it. The panel's edge and the footer name them ← → tabs. j, k, PageUp, PageDown, Home and End scroll the one shown.

The Chain starts on the node the item stands on, or the last one done. An open node says its state; when it ran more than once, each pass, newest first, with what sent it back and the rejection's note. Its sessions read task · attempt · status · time · cost. A running session shows the spinner and its time so far, moving each second. A cancelled item's current node reads cancelled, the ones after it not reached.

The implementing node adds the plan's tasks, those not yet started marked so. A gate lists its decisions, or says it waits for you. A field the server does not give is left out.

An item abandoned while it is open says it no longer exists. One archived while open shows Archived, with no keys to act.

New item

n on any screen opens a form that files a work item, as kraft item create does.

Enter in a one-line field, or File, files it. When Kraft refuses, as for a spec outside the repo, the reason shows under the fields and the form stays open. Esc or Back closes it. A toggle shows ✓ when on and · when off.

Once filed, the item opens. A toast says where it stands, and repeats any warning Kraft gave, such as an open item with the same title. The item is paused unless you chose Start now: p starts it, and Cancel item in its m menu drops it.

The Server screen

2 or /admin opens it, in a panel titled Server. Its first lines say how the server is, from the answer kraft admin health reads and from the release feed. Under them, after a server.log separator, the log follows as the server writes it, with WARNING in the warning colour, ERROR and CRITICAL in the error colour, and each record's source file dimmed.

While the server does not answer, its last answer stays and the first line says no answer.

After an update that installed a new version, a banner says so until you restart the console, which still runs the version it started on. With no server answering, Start server starts one (see When it cannot reach the server).

Add-ons

3 or /addon lists, in a panel titled Add-ons, each collection Kraft knows and where it comes from. With none added, it says what add-ons are and that m adds a collection. Under it are the add-ons it published when last fetched, and any installed from it.

e, d and m each run their kraft admin addon verb in the output panel, which says what it did, and the list is read again after. /admin addon validate is a typed command only.

The review is what kraft admin addon install and update print: the old and new version, what it can reach, and what it contains. Back has the focus. Apply takes it, and the running server loads it. Quitting with a review open answers it Back. A long review scrolls: Tab from Back reaches it. After a kraft admin update that installed a new Kraft, i and u stay closed until you restart the console.

Repos

4 or /repo lists every repo Kraft has, as kraft repo list --all does, in a panel titled Connected repos with c connects one on its edge. * marks the repo the console was opened in. Under each name and path are its test and setup commands: not set when nothing is decided yet, none when it was declared empty.

The form runs kraft repo connect in the output panel, which says what it saved. A command you leave as proposed is not passed, so the proposal stands whole. Verify also runs both commands once in a throwaway worktree; x in the output panel stops it. The repo's .kraft/ library is not offered here: /repo library reviews it.

The prompt

Every kraft verb runs from the prompt at the bottom of every screen, a framed line that starts with ❯. Type it with or without the leading /, and with or without kraft, so a command the CLI printed can be pasted back as it is: /item resume a91c and kraft item resume a91c do the same.

While it is empty, it says what this screen takes: on the Board, a approve · r reject · /command…; on an item, /item … for this item, or esc, since an /item verb typed there with no id acts on that item, as /item pause does; elsewhere /command….

The footer names these while the prompt has the focus: esc leave, tab complete, ↑ previous.

The status line

Under the prompt, one line says how things stand, from the server's own answers. Each part is read when the console reaches the server, and again whenever it reconnects. A part whose read fails is left out.

A narrow window drops the agents first, then the spend. With no server, the line keeps only ? keys.

Typed commands

A group on its own opens its screen: /admin the Server screen, /repo Repos, /addon Add-ons, /view and /item the Board. /view watch opens the Board too.

Some commands are refused, with a sentence saying why:

/admin update never passes -y, even when you type it, so the refusals it would otherwise skip still show.

The output panel

Each command runs as its own kraft process, and the output panel opens above the prompt to show it: the command, everything it prints as it prints it, and its exit code, in red when it is not 0. The panel keeps every command you ran since the console opened.

One command runs at a time. A command has no terminal to ask you anything on, so one that would ask goes on without asking or stops with its own refusal. Quitting the console stops a running command, and kills it if it has not stopped within three seconds.

Confirms

Before a command that cannot be undone, the console asks first. Back has the focus, so Enter alone never goes on, and Esc answers Back. The other button names the command: Restart, Stop, Update, Disconnect, Cancel item, Archive, Abandon or Uninstall.

R and U on the Server screen ask the same as /admin restart and /admin update --restart, d on Repos the same as /repo disconnect, and d on Add-ons the same as /admin addon uninstall.

Small windows

The console is laid out for 80 columns by 24 rows. Under 30 rows, panels give up their top and bottom edges, so each title becomes a rule, and the prompt is one line: the rows go to the work. Narrower than 80 columns, the footer goes and the status line names ? keys, so it still works as a side pane. Smaller than 60 by 16, it shows "make the window larger" until the window grows.

When it cannot reach the server