valknar
90d68f2510
CI caught this on the v1.1.0 tag push - format:check wasn't run locally before committing.
221 lines
14 KiB
Markdown
221 lines
14 KiB
Markdown
# TriggerShell
|
|
|
|
A CLI that launches a self-hosted web app for running your shell scripts: define scripts and
|
|
their parameters in a config file, get a generated form UI, run them asynchronously with live
|
|
streaming output, and keep a searchable history — all behind optional login, with a full REST/WS
|
|
API for automation.
|
|
|
|
## Features
|
|
|
|
- **One config file** defines the server, auth, and every script (command, working dir, timeout,
|
|
and typed/validated variables with defaults and choices).
|
|
- **Generated forms** — each variable renders as the right control (text, number, slider, select,
|
|
radio, checkbox, switch, multi-select) based on its type, with client- and server-side validation
|
|
from the same schema.
|
|
- **Safe execution** — scripts run via argv arrays, never a shell string. User input can never
|
|
break out into shell metacharacters.
|
|
- **Live monitoring** — stdout/stderr and status stream over WebSocket to an in-browser terminal
|
|
view; cancel a run from the UI or the API.
|
|
- **Run history** — every run's variables (secrets redacted), resolved command, status, exit code,
|
|
and full log are persisted in SQLite.
|
|
- **Optional auth** — built-in username/password sessions and API tokens, toggleable per config.
|
|
- **REST + WebSocket API** for scripting your script runner.
|
|
|
|
## Quickstart
|
|
|
|
```bash
|
|
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 start # start the app and open the browser
|
|
```
|
|
|
|
Edit `triggershell.yml` to add your own scripts (see [Configuration](#configuration) below), then
|
|
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
|
|
|
|
- Node.js >= 20 — the only thing you need installed. Everything else `triggershell` needs ships
|
|
inside the package itself and is resolved automatically when you install it.
|
|
|
|
## Configuration
|
|
|
|
TriggerShell is driven entirely by one YAML file (default: `./triggershell.yml`, override with
|
|
`-c/--config` or `TRIGGERSHELL_CONFIG_PATH`). Secrets referenced via `${VAR}` (like
|
|
`auth.sessionSecret`) are meant to live in a `.env` file next to the config, not in the config
|
|
itself — `triggershell init` generates both. Minimal example:
|
|
|
|
```yaml
|
|
server:
|
|
host: 127.0.0.1
|
|
port: 4173
|
|
|
|
auth:
|
|
enabled: true
|
|
sessionSecret: "${TRIGGERSHELL_SESSION_SECRET}" # >= 32 chars
|
|
users:
|
|
- username: admin
|
|
passwordHash: "${TRIGGERSHELL_USER_ADMIN_PASSWORD_HASH}" # from `triggershell users add`
|
|
tokens: []
|
|
|
|
database:
|
|
path: .triggershell/triggershell.db
|
|
logs:
|
|
dir: .triggershell/logs
|
|
retentionDays: 30
|
|
|
|
scripts:
|
|
- id: deploy-service
|
|
name: Deploy Service
|
|
command: bash
|
|
args: ["./scripts/deploy.sh"]
|
|
timeoutSeconds: 600
|
|
variables:
|
|
- name: environment
|
|
type: enum
|
|
choices: [staging, production]
|
|
default: staging
|
|
required: true
|
|
passAs: arg
|
|
argName: --env
|
|
- name: dryRun
|
|
type: boolean
|
|
default: false
|
|
passAs: flag
|
|
argName: --dry-run
|
|
```
|
|
|
|
A full, richly-commented example lives at [`examples/triggershell.yml`](examples/triggershell.yml)
|
|
(with a matching [`.env.example`](examples/.env.example)), and the complete field-by-field
|
|
reference is in [`docs/CONFIG_REFERENCE.md`](docs/CONFIG_REFERENCE.md).
|
|
|
|
Each variable's `type` (`string` / `number` / `boolean` / `enum` / `multiselect`) picks a sensible
|
|
default UI control; set `control` explicitly to override it (e.g. `slider` for a `number`, `radio`
|
|
for an `enum`). `passAs` (`arg` / `flag` / `env` / `stdin`) decides how the validated value reaches
|
|
the script — always as a discrete argv element or env var, never interpolated into a shell string.
|
|
|
|
## 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 against the full schema |
|
|
| `triggershell start [-c CONFIG] [--port] [--host] [--no-browser]` | Run the web app |
|
|
| `triggershell doctor [-c CONFIG]` | 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 |
|
|
| `triggershell service logs [-n LINES] [--no-follow] [--system]` | Tail the systemd unit's logs (wraps `journalctl -o cat`, so each line is raw JSON - pipe through `jq` for pretty-printing) |
|
|
|
|
### 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
|
|
|
|
- **Scripts** (`/`) — every configured script as a card; click through to its run form.
|
|
- **Run form** (`/scripts/:id`) — a generated form for the script's variables, validated before
|
|
submit.
|
|
- **Run detail** (`/runs/:id`) — live streaming terminal output, status, exit code, and a Cancel
|
|
button while the run is active.
|
|
- **History** (`/runs`) — every past run, filterable by script/status via the API (`?scriptId=`,
|
|
`?status=`).
|
|
|
|
## Authentication
|
|
|
|
Set `auth.enabled: false` for trusted/local-only use — the app then requires no login at all.
|
|
When enabled, sessions are signed/encrypted cookies (no server-side session store), and API
|
|
clients can instead send `Authorization: Bearer <token>` using a token from `users add-token`.
|
|
Passwords are hashed with argon2id; only the hash ever lives in the config file.
|
|
|
|
## API Reference
|
|
|
|
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 |
|
|
| GET | `/api/auth/session` | Current auth state |
|
|
| GET | `/api/scripts` | List configured scripts |
|
|
| GET | `/api/scripts/:scriptId` | Full script schema (variables, UI hints) |
|
|
| POST | `/api/scripts/:scriptId/runs` | Start a run: `{variables: {...}}` |
|
|
| GET | `/api/runs` | History: `?scriptId=&status=&limit=&cursor=` |
|
|
| GET | `/api/runs/:runId` | Single run's status/metadata |
|
|
| POST | `/api/runs/:runId/cancel` | Cancel an active run |
|
|
| GET | `/api/runs/:runId/logs` | Full or tailed log output (`?tail=&download=`) |
|
|
| WS | `/ws/runs` | Subscribe to a run's live output/status; send `cancel` |
|
|
|
|
## 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 install
|
|
pnpm dev # tsx watch server.ts - reads TRIGGERSHELL_CONFIG_PATH from the environment
|
|
pnpm lint
|
|
pnpm typecheck
|
|
pnpm test # CLI unit tests (src/cli/**/*.test.ts)
|
|
pnpm db:studio # browse the SQLite DB
|
|
```
|
|
|
|
Repo layout — the repo root itself is the published npm package (Next.js app + the `triggershell`
|
|
CLI in `bin/`/`src/cli/`), alongside:
|
|
|
|
```
|
|
examples/ A runnable example config + scripts
|
|
docs/ Config/architecture/API reference docs
|
|
```
|
|
|
|
See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for how the pieces fit together.
|
|
|
|
## Security Notes
|
|
|
|
- Scripts are always spawned with an argv array (`execa`), never a shell string — variable values
|
|
can never inject additional shell commands. A script's own `command`/`args` may still use `shell:
|
|
true` as an explicit, documented opt-in when the script genuinely needs pipes/globs; that
|
|
reintroduces shell interpretation of `passAs: arg` values, so prefer `passAs: env` for anything
|
|
user-controlled in that case.
|
|
- `secret: true` variables are masked in the UI and redacted from persisted run records; only the
|
|
live child process ever sees the real value.
|
|
- The server binds to `127.0.0.1` by default — set `server.host` explicitly to expose it further.
|
|
- Route Handlers check auth themselves (`requireAuth()`); `proxy.ts` is only a fast, optimistic
|
|
redirect layer, not the security boundary.
|
|
- `auth.sessionSecret` should live in `.env`, not the config file — `triggershell init` sets this
|
|
up for you. `passwordHash`/`tokenHash` are one-way hashes (not the secrets themselves), so
|
|
storing them directly in the config is reasonably safe — the same trust model as `/etc/shadow`
|
|
or `.htpasswd` — but `triggershell users add`/`add-token` store them in `.env` via `${VAR}` by
|
|
default too, for cases where you don't want them readable by anyone with config access at all.
|
|
Pass `--inline` to get the old behavior of printing the raw hash to paste into the config.
|
|
|
|
## License
|
|
|
|
MIT — see [LICENSE](LICENSE).
|