Quickstart

This page takes you from an empty directory to a running workspace and back down again. You will write one profile, break it on purpose to see what a diagnostic looks like, then bring the session up, detach from it, list it and kill it. Nothing here touches your existing tmux sessions ( Glazier never removes a session that it did not create ). The terminal output below is real. I ran these commands against a scratch directory and only shortened the paths and dropped the timestamps from the log lines.

The page assumes that glaze and tmux are installed. If not, start with Installation.

Write a profile#

Glazier looks for a file named .glaze in the current directory. The profile below describes one session with two windows. The first window holds an editor pane and a dev server pane side by side. The second window tails a log file.

1. Open a terminal in a project directory.
2. Create a file named .glaze with this content.
3. Replace the three commands with commands that exist on your machine.

session {
  name = "daemon-run"

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

    pane {
      name     = "editor"
      focus    = true
      commands = ["nvim ."]
    }

    pane {
      name     = "server"
      commands = ["npm run dev"]
    }
  }

  window {
    name = "netwatch"

    pane {
      commands = ["tail -f ./logs/netwatch.log"]
    }
  }
}

Three things to notice before you run it. The session has no starting_directory, so every pane starts in the directory where you run glaze. The editor pane has focus = true, so it is the active pane when you attach. Each pane has one command, and Glazier does not wait for the last command of a pane, so nvim and the dev server can run as long as they like without holding up the session. The Session, Window and Pane pages list every attribute.

Validate the profile#

Glazier validates a profile before it starts tmux. The format command rewrites the file into canonical HCL, and --validate checks the content first.

1. Run format with --validate in the project directory.

$ glaze format --validate
INF the profile is already formatted path=/home/v/runs/arasaka/.glaze

The profile above is already in canonical form, so Glazier does not write the file. A profile with a different indentation or alignment gets rewritten in place. Use --stdout to see the result without a write.

To see what a validation error looks like, change the layout to a name that tmux does not know.

2. Change layout = "main-vertical" to layout = "main-diagonal".
3. Run format --validate again.

$ glaze format --validate
Error: Invalid layout specified

  on /home/v/runs/arasaka/.glaze line 6, in session:
   6:     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

The diagnostic names the file, the line and the attribute, and it shows the line itself. The command exits with code 3, which is the code for a profile with errors. tmux was never started. This is the part of Glazier that I like most: a typo fails here, with a line number, and not three windows into a half-built session. The Diagnostics page describes each kind of message.

4. Change the layout back to main-vertical.

Bring the session up#

1. Run up in the project directory.

$ glaze up
INF creating new session name=daemon-run
INF using the first window name=ice-breaker
INF splitting pane name=editor from=%0
INF splitting pane name=server from=%1
INF running pane commands count=1 name=editor
INF setting pane focus name=editor
INF running pane commands count=1 name=server
INF creating new window name=netwatch
INF splitting pane name=default from=%3
INF running pane commands count=1 name=default

Glazier writes one log line for each step to stderr, then attaches your terminal to the session. You land in the ice-breaker window with the cursor in the editor pane. The log shows only how many commands each pane runs, because a command can contain a secret from a variable. Run up with --debug to see the text of each command. See up.

Detach and list#

1. Press C-b d to detach from the session. C-b is the default tmux prefix.
2. Run ls to list the sessions on the tmux server.

$ glaze ls
NAME        WINDOWS  PATH
daemon-run  2        /home/v/runs/arasaka

The session keeps running after you detach. When you run ls in a pane of the same tmux server, the table marks the session of that pane with an asterisk. When no tmux server runs, ls prints nothing and exits with code 0. See ls.

Take the session down#

1. Run down in the project directory.

$ glaze down
INF session killed session=daemon-run

down reads only the session name from the profile and kills that session. Run it again and nothing happens, which is the point: a script can call down without a check first.

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

See down.

Rebuild without attaching#

The --detached flag creates the session without attaching to it. This is the form that scripts use.

1. Run up with --detached.

$ glaze up --detached
INF creating new session name=daemon-run
INF using the first window name=ice-breaker
...

2. Run the same command again.

$ glaze up --detached

The second run prints nothing and exits with code 0. The session already exists, so Glazier leaves it alone. It never adds windows to a live session. To rebuild the session from the profile, add --clear.

3. Run up with --detached and --clear.

$ glaze up --detached --clear
INF clearing previous session name=daemon-run
INF creating new session name=daemon-run
INF using the first window name=ice-breaker
...

--clear kills the existing session first, then builds a new one from the profile. Without --detached, it attaches afterwards as usual.

Where to next#

You now have the whole loop: write, validate, up, down. The profile above hard-codes everything, which is fine for one project and tedious for ten. One profile, many projects shows how to feed it variables with --var so one file serves every gig. The Session page is the start of the profile reference, with environment variables, hooks and tmux options.