Make the README link in docs/API.md absolute

The docs viewer serves docs/*.md at /docs/<slug> but doesn't ship
README.md as a route, so the relative ../README.md link resolved to
a dead /README.md path in the rendered web UI. Point it at the file's
Gitea URL instead.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

.gitea/workflows/release.yaml

@@ -0,0 +1,41 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: https://github.com/actions/checkout@v4
+
+      - uses: https://github.com/pnpm/action-setup@v4
+        with:
+          version: 11.21.0
+
+      - uses: https://github.com/actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - run: pnpm install --frozen-lockfile
+
+      - run: pnpm run lint
+      - run: pnpm run typecheck
+      - run: pnpm run format:check
+      - run: pnpm run test
+
+      - name: Set package version from the tag
+        run: npm pkg set version="${GITHUB_REF_NAME#v}"
+
+      # Scoped to this one registry host+path (via publishConfig.registry in package.json) rather
+      # than actions/setup-node's registry-url, which would set it as the *default* registry for
+      # every install - breaking `pnpm install` for this project's own (unscoped, public) deps.
+      - name: Configure registry auth for publish
+        run: pnpm config set "//dev.pivoine.art/api/packages/valknar/npm/:_authToken" "$PACKAGE_TOKEN"
+        env:
+          PACKAGE_TOKEN: ${{ secrets.PACKAGE_TOKEN }}
+
+      - name: Publish to Gitea npm registry
+        run: pnpm publish --no-git-checks

.gitignore

@@ -1,16 +1,38 @@
-# Python
+# dependencies
-__pycache__/
+/node_modules
-*.py[cod]
+/.pnpm-store
-*.egg-info/
+/.pnp
-.eggs/
+.pnp.*
-build/
+.yarn/*
-dist/
+!.yarn/patches
-.venv/
+!.yarn/plugins
-venv/
+!.yarn/releases
-.pytest_cache/
+!.yarn/versions
-.ruff_cache/
 
-# Runtime data (created by `triggershell start/dev` in whatever directory the config lives in)
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# vercel
+.vercel
+
+# Runtime data (created by `triggershell start` in whatever directory the config lives in)
 .triggershell/
 
 # Secrets loaded by `triggershell` via ${VAR} interpolation - never commit these
@@ -23,5 +45,6 @@ venv/
 
 # Editors / OS
 .DS_Store
+*.pem
 .idea/
 .vscode/

.prettierignore

@@ -0,0 +1,7 @@
+# Machine-generated - pnpm owns this file's formatting, not prettier.
+pnpm-lock.yaml
+
+# pnpm's local content-addressable store - on some runners this ends up inside the workspace
+# instead of the global cache location; its blobs aren't source files (some happen to parse as
+# JS/TS-like content, which crashes prettier's parser rather than just wasting time on them).
+.pnpm-store/

README.md

@@ -24,20 +24,22 @@ API for automation.
 ## Quickstart
 
 ```bash
-pip install triggershell         # or: pip install -e . from a checkout
+npm install -g triggershell      # or: npx triggershell <command> for one-off use
 triggershell init                # scaffold triggershell.yml (+ .env for secrets) in the current directory
 triggershell users add admin     # create a login (skip if you set auth.enabled: false)
-triggershell dev                 # start in dev mode and open the browser
+triggershell start               # start the app and open the browser
 ```
 
-Edit `triggershell.yml` to add your own scripts (see [Configuration](#configuration) below),
+Edit `triggershell.yml` to add your own scripts (see [Configuration](#configuration) below), then
-then run `triggershell start` for a production build.
+re-run `triggershell start`.
+
+> The `triggershell` package isn't published to npm yet. Until it is, build and link a local copy
+> instead: `pnpm install && pnpm build && pnpm link --global`.
 
 ## Requirements
 
-- Python >= 3.9
+- Node.js >= 20 — the only thing you need installed. Everything else `triggershell` needs ships
-- Node.js >= 20 (checked by the CLI; not auto-installed)
+  inside the package itself and is resolved automatically when you install it.
-- pnpm (auto-provisioned via Corepack if missing and Corepack is available)
 
 ## Configuration
 
@@ -98,14 +100,38 @@ the script — always as a discrete argv element or env var, never interpolated
 ## CLI Usage
 
 | Command                                                                                       | Description                                                                                                                                                                                                            |
-|---|---|
+| --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `triggershell init [PATH]`                                                                    | Scaffold a new config file + `.env` (`--port`, `--auth/--no-auth`, `--force`)                                                                                                                                          |
-| `triggershell validate [-c CONFIG]` | Validate a config file (fast Python pre-flight + full Node/Zod schema) |
+| `triggershell validate [-c CONFIG]`                                                           | Validate a config file against the full schema                                                                                                                                                                         |
-| `triggershell dev [-c CONFIG] [--port] [--host] [--no-browser]` | Run in development mode (hot reload) |
+| `triggershell start [-c CONFIG] [--port] [--host] [--no-browser]`                             | Run the web app                                                                                                                                                                                                        |
-| `triggershell start [-c CONFIG] [--port] [--host] [--no-browser] [--skip-build]` | Build (if stale) and run in production mode |
+| `triggershell doctor [-c CONFIG]`                                                             | Print environment/config diagnostics                                                                                                                                                                                   |
-| `triggershell doctor` | Print environment/config diagnostics |
+| `triggershell scripts list [-c CONFIG]`                                                       | List configured scripts                                                                                                                                                                                                |
+| `triggershell scripts show <scriptId> [-c CONFIG]`                                            | Show a script's command and variables                                                                                                                                                                                  |
+| `triggershell run <scriptId> [--var name=value...] [--token] [--local\|--remote] [--no-wait]` | Run a configured script - through an already-running server's API if one is reachable (so any open browser tab sees it live), otherwise standalone. See [Running scripts from the CLI](#running-scripts-from-the-cli). |
 | `triggershell users add <username> [-c CONFIG] [--inline]`                                    | Hash a password, store it in `.env`, and print a `${VAR}` snippet for `auth.users` (`--inline` prints the raw hash instead)                                                                                            |
 | `triggershell users add-token <name> [-c CONFIG] [--inline]`                                  | Generate an API token, store its hash in `.env`, and print a `${VAR}` snippet for `auth.tokens` (`--inline` prints the raw hash instead)                                                                               |
+| `triggershell service install [--system]`                                                     | Install a systemd unit that runs `triggershell start` (per-user by default, Linux only)                                                                                                                                |
+| `triggershell service uninstall [--system]`                                                   | Stop, disable, and remove the systemd unit                                                                                                                                                                             |
+| `triggershell service status [--system]`                                                      | Show the systemd unit's status                                                                                                                                                                                         |
+
+### Running scripts from the CLI
+
+`triggershell run <scriptId>` auto-detects whether the web app is already running (a quick
+`/api/healthz` check against `server.host`/`server.port`, overridable with `--host`/`--port`):
+
+- **Server reachable** — the run goes through the same `POST /api/scripts/:id/runs` endpoint the
+  web UI uses, authenticated with `--token`/`TRIGGERSHELL_API_TOKEN` if `auth.enabled`. It's a
+  completely normal run from the server's point of view: it shows up in Run History, and any
+  browser tab open on `/runs/:id` streams its output live, exactly as if it had been started from
+  the UI.
+- **No server reachable** — `run` executes the script itself, in its own process, using the same
+  runner the web app uses. The run and its log are still persisted, just without a browser to watch it.
+
+Force one or the other with `--local`/`--remote` (the latter fails instead of falling back if
+nothing's reachable). Pass variables with repeated `--var name=value` flags (repeat the same name
+for a `multiselect` variable); `--no-wait` prints the run ID and returns immediately instead of
+streaming output and blocking until it finishes. Exit code is `0` for a succeeded run, `1`
+otherwise. `Ctrl-C` while waiting cancels the run, the same as the UI's Cancel button.
 
 ## Web App Guide
 
@@ -129,7 +155,7 @@ Passwords are hashed with argon2id; only the hash ever lives in the config file.
 Full reference with request/response shapes and curl examples: [`docs/API.md`](docs/API.md).
 
 | Method | Path                          | Notes                                                  |
-|---|---|---|
+| ------ | ----------------------------- | ------------------------------------------------------ |
 | GET    | `/api/healthz`                | Unauthenticated readiness probe                        |
 | POST   | `/api/auth/login`             | `{username, password}` → sets session cookie           |
 | POST   | `/api/auth/logout`            | Clears the session                                     |
@@ -145,19 +171,24 @@ Full reference with request/response shapes and curl examples: [`docs/API.md`](d
 
 ## Development
 
+This is the workflow for working on TriggerShell itself, not for installing/running it — it
+bypasses the CLI entirely and talks to the app's own scripts directly, with hot reload. The app is
+still not meant to be run standalone with `next dev`/`next start`, since it needs the custom server
+(`server.ts`) for the WebSocket endpoint — `pnpm dev`/`pnpm start` below cover that:
+
 ```bash
-pnpm --dir app install
+pnpm install
-pnpm --dir app dev            # or: triggershell dev, which wraps this
+pnpm dev            # tsx watch server.ts - reads TRIGGERSHELL_CONFIG_PATH from the environment
-pnpm --dir app lint
+pnpm lint
-pnpm --dir app typecheck
+pnpm typecheck
-pnpm --dir app db:studio      # browse the SQLite DB
+pnpm test            # CLI unit tests (src/cli/**/*.test.ts)
+pnpm db:studio       # browse the SQLite DB
 ```
 
-Repo layout:
+Repo layout — the repo root itself is the published npm package (Next.js app + the `triggershell`
+CLI in `bin/`/`src/cli/`), alongside:
 
 ```
-triggershell/    Python CLI (launcher/orchestrator only)
-app/             Next.js app - all server logic (API, auth, script execution) lives here
 examples/        A runnable example config + scripts
 docs/            Config/architecture/API reference docs
 ```

app/.gitignore

@@ -1,41 +0,0 @@
-# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
-
-# dependencies
-/node_modules
-/.pnp
-.pnp.*
-.yarn/*
-!.yarn/patches
-!.yarn/plugins
-!.yarn/releases
-!.yarn/versions
-
-# testing
-/coverage
-
-# next.js
-/.next/
-/out/
-
-# production
-/build
-
-# misc
-.DS_Store
-*.pem
-
-# debug
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-.pnpm-debug.log*
-
-# env files (can opt-in for committing if needed)
-.env*
-
-# vercel
-.vercel
-
-# typescript
-*.tsbuildinfo
-next-env.d.ts

app/README.md

@@ -1,16 +0,0 @@
-# TriggerShell web app
-
-This is the Next.js app that TriggerShell's Python CLI (`triggershell dev` / `triggershell start`)
-launches — it's not meant to be run standalone with `next dev`/`next start` since it needs a
-custom server (`server.ts`) for the WebSocket endpoint.
-
-See the [repo root README](../README.md) for how to run TriggerShell end-to-end, and
-[`../docs/ARCHITECTURE.md`](../docs/ARCHITECTURE.md) for how this app is put together.
-
-```bash
-pnpm install
-pnpm dev          # tsx watch server.ts - reads TRIGGERSHELL_CONFIG_PATH from the environment
-pnpm lint
-pnpm typecheck
-pnpm db:studio    # browse the SQLite database
-```

app/scripts/validate-config.ts

@@ -1,35 +0,0 @@
-import { loadConfig, ConfigError } from "../src/lib/config/load";
-
-const configPathArg = process.argv[2];
-
-try {
-  const { config, configPath } = loadConfig(configPathArg);
-  console.log(
-    JSON.stringify({
-      ok: true,
-      configPath,
-      scriptCount: config.scripts.length,
-      authEnabled: config.auth.enabled,
-    }),
-  );
-  process.exit(0);
-} catch (error) {
-  if (error instanceof ConfigError) {
-    console.log(
-      JSON.stringify({
-        ok: false,
-        message: error.message,
-        issues: error.issues,
-      }),
-    );
-  } else {
-    console.log(
-      JSON.stringify({
-        ok: false,
-        message: (error as Error).message,
-        issues: [],
-      }),
-    );
-  }
-  process.exit(1);
-}

app/src/app/globals.css

@@ -1,131 +0,0 @@
-@import "tailwindcss";
-@import "tw-animate-css";
-@import "shadcn/tailwind.css";
-@plugin "@tailwindcss/typography";
-
-@custom-variant dark (&:is(.dark *));
-
-@theme inline {
-  --color-background: var(--background);
-  --color-foreground: var(--foreground);
-  --font-sans: var(--font-sans);
-  --font-mono: var(--font-geist-mono);
-  --font-heading: var(--font-sans);
-  --color-sidebar-ring: var(--sidebar-ring);
-  --color-sidebar-border: var(--sidebar-border);
-  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
-  --color-sidebar-accent: var(--sidebar-accent);
-  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
-  --color-sidebar-primary: var(--sidebar-primary);
-  --color-sidebar-foreground: var(--sidebar-foreground);
-  --color-sidebar: var(--sidebar);
-  --color-chart-5: var(--chart-5);
-  --color-chart-4: var(--chart-4);
-  --color-chart-3: var(--chart-3);
-  --color-chart-2: var(--chart-2);
-  --color-chart-1: var(--chart-1);
-  --color-ring: var(--ring);
-  --color-input: var(--input);
-  --color-border: var(--border);
-  --color-destructive: var(--destructive);
-  --color-accent-foreground: var(--accent-foreground);
-  --color-accent: var(--accent);
-  --color-muted-foreground: var(--muted-foreground);
-  --color-muted: var(--muted);
-  --color-secondary-foreground: var(--secondary-foreground);
-  --color-secondary: var(--secondary);
-  --color-primary-foreground: var(--primary-foreground);
-  --color-primary: var(--primary);
-  --color-popover-foreground: var(--popover-foreground);
-  --color-popover: var(--popover);
-  --color-card-foreground: var(--card-foreground);
-  --color-card: var(--card);
-  --radius-sm: calc(var(--radius) * 0.6);
-  --radius-md: calc(var(--radius) * 0.8);
-  --radius-lg: var(--radius);
-  --radius-xl: calc(var(--radius) * 1.4);
-  --radius-2xl: calc(var(--radius) * 1.8);
-  --radius-3xl: calc(var(--radius) * 2.2);
-  --radius-4xl: calc(var(--radius) * 2.6);
-}
-
-:root {
-  --background: oklch(1 0 0);
-  --foreground: oklch(0.145 0 0);
-  --card: oklch(1 0 0);
-  --card-foreground: oklch(0.145 0 0);
-  --popover: oklch(1 0 0);
-  --popover-foreground: oklch(0.145 0 0);
-  --primary: oklch(0.205 0 0);
-  --primary-foreground: oklch(0.985 0 0);
-  --secondary: oklch(0.97 0 0);
-  --secondary-foreground: oklch(0.205 0 0);
-  --muted: oklch(0.97 0 0);
-  --muted-foreground: oklch(0.556 0 0);
-  --accent: oklch(0.97 0 0);
-  --accent-foreground: oklch(0.205 0 0);
-  --destructive: oklch(0.577 0.245 27.325);
-  --border: oklch(0.922 0 0);
-  --input: oklch(0.922 0 0);
-  --ring: oklch(0.708 0 0);
-  --chart-1: oklch(0.87 0 0);
-  --chart-2: oklch(0.556 0 0);
-  --chart-3: oklch(0.439 0 0);
-  --chart-4: oklch(0.371 0 0);
-  --chart-5: oklch(0.269 0 0);
-  --radius: 0.625rem;
-  --sidebar: oklch(0.985 0 0);
-  --sidebar-foreground: oklch(0.145 0 0);
-  --sidebar-primary: oklch(0.205 0 0);
-  --sidebar-primary-foreground: oklch(0.985 0 0);
-  --sidebar-accent: oklch(0.97 0 0);
-  --sidebar-accent-foreground: oklch(0.205 0 0);
-  --sidebar-border: oklch(0.922 0 0);
-  --sidebar-ring: oklch(0.708 0 0);
-}
-
-.dark {
-  --background: oklch(0.145 0 0);
-  --foreground: oklch(0.985 0 0);
-  --card: oklch(0.205 0 0);
-  --card-foreground: oklch(0.985 0 0);
-  --popover: oklch(0.205 0 0);
-  --popover-foreground: oklch(0.985 0 0);
-  --primary: oklch(0.922 0 0);
-  --primary-foreground: oklch(0.205 0 0);
-  --secondary: oklch(0.269 0 0);
-  --secondary-foreground: oklch(0.985 0 0);
-  --muted: oklch(0.269 0 0);
-  --muted-foreground: oklch(0.708 0 0);
-  --accent: oklch(0.269 0 0);
-  --accent-foreground: oklch(0.985 0 0);
-  --destructive: oklch(0.704 0.191 22.216);
-  --border: oklch(1 0 0 / 10%);
-  --input: oklch(1 0 0 / 15%);
-  --ring: oklch(0.556 0 0);
-  --chart-1: oklch(0.87 0 0);
-  --chart-2: oklch(0.556 0 0);
-  --chart-3: oklch(0.439 0 0);
-  --chart-4: oklch(0.371 0 0);
-  --chart-5: oklch(0.269 0 0);
-  --sidebar: oklch(0.205 0 0);
-  --sidebar-foreground: oklch(0.985 0 0);
-  --sidebar-primary: oklch(0.488 0.243 264.376);
-  --sidebar-primary-foreground: oklch(0.985 0 0);
-  --sidebar-accent: oklch(0.269 0 0);
-  --sidebar-accent-foreground: oklch(0.985 0 0);
-  --sidebar-border: oklch(1 0 0 / 10%);
-  --sidebar-ring: oklch(0.556 0 0);
-}
-
-@layer base {
-  * {
-    @apply border-border outline-ring/50;
-  }
-  body {
-    @apply bg-background text-foreground;
-  }
-  html {
-    @apply font-sans;
-  }
-}

app/src/app/icon.svg

@@ -1,5 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24">
-  <rect width="24" height="24" rx="5" fill="#09090b" />
-  <path d="M12 19h8" stroke="#fafafa" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" fill="none" />
-  <path d="m4 17 6-6-6-6" stroke="#fafafa" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" fill="none" />
-</svg>

app/src/components/docs/markdown-viewer.tsx

@@ -1,21 +0,0 @@
-import ReactMarkdown from "react-markdown";
-import remarkGfm from "remark-gfm";
-import { cn } from "@/lib/utils";
-
-export function MarkdownViewer({ content }: { content: string }) {
-  return (
-    <div
-      className={cn(
-        "prose prose-neutral dark:prose-invert max-w-none",
-        "prose-pre:bg-muted prose-pre:text-foreground",
-        // Typography's default inline `code` style is just bold text wrapped in decorative
-        // backtick characters - swap that for the same muted pill used for inline code
-        // elsewhere in the app (see the "no scripts configured" message on the dashboard).
-        "prose-code:before:content-none prose-code:after:content-none",
-        "prose-code:rounded prose-code:bg-muted prose-code:px-1.5 prose-code:py-0.5 prose-code:font-mono prose-code:font-normal prose-code:text-foreground",
-      )}
-    >
-      <ReactMarkdown remarkPlugins={[remarkGfm]}>{content}</ReactMarkdown>
-    </div>
-  );
-}

app/src/components/runs/run-status-badge.tsx

@@ -1,37 +0,0 @@
-import { Badge } from "@/components/ui/badge";
-import type { RunStatus } from "@/lib/db/schema";
-import { cn } from "@/lib/utils";
-
-const styles: Record<RunStatus, string> = {
-  queued: "bg-muted text-muted-foreground",
-  running: "bg-blue-500/15 text-blue-600 dark:text-blue-400",
-  succeeded: "bg-emerald-500/15 text-emerald-600 dark:text-emerald-400",
-  failed: "bg-destructive/15 text-destructive",
-  cancelled: "bg-muted text-muted-foreground",
-  timed_out: "bg-amber-500/15 text-amber-600 dark:text-amber-400",
-  interrupted: "bg-amber-500/15 text-amber-600 dark:text-amber-400",
-};
-
-export const runStatusLabels: Record<RunStatus, string> = {
-  queued: "Queued",
-  running: "Running",
-  succeeded: "Succeeded",
-  failed: "Failed",
-  cancelled: "Cancelled",
-  timed_out: "Timed out",
-  interrupted: "Interrupted",
-};
-
-export function RunStatusBadge({ status }: { status: RunStatus }) {
-  return (
-    <Badge
-      className={cn("border-transparent font-medium", styles[status])}
-      variant="outline"
-    >
-      {status === "running" && (
-        <span className="mr-1 inline-block size-1.5 animate-pulse rounded-full bg-current" />
-      )}
-      {runStatusLabels[status]}
-    </Badge>
-  );
-}

app/src/lib/docs.ts

@@ -1,41 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-
-export interface DocMeta {
-  slug: string;
-  title: string;
-  description: string;
-  file: string;
-}
-
-export const DOCS: DocMeta[] = [
-  {
-    slug: "api",
-    title: "API Reference",
-    description: "REST and WebSocket endpoints, auth, and request/response shapes.",
-    file: "API.md",
-  },
-  {
-    slug: "config",
-    title: "Config Reference",
-    description: "Every field in triggershell.yml: server, auth, scripts, and variables.",
-    file: "CONFIG_REFERENCE.md",
-  },
-];
-
-export function getDocMeta(slug: string): DocMeta | undefined {
-  return DOCS.find((doc) => doc.slug === slug);
-}
-
-// docs/ ships at the repo root, one level up from this Next app - resolved at runtime rather
-// than imported, since the compiled Route Handler module graph doesn't preserve source-relative
-// paths (same reasoning as config path resolution in lib/config/load.ts).
-function docsDir(): string {
-  return path.resolve(process.cwd(), "..", "docs");
-}
-
-export function readDocContent(doc: DocMeta): string | null {
-  const filePath = path.join(docsDir(), doc.file);
-  if (!fs.existsSync(/*turbopackIgnore: true*/ filePath)) return null;
-  return fs.readFileSync(/*turbopackIgnore: true*/ filePath, "utf-8");
-}

bin/triggershell.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { register } from "tsx/esm/api";
+
+register();
+await import("../src/cli/index.ts");

docs/API.md

@@ -6,6 +6,10 @@ When `auth.enabled: true`, every endpoint below except `/api/healthz`, `/api/aut
 `/api/auth/session` requires either a valid session cookie or an `Authorization: Bearer <token>`
 header using a token from `triggershell users add-token`.
 
