Back to Catalog
kranz-org GitHub avatar

kranz

Keyboard-first local service orchestrator with a focused terminal UI

Demo

Terminal preview
kranz
kranz project visual

Overview

Keyboard-first local service orchestrator with a focused terminal UI

From the maintainer

Origin story

Local development stacks tend to spread across terminal tabs: one long-running process per tab, logs in different places, and startup and shutdown order kept in someone's head. Infrastructure may already live in Docker Compose while actively developed services still run directly on the host. Kranz was built to operate that mixed local stack from one terminal.

First workflow

Install Kranz with Homebrew or go install, create a Procfile with two local commands, and run kranz in that directory. Press a to select all services and s to start them. Watch their state, detected ports, and separate logs in the TUI, then press q and confirm to shut the stack down cleanly.

Design choice

The interaction model is intentionally familiar to lazygit users: a stable, keyboard-first three-panel layout with direct 1/2/3 and Tab navigation, contextual actions, and optional mouse control. The visual system is project-scoped, so each stack can keep its own theme, accent, and canvas colors. Switching projects can also switch the interface's visual identity.

Roadmap

The next planned release is v0.8.0: a scriptable CLI built on the same configuration, dependency graph, and runtime as the TUI, with commands for configuration validation, plans, diagnostics, ports, actions, and foreground startup. It also targets native .deb and .rpm packages for Linux on amd64 and arm64, along with validated WSL 2 support.

Latest Release

v0.14.0
Released: Sep 9, 2026

Added

  • kranz ps and kranz clients accept Docker-style --format Go templates,
    including a table prefix for aligned output with headers.
  • status, ports, doctor, config explain, services, actions, and
    tags support the same row formatter.
  • Top-level kranz services, kranz actions, and kranz tags commands give
    every inspectable collection a direct noun. The actions group defaults to
    listing and also owns run and info. The old list command and singular
    action group have been removed.
  • kranz plan --operation start|stop|restart previews every service a
    lifecycle operation would affect; bare plan remains a start preview.
  • kranz runs supports target, status, time-window, and newest-count filters,
    plus Docker-style row templates. kranz runs retention now owns the
    separate per-target retention table and its formatter fields.
  • ps, clients, and status accept exact, repeatable --filter values and
    interruptible --watch refreshes. --interval controls refresh frequency,
    and --count bounds snapshots for automation.
  • The TUI quit confirmation offers c for Close & choose: it stops the
    current runtime and opens the live runtime chooser without leaving the TUI.
    The chooser remains usable when no other runtime is available.

Changed

  • kranz up now creates a runtime without starting services, matching the TUI
    and MCP surfaces. Selectors still start the named services; --start
    explicitly starts every enabled service. Foreground ownership, log streaming,
    project exit codes, and -d behavior are unchanged. The redundant
    --no-start flag has been removed.

  • Interactive kranz init is now a draft-based terminal wizard. It supports
    any number of editable and removable services and actions, independent
    project appearance controls with a live theme preview, and a final YAML or
    replacement diff before the only write. Init no longer scans package.json
    or implicitly imports nearby files; conversion requires explicit --from.

  • The obsolete MCP --attach-only flag has been removed. Version-specific
    future-command wording in CLI help is now release-neutral.

  • kranz init --name NAME is now the only project-name option. Global
    -p/--project consistently addresses a runtime and is rejected by init.

  • Project, service, and port inspection now follow their entities explicitly:
    kranz project, kranz services info SERVICE, and
    kranz ports inspect PORT. Bare services and ports select their list
    operations. The overloaded info command and singular port group have
    been removed.

  • Conflicting graph --format and --output=json selections now fail instead
    of silently choosing JSON. Help and shell-completion generation explicitly
    reject JSON output because their products are text artifacts.

  • kranz clients now presents each connection in one compact CLIENT column,
    such as TUI, CLI: foreground, or MCP: codex. It no longer reports the
    runtime's background ownership connection as a client, matching kranz ps
    and the TUI Runtimes window. kranz ps now shows the owning supervisor's PID
    directly.

  • The canonical action table shows whether each action requires confirmation.

  • Root help keeps actions beside services and tags, matching the command
    model users configure and operate in the TUI.

Discussions

0 comments
Loading comments...
Alvin By Alvin