Process supervisor

gtl start runs your dev server under a Unix socket supervisor that injects allocated env vars, streams logs to your terminal, and accepts remote stop/restart commands from any other process.

How it works

  1. You run gtl start in your terminal. The supervisor starts and launches your dev server.
  2. Server output streams to your terminal. You see every log line.
  3. An agent (or any process) calls gtl restart from another terminal. The supervisor bounces the server.
  4. Logs resume in your original terminal. No detached sessions, no hidden processes.
  5. Ctrl+C in your terminal fully exits the supervisor and the server.

Commands

Command Behavior
gtl start Launches supervisor + server. If supervisor is already running, resumes the server process.
gtl stop Stops the server process. Supervisor stays alive so the server can be resumed.
gtl stop --kill Shuts down the supervisor entirely. Equivalent to Ctrl+C from a remote process.
gtl restart Atomic stop + start. Bounces the server in one step.
Ctrl+C Fully exits the supervisor and the server. The socket is cleaned up.

Configuration

The supervisor uses the commands.start field from your .treeline.yml:

.treeline.yml 
commands:
  start: bin/dev

Resilience

gtl start handles several edge cases automatically so you don’t have to track down orphaned processes:

  • Terminal closed mid-session. The supervisor handles SIGHUP and exits cleanly when a terminal window closes, rather than surviving as an unresponsive zombie. If you re-run gtl start and the old supervisor is alive but its server is stopped, Treeline kills the orphaned supervisor and starts fresh in the current terminal so output appears where you’re looking.
  • Port already occupied. Before launching, gtl start checks whether the allocated port is already in use. If it identifies the process via tmp/pids/server.pid as the culprit, it prompts to kill it — rather than letting your framework fail with a cryptic address-in-use error.
  • Unresponsive supervisor. If the supervisor process exists but its socket is unresponsive, gtl stop --kill falls back to force-killing via the PID file.

Security

The supervisor communicates over a Unix socket with 0600 permissions (owner-only). Read deadlines and client timeouts prevent hung connections from holding the supervisor’s internal lock. The socket path is derived from a SHA-256 hash of the worktree path.

TUI dashboard

gtl dashboard (aliases: gtl dash, gtl ui) opens a full-screen terminal UI showing every worktree grouped by project. The detail panel displays ports, database name, supervisor state, link overrides, router URLs, and tunnel URLs when configured. Polls every two seconds for a live view.

Keyboard shortcuts

  • j / k or arrow keys to move through the list
  • Tab to switch focus between list and detail panel
  • s start or stop the dev server for the selected worktree
  • o open the app in the browser
  • r restart the supervisor
  • e sync env file from .treeline.yml
  • n create a new worktree (prompts for branch name)
  • d release the selected worktree (confirmation prompt)
  • / filter by project, branch, or worktree name
  • ? toggle the full shortcut help overlay
  • q or Ctrl+C quit