+`triggershell run <scriptId>` is a first-party client of this exact REST + WS contract (see
+[Running scripts from the CLI](https://dev.pivoine.art/valknar/triggershell/src/branch/main/README.md#running-scripts-from-the-cli)) -
+nothing below is CLI-specific.
+
 ## Auth
 
 ### `POST /api/auth/login`
@@ -73,7 +77,7 @@ code). `404` if not found.
 
 ### `POST /api/runs/:runId/cancel`
 
-`202 {"status": "cancelling"}`. `409` if the run already finished, or if it isn't tracked by *this*
+`202 {"status": "cancelling"}`. `409` if the run already finished, or if it isn't tracked by _this_
 server process (e.g. after a restart — see "orphaned runs" in `docs/ARCHITECTURE.md`).
 
 ### `GET /api/runs/:runId/logs`

docs/ARCHITECTURE.md

@@ -1,13 +1,14 @@
 # Architecture
 
 ```
- triggershell (Python CLI)                     app/ (Next.js, all server logic)
+ triggershell (Node CLI, src/cli)               server.ts + src/ (Next.js, all server logic)
- ───────────────────────                       ──────────────────────────────
+ ───────────────────────────────                ─────────────────────────────────────────
- triggershell dev|start                         server.ts (custom Node server)
+ triggershell start                              server.ts (custom Node server)
-   1. resolve + pre-flight the config              ├─ Next.js request handler (pages, API routes)
+   1. resolve + validate the config (loadConfig)    ├─ Next.js request handler (pages, API routes)
-   2. check node/pnpm, `pnpm install` if stale      ├─ ws.WebSocketServer on /ws/runs
+   2. check the port is free                        ├─ ws.WebSocketServer on /ws/runs
-   3. set TRIGGERSHELL_CONFIG_PATH/PORT/HOST env    └─ boot: migrate DB, sync auth, reconcile runs
+   3. set TRIGGERSHELL_CONFIG_PATH/PORT/HOST/        └─ boot: migrate DB, sync auth, reconcile runs
-   4. spawn `pnpm run dev|start`, forward signals
+      NODE_ENV
+   4. import("./server.ts") — same process                    │
    5. poll /api/healthz, open browser                          │
                                                     ┌──────────┴──────────┐
                                               REST API                 WebSocket
@@ -23,22 +24,64 @@
 
 ## Why a custom Node server
 
-Next.js Route Handlers can't host a persistent WebSocket server, so `app/server.ts` wraps Next's
+Next.js Route Handlers can't host a persistent WebSocket server, so `server.ts` wraps Next's
 request handler in a plain `http.createServer` and attaches a `ws.WebSocketServer` via the
 `upgrade` event, scoped to `/ws/runs` with its own auth check (Route Handlers get auth via
 `next/headers`'s `cookies()`, which isn't available on a raw `http.IncomingMessage`).
 
-## Why the Python CLI is thin
+## Why the CLI and server share one process
 
-Everything Node/pnpm/Next.js needs to do (serve pages, run scripts, stream output, enforce auth)
+`triggershell start` (`src/cli/commands/start.ts`) doesn't spawn `server.ts` as a child process —
-is naturally a Node problem — `execa` for argv-safe spawning, `ws` for streaming, Next for the UI.
+it sets `process.env` (`TRIGGERSHELL_CONFIG_PATH`, `PORT`, `HOST`, `NODE_ENV`) and then dynamically
-Python's job is just: get Node/pnpm ready, validate the config fast, and manage the child process's
+`import()`s `server.ts` directly, in the same Node process. `server.ts` reads that env and installs
-lifecycle (signals, readiness, browser launch) — a CLI concern, not a web-server concern.
+its own `SIGTERM`/`SIGINT` handlers, so once it's imported, `Ctrl-C` or `systemctl stop` just work —
+there's no parent process relaying signals to a child, no separate lifecycle to manage. The CLI's
+`bin/triggershell.js` entry point registers `tsx`'s loader once for the whole process
+(`tsx/esm/api`'s `register()`), so both the CLI's own `.ts` command files and `server.ts` run
+straight from source, with no compile/bundle step for either.
+
+## `triggershell run` - a second, independent client of the same run pipeline
+
+`triggershell run <scriptId>` (`src/cli/commands/run.ts`) never duplicates the spawn/streaming
+logic in `src/lib/runner/engine.ts` - it just calls it from a different position:
+
+- If a server is reachable (`GET /api/healthz`), `run` is a plain HTTP+WS client: `POST
+/api/scripts/:id/runs` (the same route the web UI's "Run" button calls) starts the run _inside
+  that server's process_, and `run` then subscribes over `/ws/runs` exactly like a browser tab
+  would, using the same `ClientMessage`/`ServerMessage` protocol (`src/lib/ws/protocol.ts`). This
+  is why a run started this way appears live in any open browser tab for free - the broadcast path
+  (`emitRunMessage` → the `runEvents` listener in `src/lib/ws/server.ts` → every subscribed
+  WebSocket) has no idea the run was triggered by a CLI instead of a click.
+- If nothing's reachable, `run` calls `startRun()` directly, in its own short-lived process (after
+  its own `migrateOnBoot()`/`reconcileOrphanedRuns()`, so a from-scratch `.triggershell/` works
+  standalone). Since it's in the same process as the run it just started, it doesn't need WS at
+  all - it listens on the same in-process `runEvents` emitter a WS client would otherwise be fed
+  from, using the exact "read the log file and current status first, then attach a live listener"
+  ordering `subscribe()` in `ws/server.ts` already uses, for the same reason: a fast script can
+  finish before a listener is attached.
+
+Either way, `Ctrl-C` cancels the run through the existing mechanism for that mode - a `{"type":
+"cancel"}` WS message for the remote case, `cancelRun()` (`src/lib/runner/registry.ts`) directly
+for the local case - not a new cancellation path.
+
+## Running as a systemd service
+
+`triggershell service install` renders a unit file (`src/cli/lib/systemd.ts`) whose `ExecStart`
+line pins the exact `node` binary (`process.execPath`) and the exact, symlink-resolved path to the
+installed CLI (`fs.realpathSync(process.argv[1])`) at install time — necessary because systemd
+services run with a minimal `PATH` that may not include wherever Node actually lives. By default it
+installs a per-user unit (`~/.config/systemd/user/triggershell.service`, no root required); `--system`
+targets `/etc/systemd/system/` instead and prints the `sudo` commands to run if not already root.
+`install` reloads the systemd daemon but does not enable/start the unit itself — that's a separate,
+explicit `systemctl --user enable --now triggershell`, since it's the point where the service
+actually starts listening and running scripts. `triggershell service status`/`uninstall` are thin
+wrappers around `systemctl`; log tailing is just `journalctl --user -u triggershell -f` — not
+reimplemented.
 
 ## Cross-module-graph state
 
 Next compiles Route Handlers and Server Components through its own build/module graph, which is a
-*separate* module instantiation from whatever `server.ts` imports directly via `tsx` at startup —
+_separate_ module instantiation from whatever `server.ts` imports directly via `tsx` at startup —
 even though both run in the same OS process. A plain module-level singleton (e.g. `new Map()` at
 the top of a file) ends up duplicated, one copy per graph, which silently breaks anything that
 needs to be shared across that boundary (the WebSocket subscriber registry, the live-run-handle
@@ -67,10 +110,10 @@ queued → running → succeeded | failed | cancelled | timed_out
 ## Auth
 
 - Session: `iron-session` — a stateless, encrypted+signed cookie (no session-store table).
-- Config is the source of truth for *who* is allowed in; `src/lib/auth/sync.ts` upserts config
+- Config is the source of truth for _who_ is allowed in; `src/lib/auth/sync.ts` upserts config
   users/tokens into SQLite on boot, giving a single DB-backed check path plus `lastLoginAt` tracking.
 - `src/proxy.ts` (Next's Proxy, formerly "Middleware") does a fast, cookie-only redirect for
-  unauthenticated page/API requests — explicitly *not* the real security boundary. Every Route
+  unauthenticated page/API requests — explicitly _not_ the real security boundary. Every Route
   Handler also calls `requireAuth()` itself; this is the actual auth check.
 - The WS `upgrade` handler is outside Next's request pipeline entirely, so it authenticates by hand
   (parsing the cookie header, or a `?token=` query param) via `authenticateUpgrade()`.
@@ -81,4 +124,4 @@ Every server file that reads the config/DB at request time (`getConfig()`, `getD
 `requireAuth()`) sets `export const dynamic = "force-dynamic"`. Without it, `next build` tries to
 statically prerender pages like `/` at build time, which fails because there's no config file to
 read yet (the config only exists at `triggershell start` runtime, in the user's own project
-directory, not `app/`'s).
+directory, not the package's).

docs/CONFIG_REFERENCE.md

@@ -10,13 +10,14 @@ present) into its environment - without overriding any variable already set in t
 secrets referenced via `${VAR}` don't have to be committed alongside the config. `triggershell
 init` scaffolds both files together.
 
-The canonical schema is the Zod schema at `app/src/lib/config/schema.ts` — this document mirrors
+The canonical schema is the Zod schema at `src/lib/config/schema.ts` — this document mirrors
-it. `triggershell validate` runs the Python pre-flight checks below, then that full schema.
+it. `triggershell validate` loads and validates the config directly against the schema below (no
+separate pre-flight step).
 
 ## `server`
 
 | Field      | Type   | Default     | Notes                   |
-|---|---|---|---|
+| ---------- | ------ | ----------- | ----------------------- |
 | `host`     | string | `127.0.0.1` | Bind address            |
 | `port`     | number | `4173`      | 1-65535                 |
 | `basePath` | string | `""`        | Reserved for future use |
@@ -24,7 +25,7 @@ it. `triggershell validate` runs the Python pre-flight checks below, then that f
 ## `auth`
 
 | Field             | Type    | Default | Notes                                                                                                                             |
-|---|---|---|---|
+| ----------------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- |
 | `enabled`         | boolean | `true`  | `false` disables login entirely                                                                                                   |
 | `sessionSecret`   | string  | —       | Required, >= 32 chars, if `enabled`. Reference it via `${TRIGGERSHELL_SESSION_SECRET}` and set the real value in `.env`, not here |
 | `sessionTtlHours` | number  | `12`    | Session cookie lifetime                                                                                                           |
@@ -42,20 +43,20 @@ pass `--inline` to those commands to get the raw hash printed for pasting into t
 ## `database`
 
 | Field  | Type   | Default                         |
-|---|---|---|
+| ------ | ------ | ------------------------------- |
 | `path` | string | `.triggershell/triggershell.db` |
 
 ## `logs`
 
 | Field           | Type   | Default              | Notes                                                       |
-|---|---|---|---|
+| --------------- | ------ | -------------------- | ----------------------------------------------------------- |
 | `dir`           | string | `.triggershell/logs` | One `<runId>.log` file per run                              |
 | `retentionDays` | number | `30`                 | Not yet enforced automatically — prune manually or via cron |
 
 ## `scripts[]`
 
 | Field            | Type     | Default | Notes                                                                                |
-|---|---|---|---|
+| ---------------- | -------- | ------- | ------------------------------------------------------------------------------------ |
 | `id`             | string   | —       | Required, unique, `[a-zA-Z0-9][a-zA-Z0-9_-]*`                                        |
 | `name`           | string   | —       | Required, display name                                                               |
 | `description`    | string   | —       | Optional                                                                             |
@@ -71,7 +72,7 @@ pass `--inline` to those commands to get the raw hash printed for pasting into t
 Common fields on every variable:
 
 | Field         | Type                                | Default            | Notes                                                                                  |
-|---|---|---|---|
+| ------------- | ----------------------------------- | ------------------ | -------------------------------------------------------------------------------------- |
 | `name`        | string                              | —                  | Required, unique per script                                                            |
 | `label`       | string                              | `name`             | Display label                                                                          |
 | `description` | string                              | —                  | Shown as form help text                                                                |
@@ -86,7 +87,7 @@ Common fields on every variable:
 Type-specific fields:
 
 | `type`        | Extra fields                                                                                      |
-|---|---|
+| ------------- | ------------------------------------------------------------------------------------------------- |
 | `string`      | `default?: string`, `pattern?: string` (regex), `minLength?`, `maxLength?`, `multiline?: boolean` |
 | `number`      | `default?: number`, `min?`, `max?`, `step?`                                                       |
 | `boolean`     | `default: boolean` (default `false`)                                                              |
@@ -96,11 +97,11 @@ Type-specific fields:
 ### UI control mapping
 
 | `type`        | Default `control`                        | Valid overrides                                  |
-|---|---|---|
+| ------------- | ---------------------------------------- | ------------------------------------------------ |
 | `string`      | `text` (or `password` if `secret: true`) | `textarea` (needs `multiline: true`), `password` |
 | `number`      | `number`                                 | `slider` (requires both `min` and `max`)         |
 | `boolean`     | `checkbox`                               | `switch`                                         |
-| `enum` | `select` | `radio` |
+| `enum`        | `select`                                 | `radio`, `combobox` (searchable, single-select)  |
 | `multiselect` | `multiselect` (combobox)                 | `checkboxGroup`                                  |
 
 ### `passAs` semantics

examples/scripts/cleanup.js

@@ -10,7 +10,9 @@ const targetDir = getArg("--dir");
 const olderThanDays = getArg("--days");
 const types = getArg("--types");
 
-console.log(`Scanning ${targetDir} for files older than ${olderThanDays} days (types: ${types})`);
+console.log(
+  `Scanning ${targetDir} for files older than ${olderThanDays} days (types: ${types})`,
+);
 if (process.env.CLEANUP_API_KEY) {
   console.log("Using configured external API key.");
 }

examples/triggershell.yml

@@ -72,7 +72,7 @@ scripts:
         label: Notify Slack Channel
         type: string
         required: false
-        pattern: '^#[a-z0-9-]+$'
+        pattern: "^#[a-z0-9-]+$"
         passAs: env
         envName: SLACK_CHANNEL
 

package.json

@@ -1,13 +1,34 @@
 {
-  "name": "app",
+  "name": "triggershell",
   "version": "0.1.0",
-  "private": true,
+  "license": "MIT",
   "type": "module",
   "repository": {
     "type": "git",
-    "url": "https://dev.pivoine.art/valknar/triggershell.git",
+    "url": "https://dev.pivoine.art/valknar/triggershell.git"
-    "directory": "app"
   },
+  "bin": {
+    "triggershell": "bin/triggershell.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "registry": "https://dev.pivoine.art/api/packages/valknar/npm/"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "drizzle",
+    "docs",
+    ".next",
+    "server.ts",
+    "next.config.ts",
+    "next-env.d.ts",
+    "tsconfig.json",
+    "LICENSE"
+  ],
   "scripts": {
     "dev": "tsx watch server.ts",
     "build": "next build",
@@ -15,13 +36,16 @@
     "lint": "eslint",
     "typecheck": "tsc --noEmit",
     "format": "prettier --write .",
-    "validate-config": "tsx scripts/validate-config.ts",
+    "format:check": "prettier --check .",
+    "test": "tsx --test \"src/cli/**/*.test.ts\"",
     "db:generate": "drizzle-kit generate",
-    "db:studio": "drizzle-kit studio"
+    "db:studio": "drizzle-kit studio",
+    "prepack": "rm -rf .next && next build && rm -rf .next/cache"
   },
   "dependencies": {
     "@base-ui/react": "^1.7.0",
     "@hookform/resolvers": "^5.8.0",
+    "@inquirer/prompts": "^8.5.2",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/xterm": "^6.0.0",
     "argon2": "^0.45.1",
@@ -29,6 +53,7 @@
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
+    "commander": "^15.0.0",
     "drizzle-orm": "^0.45.2",
     "execa": "^10.0.1",
     "iron-session": "^8.0.4",
@@ -43,6 +68,7 @@
     "shadcn": "^4.18.0",
     "sonner": "^2.0.8",
     "tailwind-merge": "^3.6.0",
+    "tsx": "^4.23.12",
     "tw-animate-css": "^1.4.0",
     "ws": "^8.21.3",
     "yaml": "^2.9.0",
@@ -63,7 +89,6 @@
     "prettier": "^3.9.6",
     "prettier-plugin-tailwindcss": "^0.8.1",
     "tailwindcss": "^4",
-    "tsx": "^4.23.12",
     "typescript": "^5"
   },
   "packageManager": "pnpm@11.21.0"

pnpm-lock.yaml

@@ -14,6 +14,9 @@ importers:
       '@hookform/resolvers':
         specifier: ^5.8.0
         version: 5.8.0(ajv-formats@2.1.1(ajv@8.20.0))(ajv@8.20.0)(react-hook-form@7.85.0(react@19.2.8))(zod@4.4.3)
+      '@inquirer/prompts':
+        specifier: ^8.5.2
+        version: 8.5.2(@types/node@20.19.43)
       '@xterm/addon-fit':
         specifier: ^0.11.0
         version: 0.11.0
@@ -35,6 +38,9 @@ importers:
       cmdk:
         specifier: ^1.1.1
         version: 1.1.1(@types/react-dom@19.2.4(@types/react@19.2.18))(@types/react@19.2.18)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
+      commander:
+        specifier: ^15.0.0
+        version: 15.0.0
       drizzle-orm:
         specifier: ^0.45.2
         version: 0.45.2(@types/better-sqlite3@9.6.0)(better-sqlite3@13.0.3)
@@ -77,6 +83,9 @@ importers:
       tailwind-merge:
         specifier: ^3.6.0
         version: 3.6.0
+      tsx:
+        specifier: ^4.23.12
+        version: 4.23.12
       tw-animate-css:
         specifier: ^1.4.0
         version: 1.4.0
@@ -132,9 +141,6 @@ importers:
       tailwindcss:
         specifier: ^4
         version: 4.3.3
-      tsx:
-        specifier: ^4.23.12
-        version: 4.23.12
       typescript:
         specifier: ^5
         version: 5.9.3
@@ -1107,6 +1113,140 @@ packages:
     cpu: [x64]
     os: [win32]
 
+  '@inquirer/ansi@2.0.7':
+    resolution: {integrity: sha512-3eTuUO1vH2cZm2ZKHeQxnOqlTi9EfZDGgIe3BL3I4u+rJHocr9Fz86M4fjYABPvFnQG/gGK551HqDiIcETwU6Q==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^20.17.0'}
+
+  '@inquirer/checkbox@5.2.1':
+    resolution: {integrity: sha512-b6xmA/VlTe0ZgDQHDui+Nav470u7u49nRd8/iuhOcQPO9Ch7lGuogydhi2VOmNlZ+zXcM8IcPuNSwQcdJaF/kw==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^20.17.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@inquirer/confirm@6.1.1':
+    resolution: {integrity: sha512-eb8DBZcz/2qHWQda4rk2JiQk5h9QV/cVHi1yjt0f69WFZMRFn0sJTye3EAP8icut8UDMjQPsaH5KbcOogefrFQ==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^20.17.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@inquirer/core@11.2.1':
+    resolution: {integrity: sha512-Qd6GJT1yVyrZZCfN8W2qKF5ApmqryXRhRKCuip8h01x2w/esJQ2XIYc6f9abMIHgKQdBfFTSOdbHRLAhuM09UA==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^20.17.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@inquirer/editor@5.2.2':
+    resolution: {integrity: sha512-ZRVd/oD+sYsUd5zVm0NflqEzlqfYCyHNsqkHl2oWXEUHs12tCbcSFi+wVFEvD8+LGRaMUsVrE7qeo6lSG/S1Vg==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^20.17.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@inquirer/expand@5.1.1':
+    resolution: {integrity: sha512-YmQpenjbFSHAK3sOd44puHh3V1KXXr+JiNpUztoSQ4drLh2rTVzTap/YtlAVu/5xavifIlBfNEzJ/neZJ1a/1g==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^20.17.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@inquirer/external-editor@3.0.3':
+    resolution: {integrity: sha512-6thf5I8q7lZwzGLAxPaaGEREEkZ3nyePPDQ1oyobblxmEE8mqTLguScP7pDjUTAibiyb4hfXl+qjUEJ+di/aNA==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^20.17.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@inquirer/figures@2.0.7':
+    resolution: {integrity: sha512-aJ8TBPOGB6f/2qziPfElISTCEd5XOYTFckA2SGjhNmiKzfK/u4ot3v0DUzGVdUnKjN10EqnnEPck36BkyfLnJw==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^20.17.0'}
+
+  '@inquirer/input@5.1.2':
+    resolution: {integrity: sha512-9K/DDBSQpOyZSkt6sOVP9Vo0TR7atX2kuILsUu0x3wVcVbe97lJwIJKMLdMw25tDYuXl/qp6erT0Xs1rfmcfZg==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^20.17.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@inquirer/number@4.1.1':
+    resolution: {integrity: sha512-XF4IXAbPnGPgw0wsbC/i2tPcyfdZgDpUlhsqU0SfT4IRIGWha6Xm9VRgN5yYxJq+jnyXlfXI/nQ3ulfk0iEICA==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^20.17.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@inquirer/password@5.1.1':
+    resolution: {integrity: sha512-3XBfF7DAsp5qeDsvN5Rd1HmbNokVvEQoUM0QLrRcybC9nX96w3Pbmu7qUsb3IT3J3jBvs2+mTXaKHOUsgHMLzg==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^20.17.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@inquirer/prompts@8.5.2':
+    resolution: {integrity: sha512-IYR/3C/paEVVQYQvdDlFZVjRCJVYHHON0XXMH91KO9GSxs0TdKYWlUdvfQl2EfAHDxUaN3IBffkE/BDTh5nJ6g==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^20.17.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@inquirer/rawlist@5.3.1':
+    resolution: {integrity: sha512-QqdTqQddL3qPX/PPrjobpsO25NZ4dWXgTLenrR445L2ptLEYE6Z+PD5c5CNDJNx4ugRgELAIpSIJxZaO2jJ2Og==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^20.17.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@inquirer/search@4.2.1':
+    resolution: {integrity: sha512-xJj8QWKRSrfKoBIITLZK61dD3zwo0Rz11fgDImku30/Oe81zMdIdGgrLY2h6RkJ+KZ/GhNYIRMKnH/62qBTA5g==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^20.17.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@inquirer/select@5.2.1':
+    resolution: {integrity: sha512-FlDndEUww8m7BfukO2nJa25vhD+H5jxxCv4oGioKqzyWz3nPHhhw4LKdYRSlXuAx7DsdWia7iyaBPKKS95Evfw==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^20.17.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@inquirer/type@4.0.7':
+    resolution: {integrity: sha512-t28inv14nMQ1PhKpsJPY+kEs/c00qzeCOS2gTNRyTjG5d6qsVA2fItxW4hkvGZ5lvanGLdtCzVIx5dwdRpN1+g==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^20.17.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
   '@jridgewell/gen-mapping@0.3.13':
     resolution: {integrity: sha512-2kkt/7niJ6MgEPxF0bYdQ6etZaA+fQvDcLKckhy1yIQOzaoKjBBjSj63/aLVjYE3qhRt5dvM+uUyfCg6UKCBbA==}
 
@@ -1955,6 +2095,9 @@ packages:
   character-reference-invalid@2.0.1:
     resolution: {integrity: sha512-iBZ4F4wRbyORVsu0jPV7gXkOsGYjGHPmAyv+HiHG8gi5PtC9KI2j1+v8/tlibRvjoWX027ypmG/n0HtO5t7unw==}
 
+  chardet@2.2.0:
+    resolution: {integrity: sha512-rddelWYNPRrXq6PtNEN2S3f6t9ILzvqaN5pVgi4kqt9jHQaXIial9PznB5iSPVlQSLNaaH22ItWz3EJtQ10+OA==}
+
   class-variance-authority@0.7.1:
     resolution: {integrity: sha512-Ka+9Trutv7G8M6WT6SeiRWz792K5qEqIGEGzXKhAE6xOWAY6pPH8U+9IY3oCMv6kqTmLsv7Xh/2w2RigkePMsg==}
 
@@ -1966,6 +2109,10 @@ packages:
     resolution: {integrity: sha512-ywqV+5MmyL4E7ybXgKys4DugZbX0FC6LnwrhjuykIjnK9k8OQacQ7axGKnjDXWNhns0xot3bZI5h55H8yo9cJg==}
     engines: {node: '>=6'}
 
+  cli-width@4.1.0:
+    resolution: {integrity: sha512-ouuZd4/dm2Sw5Gmqy6bGyNNNe1qt9RpmxveLSO7KcgsTnU7RXfsw+/bukWGo1abgBiMAic068rclZsO4IWmmxQ==}
+    engines: {node: '>= 12'}
+
   client-only@0.0.1:
     resolution: {integrity: sha512-IV3Ou0jSMzZrd3pZ48nLkT9DA7Ag1pnPzaiQhpW7c3RbcqqzvzzVu+L8gfqMp/8IM2MQtSiqaCxrrcfu8I8rMA==}
 
@@ -2000,6 +2147,10 @@ packages:
     resolution: {integrity: sha512-H+y0Jo/T1RZ9qPP4Eh1pkcQcLRglraJaSLoyOtHxu6AapkjWVCy2Sit1QQ4x3Dng8qDlSsZEet7g5Pq06MvTgw==}
     engines: {node: '>=20'}
 
+  commander@15.0.0:
+    resolution: {integrity: sha512-z67u4ZhzCL/Tydu1lJARtEZYWbWaN7oYLHbsuzocr6y4N6WZAagG3RQ4FW61V1/0+jImpj293XfrcYnd1qxtPg==}
+    engines: {node: '>=22.12.0'}
+
   concat-map@0.0.1:
     resolution: {integrity: sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg==}
 
@@ -2551,9 +2702,18 @@ packages:
   fast-levenshtein@2.0.6:
     resolution: {integrity: sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw==}
 
+  fast-string-truncated-width@3.0.3:
+    resolution: {integrity: sha512-0jjjIEL6+0jag3l2XWWizO64/aZVtpiGE3t0Zgqxv0DPuxiMjvB3M24fCyhZUO4KomJQPj3LTSUnDP3GpdwC0g==}
+
+  fast-string-width@3.0.2:
+    resolution: {integrity: sha512-gX8LrtNEI5hq8DVUfRQMbr5lpaS4nMIWV+7XEbXk2b8kiQIizgnlr12B4dA3ZEx3308ze0O4Q1R+cHts8kyUJg==}
+
   fast-uri@3.1.5:
     resolution: {integrity: sha512-gHwA1O9LDIcKunMKhObS/HimwtehO1nPUECKAu5TpKgaO19fcWEl4bliWe1jWxVFvIXztJjjQ4L8XQ1EU9f7Jw==}
 
+  fast-wrap-ansi@0.2.2:
+    resolution: {integrity: sha512-7F2Fl+TjRSenLqlU3UjSH0iyqopqoZIu7eZVpEirP2g1GtWa2G/ecEmBdgz31+Mxr+ELclgg6sokpSFIQiZ02Q==}
+
   fastq@1.20.1:
     resolution: {integrity: sha512-GGToxJ/w1x32s/D2EKND7kTil4n8OVk/9mycTc4VDza13lOvpUZTGX3mFSCtV9ksdGBVzvsyAVLM6mHFThxXxw==}
 
@@ -3381,6 +3541,10 @@ packages:
   ms@2.1.3:
     resolution: {integrity: sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==}
 
+  mute-stream@3.0.0:
+    resolution: {integrity: sha512-dkEJPVvun4FryqBmZ5KhDo0K9iDXAwn08tMLDinNdRBNPcYEDiWYysLcc6k3mjTMlbP9KyylvRpd4wFtwrT9rw==}
+    engines: {node: ^20.17.0 || >=22.9.0}
+
   nanoid@3.3.18:
     resolution: {integrity: sha512-DTg4MJbGMWkfi6VZFdNt2/caMbQy4Ou+Op/hJQvGEWcnVfoA1QA+xzRKAzw9jD6+GVOOeYr/mIcuDSdug6F6+w==}
     engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1}
@@ -5067,6 +5231,125 @@ snapshots:
   '@img/sharp-win32-x64@0.35.3':
     optional: true
 
+  '@inquirer/ansi@2.0.7': {}
+
+  '@inquirer/checkbox@5.2.1(@types/node@20.19.43)':
+    dependencies:
+      '@inquirer/ansi': 2.0.7
+      '@inquirer/core': 11.2.1(@types/node@20.19.43)
+      '@inquirer/figures': 2.0.7
+      '@inquirer/type': 4.0.7(@types/node@20.19.43)
+    optionalDependencies:
+      '@types/node': 20.19.43
+
+  '@inquirer/confirm@6.1.1(@types/node@20.19.43)':
+    dependencies:
+      '@inquirer/core': 11.2.1(@types/node@20.19.43)
+      '@inquirer/type': 4.0.7(@types/node@20.19.43)
+    optionalDependencies:
+      '@types/node': 20.19.43
+
+  '@inquirer/core@11.2.1(@types/node@20.19.43)':
+    dependencies:
+      '@inquirer/ansi': 2.0.7
+      '@inquirer/figures': 2.0.7
+      '@inquirer/type': 4.0.7(@types/node@20.19.43)
+      cli-width: 4.1.0
+      fast-wrap-ansi: 0.2.2
+      mute-stream: 3.0.0
+      signal-exit: 4.1.0
+    optionalDependencies:
+      '@types/node': 20.19.43
+
+  '@inquirer/editor@5.2.2(@types/node@20.19.43)':
+    dependencies:
+      '@inquirer/core': 11.2.1(@types/node@20.19.43)
+      '@inquirer/external-editor': 3.0.3(@types/node@20.19.43)
+      '@inquirer/type': 4.0.7(@types/node@20.19.43)
+    optionalDependencies:
+      '@types/node': 20.19.43
+
+  '@inquirer/expand@5.1.1(@types/node@20.19.43)':
+    dependencies:
+      '@inquirer/core': 11.2.1(@types/node@20.19.43)
+      '@inquirer/type': 4.0.7(@types/node@20.19.43)
+    optionalDependencies:
+      '@types/node': 20.19.43
+
+  '@inquirer/external-editor@3.0.3(@types/node@20.19.43)':
+    dependencies:
+      chardet: 2.2.0
+      iconv-lite: 0.7.3
+    optionalDependencies:
+      '@types/node': 20.19.43
+
+  '@inquirer/figures@2.0.7': {}
+
+  '@inquirer/input@5.1.2(@types/node@20.19.43)':
+    dependencies:
+      '@inquirer/core': 11.2.1(@types/node@20.19.43)
+      '@inquirer/type': 4.0.7(@types/node@20.19.43)
+    optionalDependencies:
+      '@types/node': 20.19.43
+
+  '@inquirer/number@4.1.1(@types/node@20.19.43)':
+    dependencies:
+      '@inquirer/core': 11.2.1(@types/node@20.19.43)
+      '@inquirer/type': 4.0.7(@types/node@20.19.43)
+    optionalDependencies:
+      '@types/node': 20.19.43
+
+  '@inquirer/password@5.1.1(@types/node@20.19.43)':
+    dependencies:
+      '@inquirer/ansi': 2.0.7
+      '@inquirer/core': 11.2.1(@types/node@20.19.43)
+      '@inquirer/type': 4.0.7(@types/node@20.19.43)
+    optionalDependencies:
+      '@types/node': 20.19.43
+
+  '@inquirer/prompts@8.5.2(@types/node@20.19.43)':
+    dependencies:
+      '@inquirer/checkbox': 5.2.1(@types/node@20.19.43)
+      '@inquirer/confirm': 6.1.1(@types/node@20.19.43)
+      '@inquirer/editor': 5.2.2(@types/node@20.19.43)
+      '@inquirer/expand': 5.1.1(@types/node@20.19.43)
+      '@inquirer/input': 5.1.2(@types/node@20.19.43)
+      '@inquirer/number': 4.1.1(@types/node@20.19.43)
+      '@inquirer/password': 5.1.1(@types/node@20.19.43)
+      '@inquirer/rawlist': 5.3.1(@types/node@20.19.43)
+      '@inquirer/search': 4.2.1(@types/node@20.19.43)
+      '@inquirer/select': 5.2.1(@types/node@20.19.43)
+    optionalDependencies:
+      '@types/node': 20.19.43
+
+  '@inquirer/rawlist@5.3.1(@types/node@20.19.43)':
+    dependencies:
+      '@inquirer/core': 11.2.1(@types/node@20.19.43)
+      '@inquirer/type': 4.0.7(@types/node@20.19.43)
+    optionalDependencies:
+      '@types/node': 20.19.43
+
+  '@inquirer/search@4.2.1(@types/node@20.19.43)':
+    dependencies:
+      '@inquirer/core': 11.2.1(@types/node@20.19.43)
+      '@inquirer/figures': 2.0.7
+      '@inquirer/type': 4.0.7(@types/node@20.19.43)
+    optionalDependencies:
+      '@types/node': 20.19.43
+
+  '@inquirer/select@5.2.1(@types/node@20.19.43)':
+    dependencies:
+      '@inquirer/ansi': 2.0.7
+      '@inquirer/core': 11.2.1(@types/node@20.19.43)
+      '@inquirer/figures': 2.0.7
+      '@inquirer/type': 4.0.7(@types/node@20.19.43)
+    optionalDependencies:
+      '@types/node': 20.19.43
+
+  '@inquirer/type@4.0.7(@types/node@20.19.43)':
+    optionalDependencies:
+      '@types/node': 20.19.43
+
   '@jridgewell/gen-mapping@0.3.13':
     dependencies:
       '@jridgewell/sourcemap-codec': 1.5.5
@@ -5851,6 +6134,8 @@ snapshots:
 
   character-reference-invalid@2.0.1: {}
 
+  chardet@2.2.0: {}
+
   class-variance-authority@0.7.1:
     dependencies:
       clsx: 2.1.1
@@ -5861,6 +6146,8 @@ snapshots:
 
   cli-spinners@2.9.2: {}
 
+  cli-width@4.1.0: {}
+
   client-only@0.0.1: {}
 
   clsx@2.1.1: {}
@@ -5891,6 +6178,8 @@ snapshots:
 
   commander@14.0.3: {}
 
+  commander@15.0.0: {}
+
   concat-map@0.0.1: {}
 
   conf@10.2.0:
@@ -6610,8 +6899,18 @@ snapshots:
 
   fast-levenshtein@2.0.6: {}
 
+  fast-string-truncated-width@3.0.3: {}
+
+  fast-string-width@3.0.2:
+    dependencies:
+      fast-string-truncated-width: 3.0.3
+
   fast-uri@3.1.5: {}
 
+  fast-wrap-ansi@0.2.2:
+    dependencies:
+      fast-string-width: 3.0.2
+
   fastq@1.20.1:
     dependencies:
       reusify: 1.1.0
@@ -7581,6 +7880,8 @@ snapshots:
 
   ms@2.1.3: {}
 
+  mute-stream@3.0.0: {}
+
   nanoid@3.3.18: {}
 
   napi-postinstall@0.3.4: {}

pnpm-workspace.yaml

@@ -2,5 +2,4 @@ allowBuilds:
   argon2: true
   better-sqlite3: true
   esbuild: true
-  sharp: false
   unrs-resolver: false

pyproject.toml

@@ -1,48 +0,0 @@
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[project]
-name = "triggershell"
-version = "0.1.0"
-description = "CLI launcher for the TriggerShell web app - run configured shell scripts from a browser."
-readme = "README.md"
-requires-python = ">=3.9"
-license = "MIT"
-authors = [{ name = "TriggerShell contributors" }]
-dependencies = [
-  "typer>=0.12",
-  "rich>=13.7",
-  "pyyaml>=6.0",
-  "argon2-cffi>=23.1",
-  "python-dotenv>=1.0",
-]
-
-[project.urls]
-Repository = "https://dev.pivoine.art/valknar/triggershell.git"
-
-[project.scripts]
-triggershell = "triggershell.cli:app"
-
-[tool.hatch.build.targets.wheel]
-packages = ["triggershell"]
-
-[tool.hatch.build.targets.wheel.force-include]
-"app" = "triggershell/_app"
-
-[tool.hatch.build.targets.sdist]
-include = ["triggershell", "app", "README.md"]
-exclude = ["app/node_modules", "app/.next", "app/drizzle.config.ts.bak"]
-
-[tool.ruff]
-line-length = 120
-target-version = "py39"
-
-[tool.ruff.lint]
-select = ["E", "F", "I", "UP", "B"]
-# B008: typer's `= typer.Option(...)` / `= typer.Argument(...)` defaults are the intended API, not a bug.
-# UP045: `X | None` needs 3.10 at runtime for typer's introspection; this project targets 3.9+.
-ignore = ["B008", "UP045"]
-
-[dependency-groups]
-dev = ["ruff>=0.6", "pytest>=8.0"]

server.ts

@@ -1,5 +1,7 @@
 import "./src/bootstrap/async-local-storage-polyfill";
 import { createServer } from "node:http";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 import next from "next";
 import { WebSocketServer } from "ws";
 import { getConfig } from "./src/lib/config/load";
@@ -19,7 +21,14 @@ migrateOnBoot();
 syncAuthFromConfig();
 reconcileOrphanedRuns();
 
-const app = next({ dev, hostname, port });
+// `dir` must be this file's own directory, not `process.cwd()` - when launched by the installed
+// `triggershell` CLI, the working directory is wherever the user's config lives, not the package.
+const dir = path.dirname(fileURLToPath(import.meta.url));
+// Exposed via `process.env` (not just the local `dir` const) so Route Handlers/Server Components -
+// compiled through Next's own module graph, separate from this file's - can find it too. See
+// `docs.ts`'s use of this and the `globalThis` comment in `runner/events.ts` for the same reasoning.
+process.env.TRIGGERSHELL_APP_ROOT = dir;
+const app = next({ dev, dir, hostname, port });
 const handle = app.getRequestHandler();
 
 app.prepare().then(() => {

src/app/(app)/docs/[slug]/page.tsx

@@ -27,7 +27,7 @@ export default async function DocPage({ params }: DocPageProps) {
   if (content === null) notFound();
 
   return (
-    <div className="mx-auto flex max-w-3xl flex-col gap-6">
+    <div className="mx-auto flex max-w-5xl flex-col gap-6">
       <Link
         href="/docs"
         className="text-muted-foreground hover:text-foreground flex w-fit items-center gap-1 text-sm"

src/app/(app)/docs/page.tsx

@@ -11,11 +11,13 @@ export const metadata: Metadata = { title: "Docs" };
 export default function DocsIndexPage() {
   return (
     <div className="flex flex-col gap-4">
-      <h1 className="text-2xl font-semibold tracking-tight">Docs</h1>
+      <h1 className="font-heading text-2xl font-semibold tracking-tight">
+        Docs
+      </h1>
       <div className="grid gap-3 sm:grid-cols-2">
         {DOCS.map((doc) => (
           <Link key={doc.slug} href={`/docs/${doc.slug}`}>
-            <Card className="hover:border-foreground/30 h-full transition-colors">
+            <Card className="hover:border-primary/50 h-full transition-colors">
               <CardHeader className="flex flex-row items-start justify-between gap-2 space-y-0">
                 <div className="flex items-center gap-2">
                   <BookOpen className="text-muted-foreground size-4.5 shrink-0" />

src/app/(app)/not-found.tsx

@@ -0,0 +1,5 @@
+import { NotFoundContent } from "@/components/layout/not-found-content";
+
+export default function NotFound() {
+  return <NotFoundContent />;
+}

src/app/(app)/page.tsx

@@ -13,21 +13,31 @@ export default function DashboardPage() {
 
   if (config.scripts.length === 0) {
     return (
-      <div className="text-muted-foreground py-24 text-center">
+      <div className="flex flex-col items-center gap-2 py-24 text-center">
-        No scripts configured yet. Add entries under{" "}
+        <PlayCircle className="text-muted-foreground/50 mb-2 size-8" />
-        <code className="bg-muted rounded px-1.5 py-0.5">scripts:</code> in your
+        <h1 className="font-heading text-lg font-semibold tracking-tight">
-        config file.
+          No scripts yet
+        </h1>
+        <p className="text-muted-foreground max-w-sm text-sm">
+          Add entries under{" "}
+          <code className="bg-muted rounded px-1.5 py-0.5 font-mono text-xs">
+            scripts:
+          </code>{" "}
+          in your config file to see them here.
+        </p>
       </div>
     );
   }
 
   return (
     <div className="flex flex-col gap-4">
-      <h1 className="text-2xl font-semibold tracking-tight">Scripts</h1>
+      <h1 className="font-heading text-2xl font-semibold tracking-tight">
+        Scripts
+      </h1>
       <div className="grid gap-3 sm:grid-cols-2">
         {config.scripts.map((script) => (
           <Link key={script.id} href={`/scripts/${script.id}`}>
-            <Card className="hover:border-foreground/30 h-full transition-colors">
+            <Card className="hover:border-primary/50 h-full transition-colors">
               <CardHeader className="flex flex-row items-start justify-between gap-2 space-y-0">
                 <div className="flex items-center gap-2">
                   <PlayCircle className="text-muted-foreground size-4.5 shrink-0" />

src/app/(app)/runs/[runId]/page.tsx

@@ -66,12 +66,12 @@ export default async function RunDetailPage({ params }: RunDetailPageProps) {
       }));
 
   return (
-    <div className="mx-auto flex max-w-2xl flex-col gap-4">
+    <div className="mx-auto flex max-w-5xl flex-col gap-4">
       <Card>
         <CardHeader>
           <CardTitle>{run.scriptName}</CardTitle>
           {script && (
-            <CardAction>
+            <CardAction className="row-span-1">
               <Link
                 href={`/scripts/${run.scriptId}?fromRun=${run.id}`}
                 className={buttonVariants({ variant: "outline", size: "sm" })}
@@ -81,39 +81,45 @@ export default async function RunDetailPage({ params }: RunDetailPageProps) {
               </Link>
             </CardAction>
           )}
-          <dl className="text-muted-foreground grid grid-cols-2 gap-x-4 gap-y-1 text-xs sm:grid-cols-3">
+          <dl className="text-muted-foreground col-span-2 grid grid-cols-2 gap-x-4 gap-y-2 text-xs sm:grid-cols-3">
             <div>
-              <dt className="font-medium">Triggered by</dt>
+              <dt className="font-mono text-[0.7rem] font-medium tracking-widest uppercase">
-              <dd>{run.triggeredBy}</dd>
+                Triggered by
+              </dt>
+              <dd className="font-mono">{run.triggeredBy}</dd>
             </div>
             <div>
-              <dt className="font-medium">Started</dt>
+              <dt className="font-mono text-[0.7rem] font-medium tracking-widest uppercase">
-              <dd>
+                Started
+              </dt>
+              <dd className="font-mono">
                 {run.startedAt ? new Date(run.startedAt).toLocaleString() : "-"}
               </dd>
             </div>
             <div>
-              <dt className="font-medium">Run ID</dt>
+              <dt className="font-mono text-[0.7rem] font-medium tracking-widest uppercase">
+                Run ID
+              </dt>
               <dd className="truncate font-mono">{run.id}</dd>
             </div>
           </dl>
         </CardHeader>
         <CardContent className="flex flex-col gap-4">
           <div className="flex flex-col gap-1.5">
-            <span className="text-muted-foreground text-xs font-medium">
+            <span className="text-muted-foreground font-mono text-[0.7rem] font-medium tracking-widest uppercase">
               Command
             </span>
-            <pre className="bg-muted overflow-x-auto rounded-md p-3 font-mono text-xs whitespace-pre">
+            <pre className="bg-muted border-primary/30 overflow-x-auto rounded-md border-l-2 p-3 font-mono text-xs whitespace-pre">
               {run.resolvedCommand}
             </pre>
           </div>
 
           {variableEntries.length > 0 && (
             <div className="flex flex-col gap-1.5">
-              <span className="text-muted-foreground text-xs font-medium">
+              <span className="text-muted-foreground font-mono text-[0.7rem] font-medium tracking-widest uppercase">
                 Variables
               </span>
-              <dl className="grid gap-x-6 gap-y-2 rounded-md border p-3 text-xs sm:grid-cols-2">
+              <dl className="grid gap-x-6 gap-y-2 rounded-md border p-3 text-xs sm:grid-cols-2 lg:grid-cols-3">
                 {variableEntries.map(({ key, label, value }) => (
                   <div key={key} className="flex flex-col gap-0.5">
                     <dt className="text-muted-foreground">{label}</dt>

src/app/(app)/runs/page.tsx

@@ -2,11 +2,20 @@ export const dynamic = "force-dynamic";
 
 import type { Metadata } from "next";
 import Link from "next/link";
-import { ArrowDown, ArrowUp, ArrowUpDown, ChevronLeft, ChevronRight } from "lucide-react";
+import {
+  ArrowDown,
+  ArrowUp,
+  ArrowUpDown,
+  ChevronLeft,
+  ChevronRight,
+} from "lucide-react";
 import { and, asc, desc, eq, like, or, sql, type SQL } from "drizzle-orm";
 import { getDb } from "@/lib/db/client";
 import { runs } from "@/lib/db/schema";
-import { RunStatusBadge, runStatusLabels } from "@/components/runs/run-status-badge";
+import {
+  RunStatusBadge,
+  runStatusLabels,
+} from "@/components/runs/run-status-badge";
 import { RunsToolbar } from "@/components/runs/runs-toolbar";
 import { buttonVariants } from "@/components/ui/button";
 import { cn } from "@/lib/utils";
@@ -89,7 +98,9 @@ export default async function RunsPage({ searchParams }: RunsPageProps) {
     );
   }
   if (statusFilter !== "all" && statusFilter in runStatusLabels) {
-    conditions.push(eq(runs.status, statusFilter as keyof typeof runStatusLabels));
+    conditions.push(
+      eq(runs.status, statusFilter as keyof typeof runStatusLabels),
+    );
   }
   if (scriptFilter !== "all") {
     conditions.push(eq(runs.scriptId, scriptFilter));
@@ -161,11 +172,16 @@ export default async function RunsPage({ searchParams }: RunsPageProps) {
 
   return (
     <div className="flex flex-col gap-4">
-      <h1 className="text-2xl font-semibold tracking-tight">Run History</h1>
+      <h1 className="font-heading text-2xl font-semibold tracking-tight">
+        Run History
+      </h1>
       <RunsToolbar scripts={scripts} />
       {rows.length === 0 ? (
         <p className="text-muted-foreground py-12 text-center">
-          {total === 0 && !search && statusFilter === "all" && scriptFilter === "all"
+          {total === 0 &&
+          !search &&
+          statusFilter === "all" &&
+          scriptFilter === "all"
             ? "No runs yet."
             : "No runs match these filters."}
         </p>
@@ -177,7 +193,9 @@ export default async function RunsPage({ searchParams }: RunsPageProps) {
                 <TableRow>
                   <TableHead>{sortHeader("script", "Script")}</TableHead>
                   <TableHead>{sortHeader("status", "Status")}</TableHead>
-                  <TableHead>{sortHeader("triggeredBy", "Triggered by")}</TableHead>
+                  <TableHead>
+                    {sortHeader("triggeredBy", "Triggered by")}
+                  </TableHead>
                   <TableHead>{sortHeader("started", "Started")}</TableHead>
                   <TableHead>{sortHeader("duration", "Duration")}</TableHead>
                 </TableRow>
@@ -196,15 +214,15 @@ export default async function RunsPage({ searchParams }: RunsPageProps) {
                     <TableCell>
                       <RunStatusBadge status={run.status} />
                     </TableCell>
-                    <TableCell className="text-muted-foreground">
+                    <TableCell className="text-muted-foreground font-mono text-xs">
                       {run.triggeredBy}
                     </TableCell>
-                    <TableCell className="text-muted-foreground">
+                    <TableCell className="text-muted-foreground font-mono text-xs">
                       {run.startedAt
                         ? new Date(run.startedAt).toLocaleString()
                         : "-"}
                     </TableCell>
-                    <TableCell className="text-muted-foreground">
+                    <TableCell className="text-muted-foreground font-mono text-xs">
                       {formatDuration(run.startedAt, run.endedAt)}
                     </TableCell>
                   </TableRow>

src/app/(app)/scripts/[scriptId]/page.tsx

@@ -55,7 +55,7 @@ export default async function ScriptPage({
   }
 
   return (
-    <div className="mx-auto max-w-2xl">
+    <div className="mx-auto max-w-5xl">
       <Card>
         <CardHeader>
           <CardTitle>{script.name}</CardTitle>

src/app/globals.css

@@ -0,0 +1,154 @@
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "shadcn/tailwind.css";
+@plugin "@tailwindcss/typography";
+
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --font-sans: var(--font-sans);
+  --font-mono: var(--font-mono);
+  --font-heading: var(--font-display);
+  --color-status-queued: var(--status-queued);
+  --color-status-running: var(--status-running);
+  --color-status-succeeded: var(--status-succeeded);
+  --color-status-failed: var(--status-failed);
+  --color-status-cancelled: var(--status-cancelled);
+  --color-status-warn: var(--status-warn);
+  --color-sidebar-ring: var(--sidebar-ring);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar: var(--sidebar);
+  --color-chart-5: var(--chart-5);
+  --color-chart-4: var(--chart-4);
+  --color-chart-3: var(--chart-3);
+  --color-chart-2: var(--chart-2);
+  --color-chart-1: var(--chart-1);
+  --color-ring: var(--ring);
+  --color-input: var(--input);
+  --color-border: var(--border);
+  --color-destructive: var(--destructive);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-accent: var(--accent);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-muted: var(--muted);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-secondary: var(--secondary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-primary: var(--primary);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-popover: var(--popover);
+  --color-card-foreground: var(--card-foreground);
+  --color-card: var(--card);
+  --radius-sm: calc(var(--radius) * 0.6);
+  --radius-md: calc(var(--radius) * 0.8);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) * 1.4);
+  --radius-2xl: calc(var(--radius) * 1.8);
+  --radius-3xl: calc(var(--radius) * 2.2);
+  --radius-4xl: calc(var(--radius) * 2.6);
+}
+
+/*
+ * Palette - "instrument panel": cool graphite ink/paper with a warm brass signal accent.
+ * The brass tone doubles as the "running" status color, so a live run literally lights the UI
+ * up with the brand color - see run-status-badge.tsx and run-terminal.tsx.
+ */
+:root {
+  --background: #f5f6f7;
+  --foreground: #15171a;
+  --card: #ffffff;
+  --card-foreground: #15171a;
+  --popover: #ffffff;
+  --popover-foreground: #15171a;
+  --primary: #c8842e;
+  --primary-foreground: #17130a;
+  --secondary: #ececee;
+  --secondary-foreground: #15171a;
+  --muted: #ececee;
+  --muted-foreground: #6b7280;
+  --accent: #ececee;
+  --accent-foreground: #15171a;
+  --destructive: #b3402e;
+  --border: #dfe1e3;
+  --input: #dfe1e3;
+  --ring: #c8842e;
+  --status-queued: #6b7280;
+  --status-running: #c8842e;
+  --status-succeeded: #3f8f5f;
+  --status-failed: #b3402e;
+  --status-cancelled: #6b7280;
+  --status-warn: #8a7530;
+  --chart-1: #c8842e;
+  --chart-2: #3f8f5f;
+  --chart-3: #6b7280;
+  --chart-4: #8a7530;
+  --chart-5: #b3402e;
+  --radius: 0.5rem;
+  --sidebar: #f5f6f7;
+  --sidebar-foreground: #15171a;
+  --sidebar-primary: #c8842e;
+  --sidebar-primary-foreground: #17130a;
+  --sidebar-accent: #ececee;
+  --sidebar-accent-foreground: #15171a;
+  --sidebar-border: #dfe1e3;
+  --sidebar-ring: #c8842e;
+}
+
+.dark {
+  --background: #14161a;
+  --foreground: #edeef0;
+  --card: #1b1e23;
+  --card-foreground: #edeef0;
+  --popover: #1b1e23;
+  --popover-foreground: #edeef0;
+  --primary: #e9a857;
+  --primary-foreground: #1a1305;
+  --secondary: #23262c;
+  --secondary-foreground: #edeef0;
+  --muted: #23262c;
+  --muted-foreground: #9aa0a8;
+  --accent: #23262c;
+  --accent-foreground: #edeef0;
+  --destructive: #e2685a;
+  --border: oklch(1 0 0 / 10%);
+  --input: oklch(1 0 0 / 14%);
+  --ring: #e9a857;
+  --status-queued: #9aa0a8;
+  --status-running: #e9a857;
+  --status-succeeded: #5fb983;
+  --status-failed: #e2685a;
+  --status-cancelled: #9aa0a8;
+  --status-warn: #c9a344;
+  --chart-1: #e9a857;
+  --chart-2: #5fb983;
+  --chart-3: #9aa0a8;
+  --chart-4: #c9a344;
+  --chart-5: #e2685a;
+  --sidebar: #1b1e23;
+  --sidebar-foreground: #edeef0;
+  --sidebar-primary: #e9a857;
+  --sidebar-primary-foreground: #1a1305;
+  --sidebar-accent: #23262c;
+  --sidebar-accent-foreground: #edeef0;
+  --sidebar-border: oklch(1 0 0 / 10%);
+  --sidebar-ring: #e9a857;
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+  html {
+    @apply font-sans;
+  }
+}

src/app/icon.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24">
+  <style>
+    rect { fill: #15171a; }
+    path { stroke: #c8842e; }
+    @media (prefers-color-scheme: dark) {
+      path { stroke: #e9a857; }
+    }
+  </style>
+  <rect width="24" height="24" rx="5" />
+  <path d="M12 19h8" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" fill="none" />
+  <path d="m4 17 6-6-6-6" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" fill="none" />
+</svg>

src/app/layout.tsx

@@ -1,18 +1,32 @@
 import type { Metadata } from "next";
-import { Geist, Geist_Mono } from "next/font/google";
+import {
+  Bricolage_Grotesque,
+  IBM_Plex_Mono,
+  IBM_Plex_Sans,
+} from "next/font/google";
 import { ThemeProvider } from "next-themes";
 import { TooltipProvider } from "@/components/ui/tooltip";
 import { Toaster } from "@/components/ui/sonner";
 import "./globals.css";
 
-const geistSans = Geist({
+// Display face for page titles and card headings (wired via --font-heading in globals.css) - used
-  variable: "--font-geist-sans",
+// with restraint, never for body copy. Body/UI text and technical data (run IDs, commands,
+// timestamps) share the IBM Plex family so the two registers still read as one system.
+const displayFont = Bricolage_Grotesque({
+  variable: "--font-display",
   subsets: ["latin"],
 });
 
-const geistMono = Geist_Mono({
+const sansFont = IBM_Plex_Sans({
-  variable: "--font-geist-mono",
+  variable: "--font-sans",
   subsets: ["latin"],
+  weight: ["400", "500", "600", "700"],
+});
+
+const monoFont = IBM_Plex_Mono({
+  variable: "--font-mono",
+  subsets: ["latin"],
+  weight: ["400", "500", "600"],
 });
 
 export const metadata: Metadata = {
@@ -31,7 +45,7 @@ export default function RootLayout({
   return (
     <html
       lang="en"
-      className={`${geistSans.variable} ${geistMono.variable} h-full antialiased`}
+      className={`${displayFont.variable} ${sansFont.variable} ${monoFont.variable} h-full antialiased`}
       suppressHydrationWarning
     >
       <body

src/app/login/login-form.tsx

@@ -50,7 +50,7 @@ export function LoginForm() {
     <Card className="w-full max-w-sm">
       <CardHeader>
         <div className="flex items-center gap-2">
-          <Terminal className="size-5" />
+          <Terminal className="text-primary size-5" />
           <CardTitle>TriggerShell</CardTitle>
         </div>
         <CardDescription>

src/app/not-found.tsx

@@ -0,0 +1,5 @@
+import { NotFoundContent } from "@/components/layout/not-found-content";
+
+export default function NotFound() {
+  return <NotFoundContent />;
+}

src/cli/commands/doctor.ts

@@ -0,0 +1,47 @@
+import fs from "node:fs";
+import { ConfigError, loadConfig } from "../../lib/config/load";
+import { isPortFree } from "../lib/network";
+import { resolveConfigPath } from "../lib/paths";
+
+export interface DoctorOptions {
+  config?: string;
+}
+
+export async function doctorCommand(opts: DoctorOptions): Promise<void> {
+  const rows: [string, string][] = [];
+
+  rows.push(["Node.js", process.version]);
+
+  const configPath = resolveConfigPath(opts.config);
+  const exists = fs.existsSync(configPath);
+  rows.push([
+    "Config path",
+    `${configPath} ${exists ? "(exists)" : "(not found)"}`,
+  ]);
+
+  if (exists) {
+    try {
+      const { config } = loadConfig(configPath);
+      const portFree = await isPortFree(config.server.host, config.server.port);
+      rows.push([
+        "Port available",
+        portFree
+          ? "yes"
+          : `no (${config.server.host}:${config.server.port} in use)`,
+      ]);
+      rows.push(["Scripts configured", String(config.scripts.length)]);
+      rows.push(["Auth enabled", String(config.auth.enabled)]);
+    } catch (error) {
+      if (error instanceof ConfigError) {
+        rows.push(["Config", error.message]);
+      } else {
+        throw error;
+      }
+    }
+  }
+
+  const labelWidth = Math.max(...rows.map(([label]) => label.length));
+  for (const [label, value] of rows) {
+    console.log(`${label.padEnd(labelWidth)}  ${value}`);
+  }
+}

src/cli/commands/init.ts

@@ -0,0 +1,62 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { resolveAppRoot } from "../lib/paths";
+
+const DEFAULT_CONFIG_NAME = "triggershell.yml";
+
+export interface InitOptions {
+  port: number;
+  auth: boolean;
+  force: boolean;
+}
+
+export async function initCommand(
+  targetPath: string | undefined,
+  opts: InitOptions,
+): Promise<void> {
+  const targetDir = path.resolve(process.cwd(), targetPath ?? ".");
+  fs.mkdirSync(targetDir, { recursive: true });
+  const configPath = path.join(targetDir, DEFAULT_CONFIG_NAME);
+
+  if (fs.existsSync(configPath) && !opts.force) {
+    console.error(`${configPath} already exists. Use --force to overwrite.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const templatePath = path.join(
+    resolveAppRoot(),
+    "templates",
+    DEFAULT_CONFIG_NAME,
+  );
+  const template = fs.readFileSync(templatePath, "utf-8");
+  const rendered = template
+    .replace("__PORT__", String(opts.port))
+    .replace("__AUTH_ENABLED__", opts.auth ? "true" : "false");
+  fs.writeFileSync(configPath, rendered);
+  console.log(`Created ${configPath}`);
+
+  const envPath = path.join(targetDir, ".env");
+  if (opts.auth) {
+    if (fs.existsSync(envPath)) {
+      console.log(
+        `${envPath} already exists - make sure it sets TRIGGERSHELL_SESSION_SECRET (>= 32 chars).`,
+      );
+    } else {
+      const sessionSecret = crypto.randomBytes(32).toString("hex");
+      fs.writeFileSync(
+        envPath,
+        `TRIGGERSHELL_SESSION_SECRET=${sessionSecret}\n`,
+      );
+      console.log(`Created ${envPath} (keep this out of version control)`);
+    }
+    console.log(
+      "\nAuth is enabled but no users are configured yet. Add one with:",
+    );
+    console.log(`  triggershell users add <username> --config ${configPath}`);
+  }
+
+  console.log("\nStart the app with:");
+  console.log(`  triggershell start --config ${configPath}`);
+}

