Terminal UI

pnpm sctl

With no arguments, stackctl opens its terminal UI: a picker to choose services, then a run screen with their combined log. Everything in it works with the keyboard or the mouse.

Choosing services

• space selects the service under the cursor. So does a click on its row.
• A dependency says what needs it (needed by frontend), and stays selected while that service is.
• The "will start" line is exactly what ⏎ starts: your picks, their deps and the infra.
• / filters the list as you type. n clears the selection.
• ⏎ starts the session and remembers the selection for next time.

Skip the picker with -s <service> (repeatable), or --last-answers to reuse the saved selection.

The run screen

The log fills the screen, above a footer:

• The rule line names the workspace and its git branch.
• The services rows list each application service, then the infra services, with a state dot and the memory each uses.
• The keys row shows what the keys do for the focused service.
• The links row has each service's urls. Open one with Cmd+click, or your terminal's own link gesture.

Dot	State
green ●	running, and healthy if it has a healthcheck
blinking yellow ●	starting, restarting, or running but not healthy yet
cyan ○	waiting for a service it depends on
gray ○	pending
red ○	stopped or exited

Startup happens on this screen too. If it fails (the proxy's port is taken, an infra service never gets healthy), nothing else starts, the reason is in the log, and the screen stays up for reading. Ctrl+C then exits with code 1.

Keys

Key	Action
← → ↑ ↓	Focus another service.
r	Restart the focused service.
s	Stop it, or start it when it isn't running.
m	Open the commands menu: the service's scripts, and a custom shell command.
R	Reset the focused infra service, deleting its data. Asks for a second R.
f	Filter the log: type terms, ⏎ to apply, esc to clear.
c	Clear the log on screen. The log file keeps every line.
PageUp/PageDown, Home/End	Scroll the log. End follows the newest line again.
esc	Drop the text selection, then the newest notice, then the filter.
Ctrl+C	Quit. Asks for a second press within two seconds once services are running.

In the commands menu, ↑↓ choose a script, ←→ switch service, ⏎ runs it with the service's environment, and esc closes the menu.

Mouse

• Click a service to focus it, and click a key hint to do what its key does.
• The wheel scrolls the log.
• Drag over the log to select text. It is copied when you let go. Double-click selects a word, triple-click a line.

Memory figures

• A service's figure covers everything it runs: its dev process and whatever that started (Vite's esbuild, the node under node --watch).
• On macOS it is the number Activity Monitor shows. On Linux it is the memory the processes hold privately, in RAM or swapped out. 906M is 906 MiB.
• An infra service's figure is its containers' memory as docker stats reports it.

Without a terminal

The UI needs a TTY. In a script, a CI job or an agent's shell, use --headless, which streams the same log to stdout.