valknarandClaude Sonnet 5
80c11d3bd3
sessionSecret was previously baked directly into the scaffolded config file;
`triggershell init` now generates a .env with TRIGGERSHELL_SESSION_SECRET
instead and references it via ${VAR} interpolation, keeping the actual
secret out of the (often committed) config file. `triggershell dev/start/
validate` load that .env automatically without overriding real env vars.
Also renames the default config filename from triggershell.config.yaml to
triggershell.yml throughout the CLI, app, docs, and examples.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
109 lines
4.9 KiB
Markdown
109 lines
4.9 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 `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.
|