src/cli/commands/run.ts

@@ -0,0 +1,285 @@
+import path from "node:path";
+import { eq } from "drizzle-orm";
+import { WebSocket } from "ws";
+import { ConfigError, loadConfig } from "../../lib/config/load";
+import { defaultValuesForScript } from "../../lib/config/defaults";
+import { getDb, migrateOnBoot } from "../../lib/db/client";
+import { runs, type RunStatus } from "../../lib/db/schema";
+import { startRun, reconcileOrphanedRuns } from "../../lib/runner/engine";
+import { cancelRun } from "../../lib/runner/registry";
+import { runEvents } from "../../lib/runner/events";
+import { readLogTail } from "../../lib/runner/log-file";
+import { buildVariableSchema } from "../../lib/validation/variable-schema";
+import type { ServerMessage } from "../../lib/ws/protocol";
+import { loadDotenv } from "../lib/env-file";
+import { isServerReachable } from "../lib/network";
+import { resolveConfigPath } from "../lib/paths";
+import { coerceVariables, parseVarFlags } from "../lib/variables";
+
+export interface RunOptions {
+  config?: string;
+  var: string[];
+  host?: string;
+  port?: number;
+  token?: string;
+  local?: boolean;
+  remote?: boolean;
+  wait: boolean;
+}
+
+const NON_TERMINAL: RunStatus[] = ["queued", "running"];
+
+function exitCodeFor(status: RunStatus): number {
+  return status === "succeeded" ? 0 : 1;
+}
+
+export async function runCommand(
+  scriptId: string,
+  opts: RunOptions,
+): Promise<void> {
+  const configPath = resolveConfigPath(opts.config);
+  loadDotenv(path.join(path.dirname(configPath), ".env"));
+
+  let loaded;
+  try {
+    loaded = loadConfig(configPath);
+  } catch (error) {
+    if (error instanceof ConfigError) {
+      console.error(`Config error: ${error.message}`);
+      for (const issue of error.issues) console.error(`  - ${issue}`);
+      process.exitCode = 1;
+      return;
+    }
+    throw error;
+  }
+
+  const { config } = loaded;
+  const script = config.scripts.find((s) => s.id === scriptId);
+  if (!script) {
+    console.error(`No script '${scriptId}' configured.`);
+    if (config.scripts.length > 0) {
+      console.error(
+        `Available scripts: ${config.scripts.map((s) => s.id).join(", ")}`,
+      );
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  let variables: Record<string, unknown>;
+  try {
+    const grouped = parseVarFlags(opts.var);
+    const raw = {
+      ...defaultValuesForScript(script.variables),
+      ...coerceVariables(script.variables, grouped),
+    };
+    const parsed = buildVariableSchema(script).safeParse(raw);
+    if (!parsed.success) {
+      console.error("Validation failed:");
+      for (const [field, issues] of Object.entries(
+        parsed.error.flatten().fieldErrors,
+      )) {
+        console.error(`  ${field}: ${(issues ?? []).join(", ")}`);
+      }
+      process.exitCode = 1;
+      return;
+    }
+    variables = parsed.data;
+  } catch (error) {
+    console.error((error as Error).message);
+    process.exitCode = 1;
+    return;
+  }
+
+  const host = opts.host ?? config.server.host;
+  const port = opts.port ?? config.server.port;
+  const url = `http://${host}:${port}`;
+  const token = opts.token ?? process.env.TRIGGERSHELL_API_TOKEN;
+
+  if (opts.local && opts.remote) {
+    console.error("--local and --remote can't be used together.");
+    process.exitCode = 1;
+    return;
+  }
+
+  let useRemote: boolean;
+  if (opts.remote) {
+    if (!(await isServerReachable(url))) {
+      console.error(`No triggershell server reachable at ${url}.`);
+      process.exitCode = 1;
+      return;
+    }
+    useRemote = true;
+  } else if (opts.local) {
+    useRemote = false;
+  } else {
+    useRemote = await isServerReachable(url);
+  }
+
+  if (useRemote) {
+    if (config.auth.enabled && !token) {
+      console.error(
+        `${url} requires auth - pass --token or set TRIGGERSHELL_API_TOKEN (generate one with \`triggershell users add-token\`).`,
+      );
+      process.exitCode = 1;
+      return;
+    }
+    await runRemote(url, scriptId, variables, token, opts.wait);
+  } else {
+    await runLocal(configPath, script.id, variables, opts.wait);
+  }
+}
+
+async function runLocal(
+  configPath: string,
+  scriptId: string,
+  variables: Record<string, unknown>,
+  wait: boolean,
+): Promise<void> {
+  process.env.TRIGGERSHELL_CONFIG_PATH = configPath;
+  migrateOnBoot();
+  reconcileOrphanedRuns();
+
+  const runId = await startRun({ scriptId, variables, triggeredBy: "cli" });
+  console.log(`Started run ${runId}`);
+  if (!wait) return;
+
+  // Read-then-register, same as the WS subscribe handler (src/lib/ws/server.ts): the run may
+  // already have produced output - or even finished - between `startRun` returning and this line,
+  // so we snapshot the log file and current status first, synchronously, before attaching a live
+  // listener for anything after that point. Both this read and the listener attach below are
+  // synchronous (better-sqlite3 and fs are sync here), so there's no gap either could fall through.
+  const row = getDb().select().from(runs).where(eq(runs.id, runId)).get();
+  if (row) {
+    const { text } = readLogTail(row.logFilePath);
+    if (text) process.stdout.write(text);
+    if (!NON_TERMINAL.includes(row.status)) {
+      process.exitCode = exitCodeFor(row.status);
+      return;
+    }
+  }
+
+  const finalStatus = await new Promise<RunStatus>((resolve) => {
+    function onMessage(message: ServerMessage) {
+      if (message.runId !== runId) return;
+      if (message.type === "output") {
+        process.stdout.write(message.chunk);
+      } else if (
+        message.type === "status" &&
+        !NON_TERMINAL.includes(message.status)
+      ) {
+        cleanup();
+        resolve(message.status);
+      }
+    }
+    function onSigint() {
+      cancelRun(runId);
+    }
+    function cleanup() {
+      runEvents.off("message", onMessage);
+      process.off("SIGINT", onSigint);
+    }
+    process.on("SIGINT", onSigint);
+    runEvents.on("message", onMessage);
+  });
+
+  process.exitCode = exitCodeFor(finalStatus);
+}
+
+async function runRemote(
+  url: string,
+  scriptId: string,
+  variables: Record<string, unknown>,
+  token: string | undefined,
+  wait: boolean,
+): Promise<void> {
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+  };
+  if (token) headers.Authorization = `Bearer ${token}`;
+
+  const response = await fetch(`${url}/api/scripts/${scriptId}/runs`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({ variables }),
+  });
+
+  if (!response.ok) {
+    const body = await response
+      .json()
+      .catch(() => ({}) as Record<string, unknown>);
+    if (response.status === 401) {
+      console.error(
+        "Unauthorized - pass --token or set TRIGGERSHELL_API_TOKEN (see `triggershell users add-token`).",
+      );
+    } else if (body.fieldErrors) {
+      console.error("Validation failed:");
+      for (const [field, issues] of Object.entries(
+        body.fieldErrors as Record<string, string[]>,
+      )) {
+        console.error(`  ${field}: ${issues.join(", ")}`);
+      }
+    } else {
+      console.error(
+        (body.error as string) ?? `Request failed (${response.status})`,
+      );
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  const { runId } = (await response.json()) as { runId: string };
+  console.log(`Started run ${runId}`);
+  if (!wait) return;
+
+  const wsUrl = `${url.replace(/^http/, "ws")}/ws/runs${token ? `?token=${encodeURIComponent(token)}` : ""}`;
+
+  const finalStatus = await new Promise<RunStatus>((resolve, reject) => {
+    const ws = new WebSocket(wsUrl);
+
+    function onSigint() {
+      try {
+        ws.send(JSON.stringify({ type: "cancel", runId }));
+      } catch {
+        // socket may already be closing - nothing more we can do
+      }
+    }
+    process.on("SIGINT", onSigint);
+
+    function cleanup() {
+      process.off("SIGINT", onSigint);
+      ws.close();
+    }
+
+    ws.on("open", () => {
+      ws.send(JSON.stringify({ type: "subscribe", runId, afterBytes: 0 }));
+    });
+    ws.on("message", (raw) => {
+      let message: ServerMessage;
+      try {
+        message = JSON.parse(raw.toString());
+      } catch {
+        return;
+      }
+      if (message.runId !== runId) return;
+      if (message.type === "output") {
+        process.stdout.write(message.chunk);
+      } else if (
+        message.type === "status" &&
+        !NON_TERMINAL.includes(message.status)
+      ) {
+        cleanup();
+        resolve(message.status);
+      } else if (message.type === "error") {
+        cleanup();
+        reject(new Error(message.message));
+      }
+    });
+    ws.on("error", (error) => {
+      process.off("SIGINT", onSigint);
+      reject(error);
+    });
+  });
+
+  process.exitCode = exitCodeFor(finalStatus);
+}

src/cli/commands/scripts.ts

@@ -0,0 +1,86 @@
+import path from "node:path";
+import { ConfigError, loadConfig } from "../../lib/config/load";
+import type { ScriptConfig } from "../../lib/config/schema";
+import { loadDotenv } from "../lib/env-file";
+import { resolveConfigPath } from "../lib/paths";
+
+export interface ScriptsOptions {
+  config?: string;
+}
+
+function loadScripts(opts: ScriptsOptions): ScriptConfig[] | null {
+  const configPath = resolveConfigPath(opts.config);
+  loadDotenv(path.join(path.dirname(configPath), ".env"));
+
+  try {
+    return loadConfig(configPath).config.scripts;
+  } catch (error) {
+    if (error instanceof ConfigError) {
+      console.error(`Config error: ${error.message}`);
+      for (const issue of error.issues) console.error(`  - ${issue}`);
+      process.exitCode = 1;
+      return null;
+    }
+    throw error;
+  }
+}
+
+export async function scriptsListCommand(opts: ScriptsOptions): Promise<void> {
+  const scripts = loadScripts(opts);
+  if (!scripts) return;
+
+  if (scripts.length === 0) {
+    console.log("No scripts configured.");
+    return;
+  }
+
+  const idWidth = Math.max(...scripts.map((s) => s.id.length));
+  for (const script of scripts) {
+    const description = script.description ? ` - ${script.description}` : "";
+    console.log(`${script.id.padEnd(idWidth)}  ${script.name}${description}`);
+  }
+}
+
+export async function scriptsShowCommand(
+  scriptId: string,
+  opts: ScriptsOptions,
+): Promise<void> {
+  const scripts = loadScripts(opts);
+  if (!scripts) return;
+
+  const script = scripts.find((s) => s.id === scriptId);
+  if (!script) {
+    console.error(`No script '${scriptId}' configured.`);
+    if (scripts.length > 0) {
+      console.error(
+        `Available scripts: ${scripts.map((s) => s.id).join(", ")}`,
+      );
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log(script.name);
+  if (script.description) console.log(script.description);
+  console.log(
+    `\ncommand: ${script.command} ${script.args.join(" ")}`.trimEnd(),
+  );
+
+  if (script.variables.length === 0) {
+    console.log("\nThis script takes no parameters.");
+    return;
+  }
+
+  console.log("\nvariables:");
+  for (const variable of script.variables) {
+    const parts: string[] = [variable.type];
+    if (variable.required) parts.push("required");
+    if (variable.type === "enum" || variable.type === "multiselect") {
+      parts.push(`choices: ${variable.choices.join(", ")}`);
+    }
+    if (variable.default !== undefined) {
+      parts.push(`default: ${JSON.stringify(variable.default)}`);
+    }
+    console.log(`  ${variable.name} (${parts.join(", ")})`);
+  }
+}

src/cli/commands/service.ts

@@ -0,0 +1,128 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execa } from "execa";
+import { resolveConfigPath, resolveInvokedBinPath } from "../lib/paths";
+import {
+  isRoot,
+  renderUnit,
+  SERVICE_NAME,
+  systemUnitPath,
+  userUnitPath,
+} from "../lib/systemd";
+
+export interface ServiceInstallOptions {
+  config?: string;
+  port?: number;
+  host?: string;
+  system?: boolean;
+}
+
+export interface ServiceScopeOptions {
+  system?: boolean;
+}
+
+function scopeOf(opts: ServiceScopeOptions): "user" | "system" {
+  return opts.system ? "system" : "user";
+}
+
+export async function serviceInstallCommand(
+  opts: ServiceInstallOptions,
+): Promise<void> {
+  const scope = scopeOf(opts);
+  const configPath = resolveConfigPath(opts.config);
+  const unit = renderUnit({
+    execPath: process.execPath,
+    binPath: resolveInvokedBinPath(),
+    configPath,
+    configDir: path.dirname(configPath),
+    port: opts.port,
+    host: opts.host,
+    scope,
+  });
+
+  if (scope === "user") {
+    const unitPath = userUnitPath();
+    fs.mkdirSync(path.dirname(unitPath), { recursive: true });
+    fs.writeFileSync(unitPath, unit);
+    await execa("systemctl", ["--user", "daemon-reload"], { reject: false });
+
+    console.log(`Installed ${unitPath}`);
+    console.log("\nReview it, then start the service with:");
+    console.log(`  systemctl --user enable --now ${SERVICE_NAME}`);
+    console.log("\nTail logs with:");
+    console.log(`  journalctl --user -u ${SERVICE_NAME} -f`);
+    return;
+  }
+
+  if (isRoot()) {
+    const unitPath = systemUnitPath();
+    fs.writeFileSync(unitPath, unit);
+    await execa("systemctl", ["daemon-reload"], { reject: false });
+
+    console.log(`Installed ${unitPath}`);
+    console.log("\nReview it, then start the service with:");
+    console.log(`  systemctl enable --now ${SERVICE_NAME}`);
+    console.log("\nTail logs with:");
+    console.log(`  journalctl -u ${SERVICE_NAME} -f`);
+    return;
+  }
+
+  const scratchPath = path.join(os.tmpdir(), `${SERVICE_NAME}.service`);
+  fs.writeFileSync(scratchPath, unit);
+  console.log(
+    `Not running as root - wrote the unit file to ${scratchPath} instead.`,
+  );
+  console.log("\nReview it, then run:");
+  console.log(`  sudo install -m 644 ${scratchPath} ${systemUnitPath()}`);
+  console.log("  sudo systemctl daemon-reload");
+  console.log(`  sudo systemctl enable --now ${SERVICE_NAME}`);
+}
+
+export async function serviceUninstallCommand(
+  opts: ServiceScopeOptions,
+): Promise<void> {
+  const scope = scopeOf(opts);
+
+  if (scope === "user") {
+    await execa("systemctl", ["--user", "disable", "--now", SERVICE_NAME], {
+      reject: false,
+    });
+    const unitPath = userUnitPath();
+    if (fs.existsSync(unitPath)) fs.rmSync(unitPath);
+    await execa("systemctl", ["--user", "daemon-reload"], { reject: false });
+    console.log(`Removed ${unitPath}`);
+    return;
+  }
+
+  if (isRoot()) {
+    await execa("systemctl", ["disable", "--now", SERVICE_NAME], {
+      reject: false,
+    });
+    const unitPath = systemUnitPath();
+    if (fs.existsSync(unitPath)) fs.rmSync(unitPath);
+    await execa("systemctl", ["daemon-reload"], { reject: false });
+    console.log(`Removed ${unitPath}`);
+    return;
+  }
+
+  console.log("Not running as root. Remove the system service manually with:");
+  console.log(`  sudo systemctl disable --now ${SERVICE_NAME}`);
+  console.log(`  sudo rm ${systemUnitPath()}`);
+  console.log("  sudo systemctl daemon-reload");
+}
+
+export async function serviceStatusCommand(
+  opts: ServiceScopeOptions,
+): Promise<void> {
+  const scope = scopeOf(opts);
+  const args =
+    scope === "user"
+      ? ["--user", "status", SERVICE_NAME]
+      : ["status", SERVICE_NAME];
+  const result = await execa("systemctl", args, {
+    stdio: "inherit",
+    reject: false,
+  });
+  process.exitCode = result.exitCode ?? 1;
+}

src/cli/commands/start.ts

@@ -0,0 +1,61 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { ConfigError, loadConfig } from "../../lib/config/load";
+import { loadDotenv } from "../lib/env-file";
+import { isPortFree, openBrowser, waitUntilReady } from "../lib/network";
+import { resolveAppRoot, resolveConfigPath } from "../lib/paths";
+
+export interface StartOptions {
+  config?: string;
+  port?: number;
+  host?: string;
+  noBrowser?: boolean;
+}
+
+export async function startCommand(opts: StartOptions): Promise<void> {
+  const configPath = resolveConfigPath(opts.config);
+  loadDotenv(path.join(path.dirname(configPath), ".env"));
+
+  let loaded;
+  try {
+    loaded = loadConfig(configPath);
+  } catch (error) {
+    if (error instanceof ConfigError) {
+      console.error(`Config error: ${error.message}`);
+      for (const issue of error.issues) console.error(`  - ${issue}`);
+      process.exitCode = 1;
+      return;
+    }
+    throw error;
+  }
+
+  const effectiveHost = opts.host ?? loaded.config.server.host;
+  const effectivePort = opts.port ?? loaded.config.server.port;
+
+  if (!(await isPortFree(effectiveHost, effectivePort))) {
+    console.error(
+      `Port ${effectivePort} on ${effectiveHost} is already in use. Pass --port to use a different one.`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  process.env.TRIGGERSHELL_CONFIG_PATH = configPath;
+  process.env.PORT = String(effectivePort);
+  process.env.HOST = effectiveHost;
+  // Next's generated types mark NODE_ENV readonly; this is the one legitimate place that sets it
+  // (the CLI IS what decides production mode) before importing server.ts.
+  (process.env as { NODE_ENV: string }).NODE_ENV = "production";
+
+  const url = `http://${effectiveHost}:${effectivePort}`;
+  if (!opts.noBrowser) {
+    void waitUntilReady(`${url}/api/healthz`, 45_000).then((ready) => {
+      if (ready) openBrowser(url);
+    });
+  }
+
+  const serverEntry = pathToFileURL(
+    path.join(resolveAppRoot(), "server.ts"),
+  ).href;
+  await import(serverEntry);
+}

src/cli/commands/users.ts

@@ -0,0 +1,88 @@
+import crypto from "node:crypto";
+import path from "node:path";
+import { password as promptPassword } from "@inquirer/prompts";
+import { stringify } from "yaml";
+import { hashPassword } from "../../lib/auth/password";
+import { upsertEnvVar } from "../lib/env-file";
+import { resolveConfigPath } from "../lib/paths";
+import { slug } from "../lib/slug";
+
+export interface UsersOptions {
+  config?: string;
+  inline?: boolean;
+}
+
+function printSnippet(heading: string, entry: Record<string, unknown>): void {
+  console.log(`\n${heading}\n`);
+  console.log(stringify([entry]));
+}
+
+async function promptNewPassword(): Promise<string> {
+  for (;;) {
+    const first = await promptPassword({ message: "Password", mask: true });
+    const second = await promptPassword({
+      message: "Confirm password",
+      mask: true,
+    });
+    if (first === second) return first;
+    console.error("Passwords did not match, try again.\n");
+  }
+}
+
+export async function usersAddCommand(
+  username: string,
+  opts: UsersOptions,
+): Promise<void> {
+  const password = await promptNewPassword();
+  const passwordHash = await hashPassword(password);
+
+  if (opts.inline) {
+    printSnippet("Add this under `auth.users:` in your config file:", {
+      username,
+      passwordHash,
+    });
+    return;
+  }
+
+  const configPath = resolveConfigPath(opts.config);
+  const envPath = path.join(path.dirname(configPath), ".env");
+  const varName = `TRIGGERSHELL_USER_${slug(username)}_PASSWORD_HASH`;
+  upsertEnvVar(envPath, varName, passwordHash);
+
+  console.log(`Stored ${varName} in ${envPath}`);
+  printSnippet("Add this under `auth.users:` in your config file:", {
+    username,
+    passwordHash: `\${${varName}}`,
+  });
+}
+
+export async function usersAddTokenCommand(
+  name: string,
+  opts: UsersOptions,
+): Promise<void> {
+  const token = crypto.randomBytes(32).toString("hex");
+  const tokenHash = `sha256:${crypto.createHash("sha256").update(token).digest("hex")}`;
+
+  console.log("\nSave this token now - it will not be shown again:");
+  console.log(`  ${token}`);
+  console.log(`Use it as: Authorization: Bearer ${token}`);
+
+  if (opts.inline) {
+    printSnippet("Add this under `auth.tokens:` in your config file:", {
+      name,
+      tokenHash,
+    });
+    return;
+  }
+
+  const configPath = resolveConfigPath(opts.config);
+  const envPath = path.join(path.dirname(configPath), ".env");
+  const varName = `TRIGGERSHELL_TOKEN_${slug(name)}_HASH`;
+  upsertEnvVar(envPath, varName, tokenHash);
+
+  console.log(`Stored ${varName} in ${envPath}`);
+  printSnippet("Add this under `auth.tokens:` in your config file:", {
+    name,
+    tokenHash: `\${${varName}}`,
+  });
+}

src/cli/commands/validate.ts

@@ -0,0 +1,28 @@
+import path from "node:path";
+import { ConfigError, loadConfig } from "../../lib/config/load";
+import { loadDotenv } from "../lib/env-file";
+import { resolveConfigPath } from "../lib/paths";
+
+export interface ValidateOptions {
+  config?: string;
+}
+
+export async function validateCommand(opts: ValidateOptions): Promise<void> {
+  const configPath = resolveConfigPath(opts.config);
+  loadDotenv(path.join(path.dirname(configPath), ".env"));
+
+  try {
+    const { config } = loadConfig(configPath);
+    console.log(`OK - ${configPath}`);
+    console.log(`  ${config.scripts.length} script(s) configured`);
+    console.log(`  auth.enabled: ${config.auth.enabled}`);
+  } catch (error) {
+    if (error instanceof ConfigError) {
+      console.error(`Config error: ${error.message}`);
+      for (const issue of error.issues) console.error(`  - ${issue}`);
+      process.exitCode = 1;
+      return;
+    }
+    throw error;
+  }
+}

src/cli/index.ts

@@ -0,0 +1,188 @@
+import { Command } from "commander";
+import { doctorCommand } from "./commands/doctor";
+import { initCommand } from "./commands/init";
+import { runCommand } from "./commands/run";
+import { scriptsListCommand, scriptsShowCommand } from "./commands/scripts";
+import {
+  serviceInstallCommand,
+  serviceStatusCommand,
+  serviceUninstallCommand,
+} from "./commands/service";
+import { startCommand } from "./commands/start";
+import { usersAddCommand, usersAddTokenCommand } from "./commands/users";
+import { validateCommand } from "./commands/validate";
+import { getVersion } from "./version";
+
+function collect(value: string, previous: string[]): string[] {
+  return [...previous, value];
+}
+
+const program = new Command("triggershell")
+  .version(getVersion())
+  .description(
+    "Launch the TriggerShell web app: run your configured shell scripts from a browser.",
+  );
+
+program
+  .command("init [path]")
+  .description("Scaffold a new triggershell.yml (and .env, if auth is enabled)")
+  .option(
+    "--port <port>",
+    "Port the web app will listen on.",
+    (v) => Number(v),
+    4173,
+  )
+  .option("--no-auth", "Disable built-in login for the web app.")
+  .option("--force", "Overwrite an existing config file.", false)
+  .action(initCommand);
+
+program
+  .command("validate")
+  .description("Validate a config file against the full schema.")
+  .option("-c, --config <path>", "Path to the config file.")
+  .action(validateCommand);
+
+program
+  .command("start")
+  .description("Run the web app in production mode.")
+  .option("-c, --config <path>", "Path to the config file.")
+  .option("--port <port>", "Override the port from the config file.", (v) =>
+    Number(v),
+  )
+  .option("--host <host>", "Override the host from the config file.")
+  .option("--no-browser", "Don't open a browser automatically.")
+  .action(startCommand);
+
+program
+  .command("doctor")
+  .description("Print diagnostic info about your environment and config.")
+  .option("-c, --config <path>", "Path to the config file.")
+  .action(doctorCommand);
+
+const scripts = program
+  .command("scripts")
+  .description("List and inspect configured scripts.");
+
+scripts
+  .command("list")
+  .description("List configured scripts.")
+  .option("-c, --config <path>", "Path to the config file.")
+  .action(scriptsListCommand);
+
+scripts
+  .command("show <scriptId>")
+  .description("Show a script's command and variables.")
+  .option("-c, --config <path>", "Path to the config file.")
+  .action(scriptsShowCommand);
+
+program
+  .command("run <scriptId>")
+  .description("Run a configured script.")
+  .option("-c, --config <path>", "Path to the config file.")
+  .option(
+    "--var <keyValue>",
+    "Set a variable, e.g. --var environment=staging (repeatable; repeat the same name for a multiselect variable).",
+    collect,
+    [],
+  )
+  .option("--host <host>", "Override the host from the config file.")
+  .option("--port <port>", "Override the port from the config file.", (v) =>
+    Number(v),
+  )
+  .option(
+    "--token <token>",
+    "API token for an already-running server (or set TRIGGERSHELL_API_TOKEN).",
+  )
+  .option(
+    "--local",
+    "Always run in this process, even if the web server is reachable.",
+    false,
+  )
+  .option(
+    "--remote",
+    "Require a reachable web server; don't fall back to running locally.",
+    false,
+  )
+  .option(
+    "--no-wait",
+    "Print the run ID and exit immediately instead of streaming output.",
+  )
+  .action(runCommand);
+
+const users = program
+  .command("users")
+  .description("Manage auth users and API tokens defined in your config file.");
+
+users
+  .command("add <username>")
+  .description("Hash a password with argon2id and wire it up for auth.users.")
+  .option(
+    "-c, --config <path>",
+    "Path to the config file (used to locate .env).",
+  )
+  .option(
+    "--inline",
+    "Print the raw hash to paste into the config instead of storing it in .env.",
+    false,
+  )
+  .action(usersAddCommand);
+
+users
+  .command("add-token <name>")
+  .description("Generate an API token and wire its hash up for auth.tokens.")
+  .option(
+    "-c, --config <path>",
+    "Path to the config file (used to locate .env).",
+  )
+  .option(
+    "--inline",
+    "Print the raw hash to paste into the config instead of storing it in .env.",
+    false,
+  )
+  .action(usersAddTokenCommand);
+
+const service = program
+  .command("service")
+  .description("Manage the systemd service (Linux only).");
+
+service
+  .command("install")
+  .description("Install a systemd unit that runs `triggershell start`.")
+  .option("-c, --config <path>", "Path to the config file.")
+  .option("--port <port>", "Override the port from the config file.", (v) =>
+    Number(v),
+  )
+  .option("--host <host>", "Override the host from the config file.")
+  .option(
+    "--system",
+    "Install a system-wide unit instead of a per-user one.",
+    false,
+  )
+  .action(serviceInstallCommand);
+
+service
+  .command("uninstall")
+  .description("Stop, disable, and remove the systemd unit.")
+  .option(
+    "--system",
+    "Target the system-wide unit instead of the per-user one.",
+    false,
+  )
+  .action(serviceUninstallCommand);
+
+service
+  .command("status")
+  .description("Show the systemd unit's status.")
+  .option(
+    "--system",
+    "Target the system-wide unit instead of the per-user one.",
+    false,
+  )
+  .action(serviceStatusCommand);
+
+if (process.argv.length <= 2) {
+  program.outputHelp();
+  process.exit(1);
+}
+
+await program.parseAsync(process.argv);

src/cli/lib/env-file.test.ts

@@ -0,0 +1,53 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { test } from "node:test";
+import { loadDotenv, upsertEnvVar } from "./env-file";
+
+function tmpEnvPath(): string {
+  return path.join(
+    fs.mkdtempSync(path.join(os.tmpdir(), "triggershell-env-")),
+    ".env",
+  );
+}
+
+test("upsertEnvVar appends a new key", () => {
+  const envPath = tmpEnvPath();
+  upsertEnvVar(envPath, "FOO", "bar");
+  assert.equal(fs.readFileSync(envPath, "utf-8"), "FOO=bar\n");
+});
+
+test("upsertEnvVar replaces an existing key without duplicating the line", () => {
+  const envPath = tmpEnvPath();
+  upsertEnvVar(envPath, "FOO", "first");
+  upsertEnvVar(envPath, "FOO", "second");
+  const lines = fs.readFileSync(envPath, "utf-8").trim().split("\n");
+  assert.equal(lines.length, 1);
+  assert.equal(lines[0], "FOO=second");
+});
+
+test("upsertEnvVar preserves other existing keys", () => {
+  const envPath = tmpEnvPath();
+  upsertEnvVar(envPath, "FOO", "1");
+  upsertEnvVar(envPath, "BAR", "2");
+  const content = fs.readFileSync(envPath, "utf-8");
+  assert.match(content, /FOO=1/);
+  assert.match(content, /BAR=2/);
+});
+
+test("loadDotenv sets process.env without overriding an already-set var", () => {
+  const envPath = tmpEnvPath();
+  upsertEnvVar(envPath, "TRIGGERSHELL_TEST_ALREADY_SET", "from-file");
+  upsertEnvVar(envPath, "TRIGGERSHELL_TEST_NEW", "from-file");
+  process.env.TRIGGERSHELL_TEST_ALREADY_SET = "from-shell";
+  delete process.env.TRIGGERSHELL_TEST_NEW;
+
+  loadDotenv(envPath);
+
+  assert.equal(process.env.TRIGGERSHELL_TEST_ALREADY_SET, "from-shell");
+  assert.equal(process.env.TRIGGERSHELL_TEST_NEW, "from-file");
+
+  delete process.env.TRIGGERSHELL_TEST_ALREADY_SET;
+  delete process.env.TRIGGERSHELL_TEST_NEW;
+});

src/cli/lib/env-file.ts

@@ -0,0 +1,49 @@
+import fs from "node:fs";
+
+interface EnvEntry {
+  key: string;
+  value: string;
+}
+
+function parseEnvLines(content: string): EnvEntry[] {
+  const entries: EnvEntry[] = [];
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq === -1) continue;
+    entries.push({ key: trimmed.slice(0, eq), value: trimmed.slice(eq + 1) });
+  }
+  return entries;
+}
+
+/** Loads a `.env` file into `process.env`, without overriding vars already set. */
+export function loadDotenv(envPath: string): void {
+  if (!fs.existsSync(envPath)) return;
+  for (const { key, value } of parseEnvLines(
+    fs.readFileSync(envPath, "utf-8"),
+  )) {
+    if (process.env[key] === undefined) process.env[key] = value;
+  }
+}
+
+/** Sets `key=value` in a `.env` file, replacing an existing line for that key rather than duplicating it. */
+export function upsertEnvVar(
+  envPath: string,
+  key: string,
+  value: string,
+): void {
+  const lines = fs.existsSync(envPath)
+    ? fs.readFileSync(envPath, "utf-8").split("\n")
+    : [];
+  const prefix = `${key}=`;
+  const index = lines.findIndex((line) => line.startsWith(prefix));
+  const newLine = `${key}=${value}`;
+  if (index >= 0) {
+    lines[index] = newLine;
+  } else {
+    if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+    lines.push(newLine);
+  }
+  fs.writeFileSync(envPath, lines.join("\n") + "\n");
+}

src/cli/lib/network.ts

@@ -0,0 +1,69 @@
+import { spawn } from "node:child_process";
+import net from "node:net";
+
+export function isPortFree(host: string, port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = net.connect({ host, port, timeout: 500 });
+    socket.once("connect", () => {
+      socket.destroy();
+      resolve(false);
+    });
+    socket.once("timeout", () => {
+      socket.destroy();
+      resolve(true);
+    });
+    socket.once("error", () => {
+      resolve(true);
+    });
+  });
+}
+
+export async function waitUntilReady(
+  url: string,
+  timeoutMs: number,
+  intervalMs = 400,
+): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const response = await fetch(url, { signal: AbortSignal.timeout(1500) });
+      if (response.status === 200) return true;
+    } catch {
+      // not ready yet
+    }
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+  return false;
+}
+
+/** Single-shot check (not a poll loop, unlike `waitUntilReady`) for whether a triggershell server
+ * is already listening at `url` - used to decide whether `run` can go through the REST/WS API. */
+export async function isServerReachable(url: string): Promise<boolean> {
+  try {
+    const response = await fetch(`${url}/api/healthz`, {
+      signal: AbortSignal.timeout(1000),
+    });
+    return response.status === 200;
+  } catch {
+    return false;
+  }
+}
+
+export function openBrowser(url: string): void {
+  const command =
+    process.platform === "darwin"
+      ? "open"
+      : process.platform === "win32"
+        ? "start"
+        : "xdg-open";
+  const args = process.platform === "win32" ? ["", url] : [url];
+  try {
+    spawn(command, args, {
+      detached: true,
+      stdio: "ignore",
+      shell: process.platform === "win32",
+    }).unref();
+  } catch {
+    // best-effort - not fatal if no browser opener is available
+  }
+}

