# stackctl

> Run your monorepo's stack in one terminal.

A terminal UI and CLI for a monorepo's services, infrastructure, tests and CI during development.

## Table of Contents

### Introduction

- [Getting started](/guide/getting-started.md): Install stackctl, scaffold stackctl.config.ts, describe your services and run them.
- [Why stackctl](/guide/why.md): What stackctl replaces in a monorepo's development setup, and what it deliberately leaves alone.

### Guide

- [Services](/guide/services.md): What a service is to stackctl, the dev script or Makefile target it runs, how scripts are executed, and restarting after a code edit.
- [Terminal UI](/guide/terminal-ui.md): The interactive terminal UI - the service picker, the run screen, its footer, keys and mouse, and what the memory figures mean.
- [Environment and modes](/guide/env.md): How stackctl loads .env files per workspace, service and mode, which value wins, the variables it sets itself, and how modes keep sessions apart.
- [One-off commands](/guide/commands.md): Run one command or one script in a service's directory with its exact environment, using stackctl exec and stackctl run.
- [Logs](/guide/logs.md): The combined log stream - filtering, timestamps, automatic JSON log formatting, stackctl's own lines, log files and the stackctl logs command.
- [Tests and CI](/guide/testing.md): Give an e2e suite or a CI job a healthy stack with startStack(), stackctl start --detach or --headless, in a test mode that runs beside your dev session.

### Config

- [The config file](/config/config-file.md): stackctl.config.ts - where it lives, every top-level defineConfig option, callbacks, typed tokens, splitting the config across files and typed service names.
- [Services](/config/services.md): Every option of a service in stackctl.config.ts - port, healthcheck and readiness, deps, command, urls, autostart, tokens, logs, color and directory.
- [Environment](/config/env.md): The env option of stackctl.config.ts - env.vars for variables set in the config, env.override to let files win over the shell, and env.additionalFiles for extra .env files.
- [Logs](/config/logs.md): The logs options of stackctl.config.ts - on-screen timestamps, the default JSON log formatter, the logging helpers for pino and winston, and writing your own formatter.
- [Infra](/config/infra.md): The infra option - run the databases, caches and brokers in docker-compose.yaml before your services, with readiness, per-mode Compose projects, enabled, and callbacks for migrations and seeds.
- [Reverse proxy](/config/reverse-proxy.md): The reverseProxy option - a dev reverse proxy that gives each service its own hostname, with routes by host and path, TLS, status pages, Vite HMR and a TLS terminator in front.
- [URLs and origins](/config/urls.md): Public origins - where a browser reaches each service, the PUBLIC_ORIGIN variable, footer links with urls, the publicOrigin option and the buildAddress helper.

### Reference

- [CLI](/reference/cli.md): Every stackctl command and flag - start, stop, reset, service, show-config, exec, run, logs, infra and init - plus global options, taking over a session and where state is kept.
- [Control API](/reference/control-api.md): The localhost HTTP control API of a running session - finding its port, GET /query/status, GET /events, and the service, infra and quit commands, with request and response payloads.
- [SDK](/reference/sdk.md): stackctl's SDK, the functions it exports for your own scripts and test suites - defineConfig, startStack, stackEnvironment, exec, run, resolveEnv and logging - with their options and return values.

### AI agents

- [Built for agents](/ai/overview.md): How stackctl is built for coding agents - the installable skill, headless mode, the control API, llms.txt on the site and inside the npm package, and the guard rails that protect your session.
- [Agent playbook](/ai/playbook.md): Recipes for a coding agent - check whether an app is running, find a service's URL, start a stack in the background and wait for it, restart a service, run one-off commands, use infra, read logs and onboard a new service.