# Configuration Reference

The config file is YAML, resolved from (in order): `-c/--config`, `TRIGGERSHELL_CONFIG_PATH`, or
`./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.

The canonical schema is the Zod schema at `app/src/lib/config/schema.ts` — this document mirrors
it. `triggershell validate` runs the Python pre-flight checks below, then that full schema.

## `server`

| Field | Type | Default | Notes |
|---|---|---|---|
| `host` | string | `127.0.0.1` | Bind address |
| `port` | number | `4173` | 1-65535 |
| `basePath` | string | `""` | Reserved for future use |

## `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 |
| `users` | array | `[]` | `{username, passwordHash}` — hash via `triggershell users add` |
| `tokens` | array | `[]` | `{name, tokenHash}` — hash via `triggershell users add-token` |

If `enabled: true`, at least one user or token must be configured.

## `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 |
| `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` | 1–86400 |
| `variables` | array | `[]` | See below |

## `scripts[].variables[]`

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 |
| `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 |

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`) |
| `enum` | `choices: string[]` (required, non-empty), `default?: string` |
| `multiselect` | `choices: string[]` (required, non-empty), `default: string[]` (default `[]`) |

### 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` |
| `multiselect` | `multiselect` (combobox) | `checkboxGroup` |

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