src/cli/lib/paths.ts

@@ -0,0 +1,28 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const DEFAULT_CONFIG_NAME = "triggershell.yml";
+
+/** Root of the installed `triggershell` package - one level up from `src/cli/lib`. */
+export function resolveAppRoot(): string {
+  return path.resolve(
+    path.dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "..",
+    "..",
+  );
+}
+
+export function resolveConfigPath(configArg?: string): string {
+  return path.resolve(process.cwd(), configArg ?? DEFAULT_CONFIG_NAME);
+}
+
+/**
+ * Absolute path to the script that was actually invoked (`node <this>`), with any symlink
+ * (as created by a global npm/pnpm install or `npm link`) resolved away. Used to build a
+ * `systemd` `ExecStart` line that keeps working regardless of how the CLI was installed.
+ */
+export function resolveInvokedBinPath(): string {
+  return fs.realpathSync(process.argv[1]);
+}

src/cli/lib/slug.test.ts

@@ -0,0 +1,9 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { slug } from "./slug";
+
+test("slug", () => {
+  assert.equal(slug("ci-bot"), "CI_BOT");
+  assert.equal(slug("Admin User"), "ADMIN_USER");
+  assert.equal(slug("__weird--name__"), "WEIRD_NAME");
+});

src/cli/lib/slug.ts

