Let’s get v0.1.5 out of the way first.#

There’s not much to see here, honestly. This is a routine housekeeping and dependency bump release. The only change worthy of a mention is is a bump of golang.org/x/text to address GO-2026-5970. This is the sort of thing you patch promptly even when the practical exposure for a tmux wrapper is nil ( ha-ha-ha ). Alongside that, the Go toolchain moved up to 1.26.4 and testify, urfave/cli and a stack of GitHub Actions all got their routine nudges courtesy of Dependabot. Hey, thanks little buddy!

Download the latest release, replace your current binary and you should be good to go.

v0.1.4 is where the features live.#

Back in July I wrote about adding typed variable blocks to Glazier. That work shipped on July 17th as v0.1.4.

The short recap, if you didn’t read that post is that profiles can now declare the inputs they accept as first-class variable blocks. Just like, you guessed it, Terraform. Each block can carry a primitive type (string, number or bool), a default and a description. No default means the variable is required. Pass a --var the profile never declared and you get a proper located error.

Values are read through the var. namespace and only that namespace:

variable "district" {
  description = "the district the gig is themed after"
  type        = string
  default     = "watson"
}

variable "fixer" {
  type = string
}

session {
  name = "gig-${var.district}"

  window {
    name = "${var.fixer}-ops"

    pane {
      commands = ["echo ${var.fixer} has the next job"]
    }
  }
}

$ glaze up --var fixer=wakako
$ glaze up --var district=arasaka --var fixer=wakako

That post covers the design reasoning, the type coercion and the breaking namespace migration in detail. So, no need to reshash it all here. What it doesn’t cover is everything else that snuck into the release after I hit publish button.

Support for locals.#

Variables are inputs. They cross the boundary from the outside world into your profile via --var flags, var files or defaults. But the moment I had proper variables I ran into their natural companion problem; derived values. The thing you compute from an input once and then want to reuse in five places without copy-pasting the same expression five times.

Terraform solves this with locals and, because Glazier remains an unapologetic love letter to Terraform’s parser, it does as well:

variable "district" {
  default = "night city"
}

locals {
  slug    = lower(replace(var.district, " ", "-"))
  session = "gig-${local.slug}"
  logfile = "${path.pwd}/logs/${local.slug}.log"
}

session {
  name = local.session

  window {
    name = "${local.slug}-ops"

    pane {
      commands = ["tail -f ${local.logfile}"]
    }
  }

  window {
    name = "editor"

    pane {
      commands = ["nvim"]
    }
  }
}

You declare named values in a locals block at the top level and read them back through local.<name>. Plural block and a singular reference is exactly how Terraform does it.

A local can reference the var.*, env.*, path.* namespaces, the whole function library and, crucially, other locals. In any order. This works fine:

locals {
  session = "gig-${local.slug}"                    # references slug...
  slug    = lower(replace(var.district, " ", "-")) # ...declared after it
}

Under the hood resolution just keeps iterating, evaluating whatever it can each pass until the end. Whatever’s left over then reports its real evaluation diagnostics, so a genuine fat-fingered mistake surfaces as the actual error rather than being masked by ordering machinery. If you accidentally declare the same local twice you’ll get told exactly where both declarations live.

The one thing you can’t do with a local is set it from the command line and this is by design. Variables are the contract with the outside world; locals are private. If a value should be overridable, it’s a variable. If it’s just an expression you’re tired of repeating, it’s a local. Having the language enforce that distinction is one of those small things that keeps a profile clean as it grows.

They also pair nicely with the new random function and HCL’s inline comprehensions, both of which landed in this release too:

locals {
  editors = ["nvim", "hx", "vim"]
  greeting = random([for g in ["hello", "choom", "wake up samurai"] : title(g)])
}

random(list) returns a uniformly random element of a list as a string. Did anyone ask for this? Absolutely not, but you deserve nice things.

lol… lmfao.#

The July post ended with me musing about adding *.tfvars-style functionality and asking, and I quote, “Surely, I won’t fall for this again?”

Yeah, so v0.1.4 also ships with --var-file support:

# gig.vars
district = "japantown"
fixer    = "wakako"

$ glaze up --var-file gig.vars
$ glaze up --var-file gig.vars --var fixer=dino

A var file is plain HCL; a name = value attributes written once per line. I originally supported JSON files too and then ripped that out before release, because maintaining a second parse path for a format nobody was going to use failed the smell test. In other words, “YAGNI”.

