triggershell/docs/CONFIG_REFERENCE.md

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
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.