@@ -0,0 +1,6 @@
+export function slug(value: string): string {
+  return value
+    .replace(/[^A-Za-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .toUpperCase();
+}

src/cli/lib/systemd.test.ts

@@ -0,0 +1,39 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { renderUnit } from "./systemd";
+
+test("renderUnit builds an absolute-path ExecStart with the given args", () => {
+  const unit = renderUnit({
+    execPath: "/usr/bin/node",
+    binPath:
+      "/home/user/.local/share/pnpm/global/5/node_modules/.bin/triggershell",
+    configPath: "/home/user/project/triggershell.yml",
+    configDir: "/home/user/project",
+    port: 8080,
+    host: "0.0.0.0",
+    scope: "user",
+  });
+
+  assert.match(
+    unit,
+    /ExecStart=\/usr\/bin\/node .*triggershell start --config \/home\/user\/project\/triggershell\.yml --no-browser --port 8080 --host 0\.0\.0\.0/,
+  );
+  assert.match(unit, /WorkingDirectory=\/home\/user\/project/);
+  assert.match(unit, /WantedBy=default\.target/);
+});
+
+test("renderUnit uses multi-user.target for the system scope", () => {
+  const unit = renderUnit({
+    execPath: "/usr/bin/node",
+    binPath: "/usr/lib/node_modules/triggershell/bin/triggershell.js",
+    configPath: "/etc/triggershell/triggershell.yml",
+    configDir: "/etc/triggershell",
+    scope: "system",
+  });
+
+  assert.match(unit, /WantedBy=multi-user\.target/);
+  assert.match(
+    unit,
+    /ExecStart=\/usr\/bin\/node .*start --config .*--no-browser$/m,
+  );
+});

src/cli/lib/systemd.ts

@@ -0,0 +1,61 @@
+import os from "node:os";
+import path from "node:path";
+
+export const SERVICE_NAME = "triggershell";
+
+export interface UnitOptions {
+  execPath: string;
+  binPath: string;
+  configPath: string;
+  configDir: string;
+  port?: number;
+  host?: string;
+  scope: "user" | "system";
+}
+
+export function renderUnit(opts: UnitOptions): string {
+  const args = ["start", "--config", opts.configPath, "--no-browser"];
+  if (opts.port !== undefined) args.push("--port", String(opts.port));
+  if (opts.host !== undefined) args.push("--host", opts.host);
+
+  const execStart = [opts.execPath, opts.binPath, ...args]
+    .map((part) => (part.includes(" ") ? `"${part}"` : part))
+    .join(" ");
+
+  const wantedBy =
+    opts.scope === "user" ? "default.target" : "multi-user.target";
+
+  return `[Unit]
+Description=TriggerShell - self-hosted script runner
+After=network.target
+
+[Service]
+Type=simple
+ExecStart=${execStart}
+WorkingDirectory=${opts.configDir}
+Restart=on-failure
+RestartSec=2
+Environment=NODE_ENV=production
+
+[Install]
+WantedBy=${wantedBy}
+`;
+}
+
+export function userUnitPath(): string {
+  return path.join(
+    os.homedir(),
+    ".config",
+    "systemd",
+    "user",
+    `${SERVICE_NAME}.service`,
+  );
+}
+
+export function systemUnitPath(): string {
+  return path.join("/etc", "systemd", "system", `${SERVICE_NAME}.service`);
+}
+
+export function isRoot(): boolean {
+  return process.getuid?.() === 0;
+}

src/cli/lib/variables.test.ts

@@ -0,0 +1,116 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import type { VariableConfig } from "../../lib/config/schema";
+import { coerceVariables, parseVarFlags } from "./variables";
+
+function stringVar(
+  name: string,
+  overrides: Partial<VariableConfig> = {},
+): VariableConfig {
+  return {
+    type: "string",
+    name,
+    required: false,
+    secret: false,
+    passAs: "arg",
+    joinWith: ",",
+    multiline: false,
+    ...overrides,
+  } as VariableConfig;
+}
+
+function boolVar(name: string): VariableConfig {
+  return {
+    type: "boolean",
+    name,
+    required: false,
+    secret: false,
+    passAs: "flag",
+    joinWith: ",",
+    default: false,
+  } as VariableConfig;
+}
+
+function numberVar(name: string): VariableConfig {
+  return {
+    type: "number",
+    name,
+    required: false,
+    secret: false,
+    passAs: "arg",
+    joinWith: ",",
+  } as VariableConfig;
+}
+
+function multiselectVar(name: string, choices: string[]): VariableConfig {
+  return {
+    type: "multiselect",
+    name,
+    required: false,
+    secret: false,
+    passAs: "arg",
+    joinWith: ",",
+    choices,
+    default: [],
+  } as VariableConfig;
+}
+
+test("parseVarFlags groups repeated names into arrays", () => {
+  const grouped = parseVarFlags(["environment=staging", "tag=a", "tag=b"]);
+  assert.deepEqual(grouped, { environment: ["staging"], tag: ["a", "b"] });
+});
+
+test("parseVarFlags rejects a flag with no '='", () => {
+  assert.throws(() => parseVarFlags(["oops"]), /missing '='/);
+});
+
+test("coerceVariables coerces booleans and numbers, passes strings through", () => {
+  const variables = [
+    stringVar("environment"),
+    boolVar("dryRun"),
+    numberVar("replicas"),
+  ];
+  const values = coerceVariables(variables, {
+    environment: ["staging"],
+    dryRun: ["true"],
+    replicas: ["3"],
+  });
+  assert.deepEqual(values, {
+    environment: "staging",
+    dryRun: true,
+    replicas: 3,
+  });
+});
+
+test("coerceVariables rejects an invalid boolean/number", () => {
+  assert.throws(
+    () => coerceVariables([boolVar("dryRun")], { dryRun: ["yes"] }),
+    /must be 'true' or 'false'/,
+  );
+  assert.throws(
+    () => coerceVariables([numberVar("replicas")], { replicas: ["abc"] }),
+    /not a valid number/,
+  );
+});
+
+test("coerceVariables collects a multiselect variable's repeats into an array", () => {
+  const values = coerceVariables([multiselectVar("tags", ["a", "b", "c"])], {
+    tags: ["a", "c"],
+  });
+  assert.deepEqual(values, { tags: ["a", "c"] });
+});
+
+test("coerceVariables rejects a non-multiselect variable given more than once", () => {
+  assert.throws(
+    () =>
+      coerceVariables([stringVar("environment")], { environment: ["a", "b"] }),
+    /given 2 times/,
+  );
+});
+
+test("coerceVariables rejects an unknown variable name", () => {
+  assert.throws(
+    () => coerceVariables([stringVar("environment")], { nope: ["x"] }),
+    /does not match any variable/,
+  );
+});

src/cli/lib/variables.ts

@@ -0,0 +1,77 @@
+import type { VariableConfig } from "../../lib/config/schema";
+
+/** Splits each `name=value` pair and groups by name - repeats accumulate into an array, which is
+ * how a `multiselect` variable is given more than one selection on the command line. */
+export function parseVarFlags(pairs: string[]): Record<string, string[]> {
+  const grouped: Record<string, string[]> = {};
+  for (const pair of pairs) {
+    const eq = pair.indexOf("=");
+    if (eq === -1) {
+      throw new Error(
+        `--var ${pair} is missing '=' - expected --var name=value`,
+      );
+    }
+    const name = pair.slice(0, eq);
+    const value = pair.slice(eq + 1);
+    (grouped[name] ??= []).push(value);
+  }
+  return grouped;
+}
+
+/** Coerces raw `--var` strings into the JS type each variable expects, ready for
+ * `buildVariableSchema(script).safeParse(...)` - the same schema the web form and the
+ * `/api/scripts/:id/runs` route already validate against. Variables not present in `grouped`
+ * are left out entirely (the caller fills those from `defaultValuesForScript` first). */
+export function coerceVariables(
+  variables: readonly VariableConfig[],
+  grouped: Record<string, string[]>,
+): Record<string, unknown> {
+  const values: Record<string, unknown> = {};
+  const known = new Set(variables.map((v) => v.name));
+
+  for (const name of Object.keys(grouped)) {
+    if (!known.has(name)) {
+      throw new Error(
+        `--var ${name}=... does not match any variable on this script`,
+      );
+    }
+  }
+
+  for (const variable of variables) {
+    const raw = grouped[variable.name];
+    if (!raw) continue;
+
+    if (variable.type === "multiselect") {
+      values[variable.name] = raw;
+      continue;
+    }
+
+    if (raw.length > 1) {
+      throw new Error(
+        `--var ${variable.name}=... was given ${raw.length} times, but '${variable.name}' is not a multiselect variable`,
+      );
+    }
+    const value = raw[0];
+
+    if (variable.type === "boolean") {
+      if (value === "true") values[variable.name] = true;
+      else if (value === "false") values[variable.name] = false;
+      else
+        throw new Error(
+          `--var ${variable.name}=${value} must be 'true' or 'false'`,
+        );
+    } else if (variable.type === "number") {
+      const n = Number(value);
+      if (Number.isNaN(n)) {
+        throw new Error(
+          `--var ${variable.name}=${value} is not a valid number`,
+        );
+      }
+      values[variable.name] = n;
+    } else {
+      values[variable.name] = value;
+    }
+  }
+
+  return values;
+}

src/cli/version.ts

@@ -0,0 +1,11 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolveAppRoot } from "./lib/paths";
+
+export function getVersion(): string {
+  const pkgPath = path.join(resolveAppRoot(), "package.json");
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8")) as {
+    version: string;
+  };
+  return pkg.version;
+}

