valknarandClaude Sonnet 5
ced99a8e75
A Python CLI (typer) that bootstraps Node/pnpm and launches a Next.js 16 web app for running configured shell scripts: YAML config validated by a shared Zod schema, dynamic per-script forms mapped to shadcn controls, argv-safe execa execution with live WebSocket streaming, SQLite/Drizzle run history, and optional argon2 session + API token auth. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
104 lines
4.5 KiB
Markdown
104 lines
4.5 KiB
Markdown
# Configuration Reference
|
||
|
||
The config file is YAML, resolved from (in order): `-c/--config`, `TRIGGERSHELL_CONFIG_PATH`, or
|
||
`./triggershell.config.yaml`. Values support `${VAR}` / `${VAR:-default}` interpolation against
|
||
the CLI's environment, evaluated before YAML parsing. `database.path` and `logs.dir` are resolved
|
||
relative to the config file's own directory, not the current working directory.
|
||
|
||
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` |
|
||
| `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.
|