Scripting with glaze

A tool that is pleasant in a terminal is often a pain in a script: logs mixed into the output you wanted to capture, one exit code for every kind of failure, a teardown step that errors when there is nothing to tear down. Glazier tries to behave. Each stream has one job, each exit code has one meaning and glaze down does not complain about a session that is already gone.

Output streams#

• Glazier writes log lines and diagnostics to stderr.
• Only command output goes to stdout: the ls table and the profile from format --stdout and save --stdout.
• Thus glaze save --stdout > saved.glaze writes a clean profile.
• Glazier writes colour only when stderr is a terminal. Set NO_COLOR to turn colour off.

Exit codes#

Each exit code has one meaning. A script can use the code to find the cause of a failure:

A usage error names the flag and points at --help:

$ glaze up --var nope
usage error: invalid value "nope" for flag -var: the --var `nope` does not match the required format of `key=value` (see `glaze up --help`)
$ echo $?
2

Roll-back on failure#

• When up fails or a signal stops it, Glazier removes the session that this run created. Thus the next up starts again from nothing.
• Glazier never removes a session that existed before the run.
• A second signal stops Glazier at once, with no clean-up.
• Use --keep-on-failure to keep the partly built session, so that you can examine it. Run glaze up --clear to build it again.

Idempotent teardown#

glaze down evaluates only the session name. A variable that appears only deeper in the profile is not required. A session that is not running causes no error:

$ glaze down --session nothing-here
2026-10-04 22:09:51 INF nothing to do; session is not running session=nothing-here
$ echo $?
0

Thus a script can run down before up without a check. An interpolated name, for example name = "gig-${var.district}", resolves through the same --var flags as up. See glaze down.

Validate in CI#

glaze format --validate decodes the profile and reports diagnostics. It enforces the full variable contract: a required variable must get a value from --var or from a default. One run reports each problem that Glazier can find, and each error gives exit code 3. tmux is not necessary for this step.

$ glaze format --validate --stdout --var project=$PWD > /dev/null
Error: Invalid layout specified

  on /home/v/code/arasaka/.glaze line 9, in session:
   9:     layout = "main-diagonal"

The layout value of "main-diagonal" is not a supported preset
(even-horizontal, even-vertical, main-horizontal, main-vertical, tiled) nor a
valid tmux layout string.

the glaze profile contains errors
$ echo $?
3

Use --stdout in CI so that the check does not rewrite the file. Without it, format writes the canonical form back to the profile. It skips the write when the file is already formatted, so the modification time does not change.

A script#

This script validates a profile, builds the session, snapshots it and tears it down again:

#!/bin/sh
project=$PWD

glaze format --validate --stdout --var project="$project" > /dev/null || exit $?

glaze up --detached --var project="$project"
case $? in
  0) ;;
  4) echo "tmux is unreachable" >&2; exit 4 ;;
  *) echo "glaze up failed" >&2; exit 1 ;;
esac

glaze save --session "main@$(basename "$project")" --stdout > saved.glaze || exit $?

glaze down --var project="$project"

Notes on the script:

• --detached creates the session and does not attach. Without a terminal, up warns and does not attach, so the flag also keeps the log quiet.
• save runs outside a pane of the tmux server, so the --session flag is necessary.
• The shell creates saved.glaze before glaze runs. Check the exit code of save before you trust the file.
• The session name in this profile is ${var.branch}@${path.base}, so save --session gets the name that up built. See One profile for many projects.

Glazier waits for pane commands with no time limit by default. In a script, set --command-timeout on up, so that a stuck npm install does not stall the job. See Run commands reliably.