src/components/docs/markdown-viewer.tsx

@@ -0,0 +1,39 @@
+import ReactMarkdown from "react-markdown";
+import remarkGfm from "remark-gfm";
+import { cn } from "@/lib/utils";
+
+// GFM tables (the config reference's Field/Type/Default/Notes tables) are wider than a phone
+// screen and don't wrap - without their own scroll container the table forces the whole page
+// to scroll horizontally instead. The typography plugin's table styles still apply to `table`
+// here (its selectors match any descendant, not just direct children of `.prose`), so this
+// wrapper only adds the scroll boundary.
+function Table(props: React.ComponentProps<"table">) {
+  return (
+    <div className="overflow-x-auto">
+      <table {...props} />
+    </div>
+  );
+}
+
+export function MarkdownViewer({ content }: { content: string }) {
+  return (
+    <div
+      className={cn(
+        "prose prose-neutral dark:prose-invert max-w-none",
+        "prose-pre:bg-muted prose-pre:text-foreground",
+        // Typography's default inline `code` style is just bold text wrapped in decorative
+        // backtick characters - swap that for the same muted pill used for inline code
+        // elsewhere in the app (see the "no scripts configured" message on the dashboard).
+        "prose-code:before:content-none prose-code:after:content-none",
+        "prose-code:rounded prose-code:bg-muted prose-code:px-1.5 prose-code:py-0.5 prose-code:font-mono prose-code:font-normal prose-code:text-foreground",
+        // Long unbroken strings (env var names, paths) in table cells or inline code would
+        // otherwise force their column/line wider than the viewport instead of wrapping.
+        "prose-td:break-words prose-th:break-words prose-code:break-words",
+      )}
+    >
+      <ReactMarkdown remarkPlugins={[remarkGfm]} components={{ table: Table }}>
+        {content}
+      </ReactMarkdown>
+    </div>
+  );
+}

