<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>CLI Reference — stack docs</title>
<meta name="description" content="Every stack subcommand." />
<link rel="icon" href="assets/logo.svg" type="image/svg+xml" />
<link rel="stylesheet" href="styles.css" />
<style>
.wrap { max-width: 1200px; margin: 0 auto; padding: 0 clamp(20px, 5vw, 72px); }
.nav { padding-inline: max(clamp(20px, 5vw, 72px), calc((100% - 1200px) / 2 + clamp(20px, 5vw, 72px))); }
.nav a[aria-current='page'] { color: var(--color-accent-700); }
.docs-main p, .docs-main li { font-size: 15px; }
.docs-main .lead { font-size: 17px; opacity: 0.85; max-width: 60ch; }
.cmd { border: 1px solid var(--color-divider); padding: var(--space-4); margin: var(--space-4) 0; }
.cmd h3 { font-family: var(--font-heading); font-size: 16px; margin: 0 0 4px; }
.cmd h3 code { background: none; }
.cmd p { margin: var(--space-2) 0 0; font-size: 14px; opacity: 0.85; }
.cmd .alias { font-size: 12px; opacity: 0.6; margin-left: 8px; font-weight: 400; }
</style>
</head>
<body>
<nav class="nav site-nav">
<a href="index.html" class="nav-lockup"><img class="nav-mark" src="assets/logo.svg" alt="" /><span class="nav-brand">stack</span></a>
<div class="nav-links">
<a href="getting-started.html" aria-current="page">Docs</a>
<a href="changelog.html">Changelog</a>
<a href="https://github.com/sanayasfp/stack" target="_blank" rel="noopener">GitHub</a>
</div>
<button type="button" class="btn btn-secondary btn-icon theme-toggle blueprint" id="theme-toggle" aria-label="Switch between light and dark">
<i class="corner tl"></i><i class="corner tr"></i><i class="corner bl"></i><i class="corner br"></i>
<svg class="icon-sun" width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="4"/><path d="M12 2v2M12 20v2M4.93 4.93l1.41 1.41M17.66 17.66l1.41 1.41M2 12h2M20 12h2M4.93 19.07l1.41-1.41M17.66 6.34l1.41-1.41"/></svg>
<svg class="icon-moon" width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/></svg>
</button>
</nav>
<div class="wrap docs-layout">
<aside class="docs-side">
<div class="side-group">
<h6>Guide</h6>
<a href="getting-started.html">Getting Started</a>
</div>
<div class="side-group">
<h6>Reference</h6>
<a href="manifest.html">Manifest (stack.toml)</a>
<a href="cli.html" aria-current="page">CLI Commands</a>
</div>
<div class="side-group">
<h6>More</h6>
<a href="https://github.com/sanayasfp/stack/tree/main/examples" target="_blank" rel="noopener">Examples</a>
<a href="changelog.html">Changelog</a>
<a href="https://github.com/sanayasfp/stack" target="_blank" rel="noopener">GitHub</a>
</div>
</aside>
<main class="docs-main">
<span class="kicker" style="display:block;font-family:var(--font-heading);font-size:12px;letter-spacing:.08em;text-transform:uppercase;font-weight:600;color:var(--color-accent-700);margin-bottom:8px;">Reference</span>
<h1>CLI Reference</h1>
<p class="lead">Every <code>stack</code> subcommand. Flags shown in <code>[brackets]</code> are optional.</p>
<h2>Project lifecycle</h2>
<div class="cmd"><h3><code>stack new <name></code> / <code>stack new .</code></h3><p>Interactive scaffolding. <code>stack new .</code> targets the current directory and refuses to run if a <code>stack.toml</code> is already there.</p></div>
<div class="cmd"><h3><code>stack up [dir] [--prompt]</code></h3><p>Clones anything declared in <code>[[clone]]</code> that's missing, activates languages, starts declared services, spawns <code>[run]</code>, and routes the domain. Defaults to the current directory. <code>--prompt</code> allows interactive prompting for unresolved command placeholders.</p></div>
<div class="cmd"><h3><code>stack down [project] [--all]</code></h3><p>Stops that project's <code>[run]</code> process and removes its route. Shared services keep running for other projects unless <code>--all</code> is passed, which stops every project and every shared service — the true end-of-day shutdown.</p></div>
<div class="cmd"><h3><code>stack status</code> <span class="alias">alias: stack ps</span></h3><p>Lists every running project, service, and Caddy's own liveness/route count. Self-healing — drops entries whose process is no longer alive.</p></div>
<div class="cmd"><h3><code>stack stats [--no-stream]</code></h3><p>Continuously-refreshing CPU/memory view, <code>docker stats</code>-style. <code>--no-stream</code> for a single snapshot.</p></div>
<div class="cmd"><h3><code>stack logs <name> [--tail N] [-f/--follow]</code></h3><p>Reads a project's or service's log file directly — works even after it's stopped, since it doesn't depend on the running-state list.</p></div>
<h2>Manifest editing</h2>
<div class="cmd"><h3><code>stack add <kind> <name> [version] [options]</code></h3><p><code>kind</code> is <code>language</code>, <code>service</code>, or <code>tool</code>. Format-preserving — existing comments and key order in <code>stack.toml</code> survive untouched.</p></div>
<div class="cmd"><h3><code>stack remove <kind> <name></code></h3><p>Removes one entry, same format-preserving guarantee.</p></div>
<h2>Diagnostics & registry</h2>
<div class="cmd"><h3><code>stack doctor [--fix]</code></h3><p>Checks vfox/uv/Caddy are present at compatible versions, and that every registered <code>service</code>/<code>tool</code> path still exists on disk. <code>--fix</code> installs vfox/uv/Caddy at stack's pinned versions. Also scans for pre-existing Windows Services (MySQL, MongoDB, PostgreSQL) worth registering as <code>external</code>.</p></div>
<div class="cmd"><h3><code>stack register <kind> <name> <version> <path></code></h3><p><code>kind</code> is <code>service</code>, <code>tool</code>, or <code>language</code> — makes a BYO install reusable by any project, without repeating the path in every <code>stack.toml</code>. <code>stack register service <name> <version> --external --port <port></code> registers an already-running instance instead of a path.</p></div>
<div class="cmd"><h3><code>stack list</code></h3><p>Live-merged view of everything installed — vfox, uv, and the registry — queried fresh each time, never cached.</p></div>
<div class="cmd"><h3><code>stack prune [--yes] [--purge-data]</code></h3><p>Reports language/service versions installed but no longer referenced by any known project. Dry-run by default; <code>--yes</code> uninstalls orphaned language SDKs and drops orphaned registry pointers only — a service's actual data directory is never touched without the separate, explicit <code>--purge-data</code>.</p></div>
<h2>Shell integration</h2>
<div class="cmd"><h3><code>stack setup [--shell]</code></h3><p>One-time bootstrap: wires the shell hook into your profile and runs <code>doctor --fix</code>. Idempotent — safe to run again.</p></div>
<div class="cmd"><h3><code>stack hook <shell></code></h3><p>Prints the bootstrap script your shell profile evaluates once at startup. You won't normally call this directly — <code>stack setup</code> wires it for you.</p></div>
<div class="cmd"><h3><code>stack activate <shell></code></h3><p>Called by the hook on every prompt — resolves the current directory's <code>stack.toml</code> (if any) and prints the <code>PATH</code> changes for that shell to apply. Silent, no-op output when no manifest is found.</p></div>
<div class="cmd"><h3><code>stack load-env [path]</code></h3><p>Loads a <code>.env</code>-style file for the current shell session only (defaults to <code>.env</code> in the current directory). Confirms which variable names were loaded — never the values.</p></div>
</main>
</div>
<script src="site.js"></script>
</body>
</html>