valknarandClaude Sonnet 5
acc6715a88
Previously every script was forced to have a positive timeout capped at 24h, with no way to run something genuinely unbounded. execa only enforces its timeout option when it's greater than 0, so this just relaxes the schema's lower bound from positive to >= 0 and lets that flow through unchanged - no engine logic needed beyond a clarifying comment. The 1800s default and 86400s cap for finite timeouts are unchanged; 0 is an explicit opt-in, not the default. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
115 lines
5.4 KiB
Markdown
115 lines
5.4 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}` — 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` |
|
||
| `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.
|