triggershell/docs/CONFIG_REFERENCE.md

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.