Using Zinc

Getting started

What you need

Windows 10 version 2004 or later, or Windows 11, on an x64 PC. ARM64 builds aren’t available yet.

Install

Rather not install? Zinc-win-Portable.zip holds the same build in a folder you can run from anywhere.

Updates

Installed copies check for a new build once a day and update themselves. You’ll find the version you have, and the option to check now, in Settings›About›Updates. What changed is in the changelog.

First launch

The first time Zinc starts, a welcome page asks how you like to work and saves your answers to your settings. Reopen it any time with Welcome… in the command palette (Ctrl+Shift+P). It changes only what you change there.

• Layout. Simple, with tabs along the top and one terminal each, or workspaces, in a sidebar or along the top, each with its own tabs and splits.
• Panes. Compact, edge to edge, or cards, each with a header and a gap around it.
• Color scheme and font, with a preview. Pick one scheme, or a pair that follows Windows’ light and dark mode.
• Default shell. Zinc lists the shells it found on your PC.
• Notifications. Whether a long command that finishes in the background shows a Windows notification.

Keys worth knowing

Every action and its keys are in Settings›Keyboard, where you can change them.

Configuration

Change settings in the Settings window or in config.toml. They’re the same settings: a change in one shows in the other and applies straight away, in every open window.

The Settings window

Open it with Ctrl+,, from the command palette or from the tray icon. Each change is saved as you make it, and each setting shows its key in the file.

• Find a setting (Ctrl+F) searches settings, keys and profiles, so “font size ubuntu” finds the font size in your Ubuntu profile.
• The reset arrow beside a changed setting puts it back to its default.
• Undo changes, at the bottom, puts the file back as it was when you opened the window.

The config file

Your settings live in %APPDATA%\Zinc\config.toml. It’s TOML: settings grouped into sections, with # comments. Changes apply when you save.

default-profile = "wsl:Fedora"

[font]
family = "JetBrainsMono NF"
size = 11                    # points

[colors]
theme = "Dracula"            # a bundled scheme, or one of yours
background = "#181818"       # single colors override the scheme

[window]
workspace-tabs = "left"

[profile."wsl:Fedora"]
name = "Fedora"
command = 'wsl.exe -d Fedora --cd ~'
colors.theme = "0x96f"

Profiles

A profile is a shell with its own name, folder, font and colors. Zinc finds the shells on your PC each time it reads your settings, and lists them after your own.

A [profile] section with a found profile’s id changes it. [discover] turns a source off.

[discover]
ssh = false                  # also wsl, powershell, cmd, git-bash, msys2, visual-studio

[profile."wsl:Ubuntu"]
colors.theme = "Ubuntu"

[profile."msys2:ucrt64"]
hidden = true

Color schemes

Lit Cell and Lit Cell Light come with Zinc, along with about 650 schemes from iTerm2-Color-Schemes. Browse them in Settings›Appearance›Color scheme, where each one shows in its own colors. Your own go in %APPDATA%\Zinc\themes\, one file per scheme in Ghostty’s theme format.

To follow Windows’ light and dark mode, give a pair:

[colors]
theme = "light:Lit Cell Light,dark:Lit Cell"

Shell integration

Shells can mark where each prompt, command and output starts, and how each command ended. Zinc uses the marks to:

• Jump between prompts with Ctrl+Shift+↑ and Ctrl+Shift+↓.
• Copy or select a command’s output, from the command palette or the right-click menu.
• Show a red bar beside a failed command, and a mark on the scrollbar at each prompt.
• Mark a tab when a long command finishes out of view: green when it succeeded, red when it failed.
• Ask before closing a tab while a command is still running in it.
• Reopen tabs in the folder they were in.

Which shells

Most shells need nothing from you. Your startup files run as usual, and Zinc’s script runs after them without changing anything you see.

Turning it off

To start shells exactly as they’d start anywhere else, turn it off for every profile, or for one:

[terminal]
shell-integration = "off"

If your startup files hand over to something else, such as tmux or exec into another shell, the marks don’t follow. The scripts in the ShellIntegration folder next to zinc.exe show what to send from there.

Not reached yet

• bash in WSL, when your startup files replace PROMPT_COMMAND instead of adding to it. Git Bash is fine.
• elvish inside WSL, YSH and xonsh.
• Exit codes in cmd without Clink.

The zn CLI

zn opens, arranges and closes windows, workspaces, panes and terminals in the running Zinc. It can also type into a terminal and read what it shows, so scripts can set up your work for you.

Turn it on

Remote control is off until you turn it on, in Settings›Terminal›Command line or in your config:

[cli]
remote-control = true

Inside Zinc, zn is already on your PATH. To use it from other terminals too, turn on Use zn in other terminals.

Examples

zn list                                     # everything open, with ids
zn pane split right -- htop                 # a pane beside this one, running htop
zn terminal new --pane 4 --profile wsl:Fedora
zn workspace new --name api --cwd .         # a workspace in this folder
zn terminal send --terminal 5 ":w\r"        # types into terminal 5 (\r is Enter)
zn terminal read --terminal 7 --lines 20    # the last 20 lines of terminal 7
zn workspace color teal                     # this workspace's color
zn action "zoom-in"                         # any action, by its name

Commands

Commands are zn <thing> <verb>.

Run inside Zinc, a command acts on the terminal it runs in, and on that terminal’s pane, workspace and window. --terminal, --pane, --workspace and --window aim elsewhere, using ids from zn list. Add --json for output scripts can read, and run zn <thing> --help for the rest.

Exit codes