Templates

Requires Extended

Exporting, importing and applying templates require Extended (one-time or subscription). Local templates are a one-shot file you export and import — not to be confused with Team Template / Cloud Sync, which are Subscription-only.

Overview

A template is a portable blueprint of a workspace — its pane layout and the shells inside it — saved as a single file you can store, share, or reuse later.

Templates are a one-shot mechanism: you export a file and import it when you need it. They are not the same as continuous sync (see Templates vs continuous sync).

To unlock templates, see Activating your license.

What a template captures

A template records:

• The layout — how the panes are arranged in the workspace.
• Each terminal’s shell — its shell type (PowerShell, Bash, …) and its title.

A freshly exported template does not include your real working directories or any startup commands. Working directories are deliberately left out so a shared template never leaks the folder paths from your machine — you fill them in when you import (in the preview dialog), or by editing the file directly.

Template file format

A template is a plain JSON file with the extension .gridmux-template.json. At a high level it contains:

{
  "meta": {
    "name": "My project",
    "platform": "win32",
    "createdAt": "2026-05-31T10:00:00.000Z",
    "version": "1.0",
    "minGridmuxVersion": "0.1.0"
  },
  "workspace": {
    "name": "My project",
    "layoutConfig": { "...": "pane layout" }
  },
  "terminals": [
    { "shellType": "powershell", "title": "build", "cwd": null, "startupCommands": [] }
  ]
}

• version is the template schema version. On import, Gridmux rejects a schema major version it doesn’t understand.
• minGridmuxVersion is the lowest Gridmux version that can open the template. A template that needs a newer version than yours is rejected with a clear message.
• cwd and startupCommands are empty in a fresh export; you can fill them in via the import preview or by editing the JSON.

Exporting a template

Export always captures the active workspace. There are two ways to start it (neither has a keyboard shortcut):

• From the menu bar: File → Export Workspace as Template…
• Right-click a workspace tab and choose Export as Template…

Gridmux opens a save dialog where you choose where to write the .gridmux-template.json file.

Importing a template

From the menu bar, choose File → Import Template… and pick a .gridmux-template.json file. Gridmux validates it (schema and version) and then opens a preview dialog showing:

• the template’s metadata (name, the platform it was created on, date);
• its terminals — shell type, title, and a working directory field;
• warnings, where relevant (shells that aren’t installed on this machine, or a template created on a different platform).

In the preview you can set the working directory for each terminal. Shell type, title, and startup commands are shown read-only. Confirm with Apply, or cancel to discard.

Applying a template

When you click Apply in the preview, Gridmux creates a new workspace from the template. It does not overwrite or modify your current workspace — your existing workspaces are left untouched.

During apply:

• Terminals whose shell isn’t installed on this machine are skipped. If none remain, Apply is unavailable.
• The saved layout is rebuilt in the new workspace.
• Any startup commands run in their terminals, one after another.

Applying is subject to your workspace limit — if you’re already at the maximum (25 on Extended), apply is blocked. A platform mismatch is only a warning and does not block apply.

Note

“Applying” is the final step of importing, not a separate command. There is no way to apply a template onto an existing workspace — apply always produces a new one.

Security & safety

Caution

Startup commands stored in a template run automatically when you apply it. Only import templates from sources you trust, and review the startup commands listed in the import preview before clicking Apply.

Working in your favor: because exported templates strip your real working directories, sharing a template doesn’t expose the folder paths on your machine.

Templates vs continuous sync

	Templates	Continuous sync
What it does	Export/import a workspace as a file	Keeps your profile in sync across devices
Trigger	Manual, one-shot	Automatic, ongoing
Storage	A .gridmux-template.json file you manage	Managed by the sync provider

If you want your setup to follow you across machines automatically rather than moving a file by hand, see Cloud Sync.

Example workflow

Say you’ve arranged a workspace just right for a project — a PowerShell pane on the left and two Git Bash panes on the right.

1. Choose File → Export Workspace as Template… and save it as project.gridmux-template.json.
2. On another machine (or to hand it to a teammate), choose File → Import Template… and pick that file.
3. In the preview, set each terminal’s working directory to the local repo path, check the shells, and click Apply.
4. A new workspace appears with the same layout, ready to use — and your current workspaces stay exactly as they were.