src/components/forms/controls/combobox.tsx

@@ -0,0 +1,80 @@
+"use client";
+
+import { useState } from "react";
+import { Check, ChevronsUpDown } from "lucide-react";
+import { buttonVariants } from "@/components/ui/button";
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+} from "@/components/ui/command";
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from "@/components/ui/popover";
+import { cn } from "@/lib/utils";
+
+interface ComboboxProps {
+  choices: string[];
+  value: string;
+  onChange: (value: string) => void;
+  placeholder?: string;
+}
+
+export function Combobox({
+  choices,
+  value,
+  onChange,
+  placeholder = "Select...",
+}: ComboboxProps) {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverTrigger
+        className={cn(
+          buttonVariants({ variant: "outline" }),
+          "h-auto min-h-8 w-full justify-between font-normal",
+        )}
+      >
+        <span
+          className={cn("flex-1 text-left", !value && "text-muted-foreground")}
+        >
+          {value || placeholder}
+        </span>
+        <ChevronsUpDown className="text-muted-foreground size-4 shrink-0" />
+      </PopoverTrigger>
+      <PopoverContent className="w-80 p-0">
+        <Command>
+          <CommandInput placeholder="Search..." />
+          <CommandList>
+            <CommandEmpty>No matches.</CommandEmpty>
+            <CommandGroup>
+              {choices.map((choice) => (
+                <CommandItem
+                  key={choice}
+                  onSelect={() => {
+                    onChange(choice);
+                    setOpen(false);
+                  }}
+                >
+                  <Check
+                    className={cn(
+                      "mr-2 size-4",
+                      value === choice ? "opacity-100" : "opacity-0",
+                    )}
+                  />
+                  {choice}
+                </CommandItem>
+              ))}
+            </CommandGroup>
+          </CommandList>
+        </Command>
+      </PopoverContent>
+    </Popover>
+  );
+}

