Seristack Config Reference

Root object

Seristack configs are YAML files with a root stacks list.

stacks:
  - name: example
    cmds:
      - echo "hello from seristack"

Attribute	Type	Required	Description
`stacks`	list	yes	List of stack/workflow definitions.

Stack attributes

Attribute	Type	Required	Default	Description
`name`	string	yes	none	Unique stack name. Used by CLI selection, HTTP routes, MCP tools, dependencies, and registry output keys.
`description`	string	no	empty	Human-readable description. Required for exposing a stack as an MCP tool.
`method`	string	no	empty	HTTP method such as `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`. Required for HTTP endpoint exposure.
`urlPath`	string	no	`/<name>`	Custom HTTP route path.
`workDir`	string	no	source/config directory behavior	Working directory for command execution.
`continueOnError`	boolean	no	`false`	Continue command execution after failures and record errors.
`dependsOn`	list	no	`[]`	Stacks that must run before this stack.
`vars`	list	no	empty	Variable definitions and validation rules.
`executionMode`	string	no	`PARALLEL`	Concurrency strategy for count iterations and commands.
`count`	integer	no	`0`	Number of times to run commands. `0` skips execution.
`timeouts`	string	no	`1h`	Per-command timeout using Go duration syntax.
`shell`	string	no	mvdan shell	External shell executable such as `bash`, `sh`, or `powershell`.
`shellArg`	string	no	`-c`	Argument passed to the external shell before the script.
`cmds`	list	no	empty	Commands/scripts executed by the stack.
`output`	string	no	empty	Optional post-processing command using `{{.Self.result}}`.
`discardOutput`	list	no	empty	Registry output keys to remove after the current stack completes.

Variables and validation

Variables can be used in commands with {{.Vars.variable_name}}.

vars:
  - name: env
    value: dev
    required: true
    allowed_value: [dev, stage, prod]

Attribute	Type	Required	Description
`name`	string	yes	Variable name. Must be unique within the stack.
`value`	string	no	Default variable value.
`required`	boolean	no	Final value must not be empty.
`allowed_value`	list	no	Allows only listed values.
`denied_value`	list	no	Rejects listed values.
`allowed_regex`	string	no	Allows only values matching `regex(...)`.
`denied_regex`	string	no	Rejects values matching `regex(...)`.

Only one of allowed_value, denied_value, allowed_regex, or denied_regex can be used per variable. required can be combined with one of them.

Runtime values can come from CLI flags, HTTP query/form/JSON body, HTTP X-* headers, and MCP tool arguments.

Execution modes

Mode	Count iterations	Commands inside each iteration
`PARALLEL`	concurrent	concurrent
`STAGE`	concurrent	sequential
`PIPELINE`	sequential	concurrent
`SEQUENTIAL`	sequential	sequential

Use SEQUENTIAL when ordering matters. Use PARALLEL when maximum concurrency is desired.

Timeouts

timeouts controls the maximum duration for each command execution. Default: 1h.

500ms

500 milliseconds

30s

30 seconds

5m

5 minutes

1h

1 hour

1h30m

1 hour 30 minutes

2.5h

2 hours 30 minutes

Supported units: ns, us/µs, ms, s, m, h. Use 24h instead of 1d.

Shell settings

If shell is omitted, Seristack uses the built-in mvdan shell interpreter. External shells can be configured with shell and shellArg.

shell: bash
shellArg: -c

Commands, output, and registry cleanup

`cmds`

cmds:
  - |
    echo "starting"
    echo "finished"

`output`

Post-process accumulated stack output through {{.Self.result}}.

output: |
  echo '{{.Self.result}}' | grep "^{" | jq -s '{records: ., total: length}'

`discardOutput`

discardOutput: [build, test]

HTTP endpoint behavior

A stack becomes an HTTP endpoint when method is set.

name: greet-api
method: GET
urlPath: /greet

HTTP variables can come from query parameters, form values, JSON request body, and headers beginning with X-.

MCP tool behavior

A stack becomes an MCP tool when description is set. Variables declared in vars become MCP tool arguments.

Complete example

stacks:
  - name: greet-api
    description: Greets a user from CLI, HTTP, or MCP
    method: GET
    urlPath: /greet
    workDir: ./
    count: 1
    timeouts: 30s
    executionMode: SEQUENTIAL
    vars:
      - name: name
        value: engineer
        required: true
        allowed_regex: regex("^[a-zA-Z0-9_-]+$")
      - name: env
        value: dev
        allowed_value: [dev, stage, prod]
    cmds:
      - |
        echo "Hello {{.Vars.name}} from {{.Vars.env}}"

  - name: collect-metadata
    description: Produces JSON metadata for aggregation
    dependsOn: [greet-api]
    count: 2
    timeouts: 5m
    executionMode: SEQUENTIAL
    vars:
      - name: env
        value: dev
    cmds:
      - |
        echo "{\"index\": {{.Count.index}}, \"env\": \"{{.Vars.env}}\", \"status\": \"ok\"}"
    output: |
      echo '{{.Self.result}}' | grep "^{" | jq -s '{records: ., total: length}'

  - name: cleanup-output
    dependsOn: [collect-metadata]
    discardOutput: [greet-api]
    count: 1
    timeouts: 10s
    cmds:
      - echo "discarded greet-api output from memory"