# 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.

**Coding agents:** read the [Agent playbook](/ai/playbook.md) first. It has the rules and a recipe for each task, and links to the pages below.

## 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, status, events, 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.
- [Events](/reference/events.md): The event log - each mode's record of what acted on its stack (keys, control API requests, stackctl commands) and what its session did (starts, exits, readiness), one JSON object per line, in node_modules/.stackctl/modes/<mode>/events.log and on GET /events.
- [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 rules file and skill it offers to install, 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, run tests in the test mode, restart a service, bring back one that is down, run one-off commands, use infra, read logs and onboard a new service.