src/components/forms/dynamic-form.tsx

@@ -10,30 +10,28 @@ import { Button } from "@/components/ui/button";
 import { Form } from "@/components/ui/form";
 import { Alert, AlertDescription } from "@/components/ui/alert";
 import { buildVariableSchemaFromList } from "@/lib/validation/variable-schema";
+import { defaultValuesForScript } from "@/lib/config/defaults";
 import type { ClientScript } from "@/lib/config/serialize";
 import { FieldRenderer } from "./field-renderer";
 
-function emptyValueFor(variable: ClientScript["variables"][number]): unknown {
+/** Controls whose content doesn't shrink well into a narrow grid column - long-form text,
-  if (variable.type === "boolean") return false;
+ * or a group of checkboxes that reads better as a single wide list - so they span the full
-  if (variable.type === "multiselect") return [];
+ * grid width instead of sharing a row with other fields. */
-  return "";
+const WIDE_CONTROLS = new Set(["textarea", "checkboxGroup"]);
-}
 
 /** `initialValues` comes from a previous run's (already-redacted) variables when re-running -
  * secret fields are deliberately excluded there (their stored value is just "***", not the real
- * one), so those always fall through to the normal empty/default state and have to be re-entered. */
+ * one), so those always fall through to the normal default/empty state and have to be re-entered. */
 function defaultValuesFor(
   script: ClientScript,
   initialValues?: Record<string, unknown>,
 ): Record<string, unknown> {
-  const values: Record<string, unknown> = {};
+  const values = defaultValuesForScript(script.variables);
+  if (!initialValues) return values;
   for (const variable of script.variables) {
-    const fromPreviousRun =
+    if (variable.secret) continue;
-      initialValues && !variable.secret
+    const fromPreviousRun = initialValues[variable.name];
-        ? initialValues[variable.name]
+    if (fromPreviousRun !== undefined) values[variable.name] = fromPreviousRun;
-        : undefined;
-    values[variable.name] =
-      fromPreviousRun ?? variable.default ?? emptyValueFor(variable);
   }
   return values;
 }
@@ -100,9 +98,22 @@ export function DynamicForm({
             This script takes no parameters.
           </p>
         )}
+        {script.variables.length > 0 && (
+          <div className="grid grid-cols-1 gap-x-6 gap-y-5 sm:grid-cols-2 lg:grid-cols-3">
             {script.variables.map((variable) => (
-          <FieldRenderer key={variable.name} variable={variable} />
+              <div
+                key={variable.name}
+                className={
+                  WIDE_CONTROLS.has(variable.control)
+                    ? "sm:col-span-2 lg:col-span-3"
+                    : undefined
+                }
+              >
+                <FieldRenderer variable={variable} />
+              </div>
             ))}
+          </div>
+        )}
         <Button
           type="submit"
           disabled={form.formState.isSubmitting}

src/components/forms/field-renderer.tsx

@@ -24,6 +24,7 @@ import {
 import { Slider } from "@/components/ui/slider";
 import { Label } from "@/components/ui/label";
 import { MultiSelect } from "./controls/multi-select";
+import { Combobox } from "./controls/combobox";
 import type { ClientVariable } from "@/lib/config/serialize";
 
 export function FieldRenderer({ variable }: { variable: ClientVariable }) {
@@ -211,6 +212,29 @@ export function FieldRenderer({ variable }: { variable: ClientVariable }) {
               </FormItem>
             );
 
+          case "combobox":
+            return (
+              <FormItem>
+                <FormLabel>
+                  {label}
+                  {variable.required && (
+                    <span className="text-destructive"> *</span>
+                  )}
+                </FormLabel>
+                <FormControl>
+                  <Combobox
+                    choices={variable.type === "enum" ? variable.choices : []}
+                    value={field.value ?? ""}
+                    onChange={(value) => field.onChange(value)}
+                  />
+                </FormControl>
+                {variable.description && (
+                  <FormDescription>{variable.description}</FormDescription>
+                )}
+                <FormMessage />
+              </FormItem>
+            );
+
           case "radio":
             return (
               <FormItem>

src/components/layout/nav.tsx

@@ -34,9 +34,9 @@ export function Nav({
         <div className="flex min-w-0 items-center gap-3 sm:gap-6">
           <Link
             href="/"
-            className="flex shrink-0 items-center gap-2 font-semibold tracking-tight"
+            className="font-heading flex shrink-0 items-center gap-2 text-[1.05rem] font-semibold tracking-tight"
           >
-            <Terminal className="size-5" />
+            <Terminal className="text-primary size-5" />
             TriggerShell
           </Link>
           <nav className="flex items-center gap-1">
@@ -45,8 +45,8 @@ export function Nav({
                 key={href}
                 href={href}
                 className={cn(
-                  "text-muted-foreground hover:text-foreground flex items-center gap-1.5 rounded-md px-2 py-1.5 text-sm font-medium transition-colors sm:px-3",
+                  "text-muted-foreground hover:text-foreground hover:bg-muted/60 flex items-center gap-1.5 rounded-md px-2 py-1.5 text-sm font-medium transition-colors sm:px-3",
-                  pathname === href && "bg-muted text-foreground",
+                  pathname === href && "bg-primary/10 text-foreground",
                 )}
               >
                 <Icon className="size-4" />

src/components/layout/not-found-content.tsx

@@ -0,0 +1,29 @@
+import Link from "next/link";
+import { Home } from "lucide-react";
+import { buttonVariants } from "@/components/ui/button";
+import { cn } from "@/lib/utils";
+
+export function NotFoundContent() {
+  return (
+    <div className="mx-auto flex max-w-md flex-col items-center gap-3 py-24 text-center">
+      <span className="text-primary font-mono text-6xl font-semibold tracking-tight">
+        404
+      </span>
+      <h1 className="font-heading text-xl font-medium">Page not found</h1>
+      <p className="text-muted-foreground text-sm">
+        The page you&rsquo;re looking for doesn&rsquo;t exist or may have been
+        moved.
+      </p>
+      <Link
+        href="/"
+        className={cn(
+          buttonVariants({ variant: "outline", size: "sm" }),
+          "mt-2",
+        )}
+      >
+        <Home className="size-3.5" />
+        Back to dashboard
+      </Link>
+    </div>
+  );
+}

src/components/runs/run-status-badge.tsx

@@ -0,0 +1,43 @@
+import { Badge } from "@/components/ui/badge";
+import type { RunStatus } from "@/lib/db/schema";
+import { cn } from "@/lib/utils";
+
+const styles: Record<RunStatus, string> = {
+  queued: "bg-status-queued/12 text-status-queued",
+  running: "bg-status-running/15 text-status-running",
+  succeeded: "bg-status-succeeded/12 text-status-succeeded",
+  failed: "bg-status-failed/12 text-status-failed",
+  cancelled: "bg-status-cancelled/12 text-status-cancelled",
+  timed_out: "bg-status-warn/12 text-status-warn",
+  interrupted: "bg-status-warn/12 text-status-warn",
+};
+
+export const runStatusLabels: Record<RunStatus, string> = {
+  queued: "Queued",
+  running: "Running",
+  succeeded: "Succeeded",
+  failed: "Failed",
+  cancelled: "Cancelled",
+  timed_out: "Timed out",
+  interrupted: "Interrupted",
+};
+
+export function RunStatusBadge({ status }: { status: RunStatus }) {
+  return (
+    <Badge
+      className={cn(
+        "gap-1.5 border-transparent font-mono text-[0.7rem] font-medium tracking-wide uppercase",
+        styles[status],
+      )}
+      variant="outline"
+    >
+      <span
+        className={cn(
+          "size-1.5 shrink-0 rounded-full bg-current",
+          status === "running" && "animate-pulse",
+        )}
+      />
+      {runStatusLabels[status]}
+    </Badge>
+  );
+}

src/components/runs/run-terminal.tsx

@@ -74,13 +74,13 @@ export function RunTerminal({
   }
 
   return (
-    <div className="flex flex-col gap-3">
+    <div className="border-border overflow-hidden rounded-lg border">
-      <div className="flex items-center justify-between">
+      <div className="bg-muted/40 flex items-center justify-between gap-3 border-b px-3 py-2">
         <div className="flex items-center gap-3">
           <RunStatusBadge status={status} />
           {exitCode !== null && (
-            <span className="text-muted-foreground text-xs">
+            <span className="text-muted-foreground font-mono text-xs">
-              exit code {exitCode}
+              exit {exitCode}
             </span>
           )}
         </div>

src/components/runs/xterm-view.tsx

@@ -10,9 +10,9 @@ export interface XtermViewHandle {
 }
 
 const theme = {
-  background: "#09090b",
+  background: "#101215",
-  foreground: "#f4f4f5",
+  foreground: "#edeef0",
-  cursor: "#f4f4f5",
+  cursor: "#e9a857",
   selectionBackground: "#3f3f46",
   black: "#18181b",
   red: "#f87171",
@@ -95,7 +95,7 @@ export const XtermView = forwardRef<XtermViewHandle, XtermViewProps>(
     return (
       <div
         ref={containerRef}
-        className="h-[60vh] overflow-hidden rounded-lg bg-zinc-950 p-2"
+        className="aspect-video w-full overflow-hidden bg-[#101215] p-2"
       />
     );
   },