valknar
c7bc4421c5
select/radio don't scale to enums with dozens of choices. Reuses the same cmdk Command/Popover primitives multi-select already uses, just single-valued instead of an array.
116 lines
9.2 KiB
Markdown
116 lines
9.2 KiB
Markdown
# 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 `src/lib/config/schema.ts` — this document mirrors
|
||
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 |
|
||
|
||
## `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}` — generate via `triggershell users add` |
|
||
| `tokens` | array | `[]` | `{name, tokenHash}` — generate via `triggershell users add-token` |
|
||
|
||
If `enabled: true`, at least one user or token must be configured.
|
||
|
||
`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.
|
||
|
||
## `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` | 0–86400. `0` means no timeout - the run is never killed for taking too long |
|
||
| `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`, `combobox` (searchable, single-select) |
|
||
| `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.
|