Precedence works the way you’d expect: defaults go first, a var file overrides defaults and an explicit --var flag always has the final say. In the second command above fixer comes out as dino no matter what the file thinks.

Strictness from the flag side applies here too. An entry in a var file that names a variable the profile never declared is an error. Values are coerced to their declared types and every problem in the file is reported all at once for convenience.

Our first contributor has entered the chat!#

This release contains the first fix from an actual outside contributor. ThreeToes tracked down an annoying initialisation bug where the first window in a profile would be ignored and cleaned up on startup. Leaving you with either a stray default terminal or only the subsequent windows.

Someone who isn’t me not only ran the thing, they read the source and fixed it. That’s a genuinely lovely milestone for a hobby project. Thanks, man!

Oh, and the repo finally has a proper SPEC.md. A full reference for the profile format describing every block, namespace and function.

In closing …#

Release notes are like backups. Everyone agrees they’re important and nobody does them until it’s embarrassing.

As always, it’s up on GitHub under MIT. If you’ve got Go installed:

$ go install github.com/wilhelm-murdoch/glazier/cmd/glaze@latest

Or, grab a prebuilt binary from the releases page, checksums and provenance attestations are included. Small note on this, I do plan on adding support for all your favourite package managers to make this process a bit more intuitive. Homebrew first as a test run, then all the other you’d expect.

If you’ve opinions on locals, var files or what Glazier should learn next, the comments are right below.

P.S. - I’ve another secret project in the works and I’m using it to declaratively generate Open Graph social cards for the blog. I thought I’d create a format dedicated to Glazier releases.

So, over the course of the past few days Glazier learned a new trick. Profiles can now declare the variables they accept, give them primitive types, mark them as required and read them back through a proper var. namespace.

Out with the old.#

Technically speaking, Glazier has had variable support since day one. You could pass --var region=watson and reference ${region} anywhere in your profile and that was that. Anything you passed got dumped into a flat namespace and any name you referenced, but forgot to set, quietly resolved to an empty string.

That’s fine right up until you fat-finger ${reigon} and spend ten minutes wondering why your session name has a hole in it. The whole reason I built this thing was to get Terraform’s “here is exactly what you did wrong and where” experience.

Letting variables fail silently just felt a bit like an own-goal.

Profiles can now declare what they accept.#

Because this whole thing is kind of a love letter to Terraform’s parser, the idea behind variable definitions is functionally the same. You declare a variable block, it sits at the top level next to your session and that’s the input you’re allowed to pass:

variable "district" {
  description = "the district the gig is themed after"
  type        = string
  default     = "watson"
}

variable "fixer" {
  type = string
}

session {
  name = "gig-${var.district}"

  window {
    name = "${var.fixer}-ops"

    pane {
      commands = ["echo ${var.fixer} has the next job"]
    }
  }
}

First, you reach a variable through var. and only var. now, so it reads exactly like it would in a .tf file. Second, district has a default and fixer doesn’t, which turns out to matter quite a lot in a second.

$ glaze up --var fixer=wakako # district falls back to "watson"
$ glaze up --var district=arasaka --var fixer=wakako

So, here you are using the same templated profile to define two seperate sessions decided entirely by flags.

Pass it something it doesn’t know and it says so.#

If you pass a --var for a variable the profile never declared, you no longer get a silent shrug. You get a proper error:

Error: Undefined variable

A value for "ghost" was passed with --var, but the profile declares no
variable "ghost". Add a variable "ghost" {} block, or remove the flag.

I went back and forth on this one. Being strict about undeclared flags is the sort of thing that feels pedantic until the day it catches a typo you’d have otherwise chased for half an hour. In this case strict won.

A --var you can’t explain is almost always a mistake, so Glazier now treats it like one.

No default means you have to mean it.#

A variable without a default is required. Leave it unset and up refuses to do anything until you supply it:

Error: Missing required variable

  on .glaze line 6, in variable "fixer":
   6: variable "fixer" {

The variable "fixer" has no default, so a value must be supplied with
--var fixer=<value>.

This is the bit that makes a profile a genuine contract rather than a suggestion. If a layout is useless without a fixer, declare fixer with no default and the tool will make absolutely sure you provided one before it touches tmux.

Proper type-checking.#

Every variable declares a type. Use one of the bare keywords string, number or bool. The value you hand over on the command line is coerced into that type and rejected if it doesn’t fit:

variable "base_index" {
  type    = number
  default = 1
}

$ glaze up --var base_index=two

Error: Invalid variable value

  on .glaze line 1, in variable "base_index":
   1: variable "base_index" {

The value passed for variable "base_index" with --var cannot be used as
number: a number is required.

two is not a number, so you find out before anything launches rather than after tmux has already swallowed a garbage option and started behaving oddly. Booleans get the same treatment: true and false are fine, anything else is shown the door. Unfortunately, I decided not to go with truthy or falsey value coercion.

I kept it to the three primitives on purpose. The moment you add list(string) and friends you’re also signing up for coercing comma-soup off the command line into nested types. That’s a much bigger can of worms than a tmux helper needs to open today.

Though, obviously, if you disagree you’re more than welcome to leave a comment below!

A namespace for everything.#

I’ll be honest about the consequence here. This is a breaking change and pretending otherwise would be rude. The old flat ${region} style is gone. If a value comes from a declared variable, you read it as var.region.

Which raised a genuinely interesting design question I sat with for a while. If variables are only ever used inside a session, why not declare them inside the session block too? It feels more intuitive at first though, but it’s also wrong.

However you nest the declaration, the reference is still flat and global; you write var.fixer, never session.var.fixer. Declaring something file-global but reading it block-scoped is incoherent and a variable is really an input to the invocation, sitting conceptually above the session and not a property of it. So they live at the top level, exactly where Terraform puts them. I borrowed both the syntax and the reasoning.

Where did the environment variables go?#

They also got their own namespace. Previously GLAZE_ENV_token showed up as a bare ${token}, sharing the same flat namespace as everything else. Now it lives under an env. namespace, which makes the three sources nicely symmetric:

• var.* for variables you declared and passed with --var
• env.* for GLAZE_ENV_* environment variables
• path.pwd & path.base the unchanged built-ins

session {
  name = "host-${env.box}"

  window {
    pane {}
  }
}

$ GLAZE_ENV_box=nightcity glaze up

session = host-nightcity

There’s no declaration needed for env.*; the environment is the environment. Only the things you pass with --var have to be declared, because those are the inputs you are claiming the profile accepts.

Tearing down a session.#

If a required variable now blocks up, doesn’t that wreck glaze down? I recently taught the down command to evaluate only the session name so it doesn’t need every variable buried deep in the profile just to kill a session. Surely required variables undo that?

They don’t and this was the fiddly bit to get right. down resolves variables leniently. A variable used solely in some pane command, far away from the session name, is neither required nor evaluated when you’re tearing things down:

variable "beep" {
  type = string
}

session {
  name = "daemon-run"

  window {
    pane {
      commands = ["echo ${var.beep}"]
    }
  }
}

$ glaze down
INF nothing to do; session is not running session=daemon-run

If beep isn’t provided, the command just accepts it and moves on, because down never needed it. up enforces the full contract; down only asks for what the name actually depends on. Obviously, the exception here is if a variable is used to construct the actual session name. Other than that, this is an idempotent no-op.

Validation has been updated too.#

glaze format --validate decodes a profile and reports diagnostics without ever touching tmux and it now enforces the entire variable contract. Miss a required variable and validation fails right there:

$ glaze format --validate
Error: Missing required variable
  ...

$ glaze format --validate --var region=us-east-1
# clean. nothing to report.

So, you can lint a parameterised profile in CI, or just before committing it and know it holds together before you ever try to bring it up.

This literally broke all my current profiles.#

And I regret nothing. The flat-namespace migration touched pretty much everything; sample profiles, the docs, a pile of tests and all the profiles I actually use day to day. Normally this is the part of a post where I’d sketch out a careful migration path and apologise profusely.

But, the entire userbase of this tool is almost, as far as I can tell, me. So the migration path is “I’ll fix all my profiles tomorrow morning over coffee.”

To migrate is easy enough, just define your variables and prefix all references with var.. This is still currently in beta after all.

In closing…#

Under the hood this turned into a more interesting refactor than I expected. hcldec wants to decode a whole file body against one spec and it flatly refuses to tolerate a variable block sitting next to the session it doesn’t know about. The trick was to stop handing it the whole file, pull the session block out myself and decode just its body, which leaves the variable blocks to be gathered and resolved in their own quiet little pass beforehand. There’s a tidy PartialContent implementation in there that was heaps of fun to figure out.

None of which a tmux wrapper strictly needed, of course. But “strictly needed” stopped being the bar around the time I added a fuzzer. The point was to feel out how Terraform turns a typo into a friendly, located error and now Glazier does a respectable impression of it for variables too.

I’m still ironing out all the kinks and ensuring I still have an 80% baseline in testing and code coverage, but I’m planning to release this and a few bug fixes and dependency bumps this weekend. Tomorrow-me gets to read this back with fresh eyes and decide how much of it past-me oversold. Very nice.

Until I merge it in, you can play with the latest release here.

And now I’m thinking about adding *.tfvars-like functionality. Surely, I won’t fall for this again?

variable "name" {
  description = optional(string)
  type        = required(string | bool | number)
  default     = optional(type)
}

Time to do what I do best: make things more complicated than they have any right to be.

So I built Glazier; a small command-line tool that lets me describe a tmux workspace once and recreate it on demand. Type glaze up and the sessions, windows and panes I described spring back into existence exactly how I left them.

This has been a slow-burning labour of love for the better part of two years and it’s finally in a state where I feel comfortable letting other people look at it. So let’s talk about why it exists, what else is out there and how this one is different.

It’s just a config file, right?#

That was the idea, at least. I just wanted to stop rebuilding the same layouts over and over. But, as is tradition, I didn’t want to make it too easy for myself.

There was a second, more selfish motivation. As a platform engineer, there isn’t a day that goes by where I don’t work with Terraform. I’ve always been quietly fascinated by how it parses and validates its configuration. That whole experience of getting a precise, friendly error pointing at the exact line you fat-fingered, rather than a stack trace and a 🖕. I wanted to understand how that machinery actually worked.

So, I’m a heavy tmux user and I wanted to learn HCL parsing from the inside. These two things lined up a little too perfectly. So Glazier’s profiles aren’t YAML; they’re HCL. The same configuration language Terraform uses and parsed with the same underlying library.

Here’s a basic profile:

session {
  name = "daemon-run"

  window {
    name   = "ice-breaker"
    layout = "main-vertical"

    pane {
      commands = ["nvim ./payloads"]
    }

    pane {
      commands = ["watch -n1 netwatch --target arasaka-mainframe"]
    }
  }
}

Drop that in a file called .glaze, run glaze up next to it and you’re jacked in.

I’m not the first to do this; not even the 3rd… or the 4th.#

This is a thoroughly-solved problem and I’d be doing you a disservice if I pretended otherwise. There’s a whole shelf of mature, battle-tested tools that do effectively the same thing:

• tmuxinator is the one most are familiar with. Written in Ruby with YAML profiles. Probably what most people reach for.
• teamocil is also written Ruby; also uses YAML.
• smug is written in Go and uses YAML and is the closest in spirit to Glazier if we’re being honest.
• tmuxp is written in good’ole reliable Python and it’ll happily eat YAML or JSON.

If you already use and trust one of these, I’ll be straight with you: there isn’t a compelling reason to switch. Keep using what works. I’m not here to convince anyone to rip out a tool they’re happy with.

But if you’re still reading, here’s what I like about mine.

So what’s actually different?#

The profile validates itself!#

This is the part I set out to build, so it’s the part I’m fondest of. Because Glazier is built on HCL, it inherits Terraform-style diagnostics for free. Mistype a layout, point a starting directory at somewhere that doesn’t exist or forget a required block and you don’t get a vague “something went wrong fuck you”. You get told exactly what and where you messed up:

Error: Invalid layout specified

  on .glaze line 4, in session.window:
   4:     layout = "main-plumbus"

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

There’s a glaze format command that rewrites your profile into a canonical style and, with --validate, reports any of these diagnostics without touching tmux at all. Both of these scratch exactly the itch that started the whole project.

Variables, templates and string functions! Oh, my!#

A static layout is useful. A templated one is better. Profiles can reference variables and you can feed those in from --var flags or GLAZE_ENV_* environment variables:

session {
  name               = "ops-${region}"
  starting_directory = path.pwd

  window {
    name = upper(region)

    pane {
      commands = ["k9s --context ${region}"]
    }
  }
}

$ glaze up --var region=ap-southeast-2

Look familiar? If you work with Terraform it does!

There’s a handful of built-in string functions too. upper, lower, replace, trimspace, join and friends which act as thin wrappers over the same go-cty standard library Terraform uses. Plus, a couple of freebies like path.pwd and path.base so a profile can adapt to wherever it’s run from.

It doesn’t lie to you about timing.#

This is the bit of engineering I’m quietly proudest of, even though nobody will ever see it. When you fire a sequence of commands into a tmux pane, the naive approach is to blast them in with a sleep between each one and hope the previous command finished. That’s flaky and it’s how a few other tools handle it.

Glazier instead serialises commands through tmux’s own wait-for signalling, so each command genuinely waits for the previous one to finish before the next is sent. There are no fixed sleeps and no races. The one exception is the final command in a list, which is sent fire-and-forget. If your last command is a long-running dev server or tail -f, waiting on it would hang up forever.

I learned that last part the hard way.

It can mostly save a session!#

Run glaze save inside a live session and it’ll capture the structure back out into a profile: windows, panes, names, layouts, focus and starting directories. The “mostly” is doing some load-bearing work in that sentence and it’s a deliberate choice, not a missing feature.

save will not export your pane commands, environment variables, hooks or tmux options. Why? Because each of those is a footgun:

• Commands would re-execute on the next up. A forgotten rm -rf captured from some pane could ruin your whole day on replay.
• Environment variables can only be read as the entire session environment. This means inherited secrets, tokens and keys getting written into a file you might commit. That’s a big fat no from me, dawg.
• Options read back as effective state, hopelessly tangling up with your tmux.conf and manual tweaks.

So, a saved profile is a scaffold. It gets the geometry right and you add back the commands and config you actually want by hand.

A real profile.#

Enough talk. Here’s the profile I actually use when working this website:

session {
  name = path.base

  envs = {
    HUGO_GITHUB_TOKEN        = "${github}"
    HUGO_ACTIVITY_GRAPH_DEMO = "${demo}"
  }

  window {
    name  = "editor"

    pane {
      commands = ["nvim"]
    }
  }

  window {
    name  = "terminal"
    focus = true

    pane {}
  }

  window {
    name = "server"

    pane {
      commands = ["hugo server --disableFastRender"]
    }
  }

  window {
    name = "git"

    pane {
      commands = ["lazygit"]
    }
  }
}

Running glaze up --var github=*** --var demo=true gives me the following windows:

• My editor of choice; NeoVim.
• A dedicated terminal session.
• The Hugo server along with some HUGO_ specific environment variables; values sourced from the CLI.
• Finally, lazygit to manage and commit my changes.

Further, the --var arguments aren’t really necessary as you could just export GLAZE_var_name as well and Glazier will pick it up automatically.

Anyways, because the session is just a named thing, the rest of the lifecycle is tidy too. List what’s running with glaze ls:

$ glaze ls
NAME      WINDOWS  PATH
glazier*  2        /home/wilhelm/Development/wilhelm.codes
scratch   1        /tmp

The asterisk marks the session I’m currently attached to. When I’m done, I tear it down by profile:

$ glaze down

down is idempotent and that’s on purpose. Bringing down a session that isn’t running is a no-op, not an error, so it’s safe to drop in scripts without defensive checks.

Some over-engineered bits …#

To be frank a tool that shells out to tmux did not strictly need a fuzzed HCL parser, build provenance attestations on its release binaries or a CI pipeline that runs the test suite against multiple Go versions and operating systems.

But, that was never really the point. The point was learning how Terraform’s parser ticks, working out how to drive tmux reliably without sleeps and over-engineering the ever-loving-shit out of an already-solved problem because it was fun. Every constraint I imposed upon myself taught me something new. This is ultimately the only metric I actually care about for a hobby project like this.

Where to get it?#

It’s up on GitHub with a shiny MIT license. If you’ve got Go installed:

$ go install github.com/wilhelm-murdoch/glazier/cmd/glaze@latest

Or, grab a prebuilt binary from the releases page. I currently build for Linux and macOS on both amd64 and arm64. Each one ships with a checksum and a signed provenance attestation, because of course it does.

In closing …#

I would confidently say Glazier has moved on from “experimental” to “stable”. It works and I use it every single day. But, there are rough edges and there may be any number of unencountered failure modes. The down and ls commands only landed recently and I’m not sure if the latter should remain. I’ve also got a running list of ideas I haven’t talked myself out of yet. Like, something similar to Terraform’s *.tfvars files or defining typed variables.

If you’re already happy with Tmuxinator or Smug, then stick with them. But if the idea of a declarative, self-validating, slightly-too-clever tmux profile appeals to you, or you just want to read some Go that wraps tmux in ways it was probably never meant to be wrapped, I’d love for you to take it for a spin.

I sincerely hope you find Glazier as useful as I had fun building it.