2026-08-15 18:37:30 +02:00
# Configuration Reference
The config file is YAML, resolved from (in order): `-c/--config` , `TRIGGERSHELL_CONFIG_PATH` , or
2026-08-15 19:15:03 +02:00
`./triggershell.yml` . Values support `${VAR}` / `${VAR:-default}` interpolation, evaluated before
YAML parsing. `database.path` and `logs.dir` are resolved relative to the config file's own
directory, not the current working directory.
Before interpolation, the CLI loads a `.env` file from the same directory as the config file (if
present) into its environment - without overriding any variable already set in the shell - so
secrets referenced via `${VAR}` don't have to be committed alongside the config. `triggershell
init` scaffolds both files together.
2026-08-15 18:37:30 +02:00
2026-08-16 11:14:01 +02:00
The canonical schema is the Zod schema at `src/lib/config/schema.ts` — this document mirrors
2026-08-16 11:03:25 +02:00
it. `triggershell validate` loads and validates the config directly against the schema below (no
separate pre-flight step).
2026-08-15 18:37:30 +02:00
## `server`
2026-08-16 13:55:25 +02:00
| Field | Type | Default | Notes |
| ---------- | ------ | ----------- | ----------------------- |
| `host` | string | `127.0.0.1` | Bind address |
| `port` | number | `4173` | 1-65535 |
| `basePath` | string | `""` | Reserved for future use |
2026-08-15 18:37:30 +02:00
## `auth`
2026-08-16 13:55:25 +02:00
| 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 |
| `users` | array | `[]` | `{username, passwordHash}` — generate via `triggershell users add` |
| `tokens` | array | `[]` | `{name, tokenHash}` — generate via `triggershell users add-token` |
2026-08-15 18:37:30 +02:00
If `enabled: true` , at least one user or token must be configured.
2026-08-15 19:31:41 +02:00
`passwordHash` /`tokenHash` are one-way hashes, so storing them directly in the config is
reasonably safe (same trust model as `/etc/shadow` ). By default `triggershell users add` /
`add-token` instead store the hash in `.env` and give you a `${VAR}` reference to put in the
config, named `TRIGGERSHELL_USER_<USERNAME>_PASSWORD_HASH` / `TRIGGERSHELL_TOKEN_<NAME>_HASH` —
pass `--inline` to those commands to get the raw hash printed for pasting into the config instead.
2026-08-15 18:37:30 +02:00
## `database`
2026-08-16 13:55:25 +02:00
| Field | Type | Default |
| ------ | ------ | ------------------------------- |
2026-08-15 18:37:30 +02:00
| `path` | string | `.triggershell/triggershell.db` |
## `logs`
2026-08-16 13:55:25 +02:00
| 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 |
2026-08-15 18:37:30 +02:00
## `scripts[]`
2026-08-16 13:55:25 +02:00
| Field | Type | Default | Notes |
| ---------------- | -------- | ------- | ------------------------------------------------------------------------------------ |
| `id` | string | — | Required, unique, `[a-zA-Z0-9][a-zA-Z0-9_-]*` |
| `name` | string | — | Required, display name |
| `description` | string | — | Optional |
| `command` | string | — | Required, e.g. `bash` , `node` , `./script.sh` |
| `args` | string[] | `[]` | Fixed leading args, before variable-derived ones |
| `cwd` | string | `./` | Resolved relative to the config file's directory |
| `shell` | boolean | `false` | Opt-in shell interpretation — see the Security Notes in the README before using this |
| `timeoutSeconds` | number | `1800` | 0– `0` means no timeout - the run is never killed for taking too long |
| `variables` | array | `[]` | See below |
2026-08-15 18:37:30 +02:00
## `scripts[].variables[]`
Common fields on every variable:
2026-08-16 13:55:25 +02:00
| Field | Type | Default | Notes |
| ------------- | ----------------------------------- | ------------------ | -------------------------------------------------------------------------------------- |
| `name` | string | — | Required, unique per script |
| `label` | string | `name` | Display label |
| `description` | string | — | Shown as form help text |
| `required` | boolean | `false` | |
| `secret` | boolean | `false` | Only valid on `type: string` . Masks the UI control, redacts from persisted run records |
| `control` | string | type-based default | See mapping below |
| `passAs` | `arg` \| `flag` \| `env` \| `stdin` | `arg` | How the value reaches the process |
| `argName` | string | — | Required for `passAs: arg` /`flag` , e.g. `--env` |
| `envName` | string | — | Required for `passAs: env` , e.g. `SLACK_CHANNEL` |
| `joinWith` | string | `,` | Separator used when an array value is passed as a single arg/env string |
2026-08-15 18:37:30 +02:00
Type-specific fields:
2026-08-16 13:55:25 +02:00
| `type` | Extra fields |
| ------------- | ------------------------------------------------------------------------------------------------- |
| `string` | `default?: string` , `pattern?: string` (regex), `minLength?` , `maxLength?` , `multiline?: boolean` |
| `number` | `default?: number` , `min?` , `max?` , `step?` |
| `boolean` | `default: boolean` (default `false` ) |
| `enum` | `choices: string[]` (required, non-empty), `default?: string` |
| `multiselect` | `choices: string[]` (required, non-empty), `default: string[]` (default `[]` ) |
2026-08-15 18:37:30 +02:00
### UI control mapping
2026-08-16 13:55:25 +02:00
| `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` |
2026-08-16 17:21:11 +02:00
| `enum` | `select` | `radio` , `combobox` (searchable, single-select) |
2026-08-16 13:55:25 +02:00
| `multiselect` | `multiselect` (combobox) | `checkboxGroup` |
2026-08-15 18:37:30 +02:00
### `passAs` semantics
- `arg` — appends `argName value` to argv (e.g. `--env staging` ).
- `flag` — appends `argName` alone, only when the boolean value is `true` .
- `env` — sets `envName=value` in the child process's environment.
- `stdin` — the value is piped to the process's stdin (only one `stdin` variable is meaningful per script).
Values are always passed as discrete argv elements or env vars — never concatenated into a shell
string — so arbitrary characters (including shell metacharacters) in a variable's value are inert.
