Tutorial

Configuration & keybindings

Sinclair reads a single settings.json — JSON with // comments — and watches it while it runs. In this walkthrough you'll find the config, save a change and watch it apply live, see what happens when you fat-finger a line, and then rebind a key to any action in the catalog. Nothing here needs a restart — every save takes effect the instant you write it.

1. Find the config file

Sinclair loads its settings from $XDG_CONFIG_HOME/sinclair/settings.json, falling back to ~/.config/sinclair/settings.json when XDG_CONFIG_HOME is unset (on Windows: %APPDATA%\sinclair\settings.json). The file is created on demand, so you can start from an empty {} — or no file at all — and add only the keys you care about. If you have a legacy key = value config file from an older Sinclair, it is migrated into settings.json once on launch and no longer read.

The format is JSON with comments: one object, one member per setting, and // comment lines are ignored. Most keys take a single scalar value; a handful (like font-family and keybind) take an array and accumulate entries. Every key is optional — remove one and it falls back to its built-in default. Save one member and see for yourself:

// ~/.config/sinclair/settings.json
{
  "theme": "Catppuccin Mocha",
  "font-family": ["JetBrains Mono"],
  "font-size": 14,
  "cursor-style": "bar",
  "copy-on-select": true
}

Sinclair watches the file. Appearance settings — fonts, theme, colors, padding, cursor — and keybindings take effect the moment you save, with no need to quit and relaunch.

2. Break a line on purpose

A bad line never aborts the load. An unknown key, a malformed value, or a plain typo becomes a friendly diagnostic surfaced on startup, and the rest of the file is applied normally. Add a nonsense key and a broken one alongside your good keys:

// ~/.config/sinclair/settings.json
{
  "theme": "Catppuccin Mocha",
  "fnot-size": 14,        // unknown key → diagnostic, not a crash
  "font-size": "huge",    // malformed value → diagnostic, not a crash
  "cursor-style": "bar"
}

Your theme and cursor-style still apply; the two bad lines are reported and skipped. This is deliberate: one mistake never leaves you staring at an unstyled terminal.

3. Round-trip through the settings UI

Prefer not to edit text by hand? Open the built-in GUI settings with ⌘, (the toggle_settings action) and the same options are exposed there. Change a font or theme in the panel and it lands in the same config file the editor writes — so the file and the UI stay in sync, and you can move between them however you like.

4. Rebind a key

Every command in Sinclair is an action, and any action can be bound to any key combination from your config. Keybindings live in the same file, on keybind lines. That key is repeatable — list as many as you like. Each binding is a single line:

"keybind": ["trigger=action"]   // optionally with a :param

A trigger is one or more modifiers and a key, joined with +. The modifier tokens are:

Keys are the alphanumerics (a–z, 0–9); named keys like enter, tab, escape, space, up, down, left, right, and f1–f12; and punctuation names like comma, period, slash, bracket_left, and bracket_right. A parameter, if the action takes one, follows the action after a colon (for example new_split:right). Your bindings are merged on top of the defaults, so you only declare what you want to change:

{
  "keybind": [
    // Override: make Cmd+T open a split to the right instead of a new tab
    "cmd+t=new_split:right",

    // Add: a fresh shortcut for clearing the screen and scrollback
    "cmd+shift+k=clear_screen",

    // Add: jump straight to the first tab
    "cmd+shift+1=goto_tab:1"
  ]
}

You can also chain keys into a chord with > — the binding fires only when the keys are pressed in sequence. For example, keybind = ctrl+a>n=next_tab means "press ⌃A, then N."

5. Remove a default you never use

To reclaim a default shortcut, bind its trigger to the unbind action. Sinclair then stops handling that combination and lets it fall through — handy when you want a key back for the shell:

{
  "keybind": [
    "cmd+k=unbind"   // reclaim Cmd+K for the shell
  ]
}

6. Discover an action's token

You never have to memorize the config strings. Two places surface every action:

• The command palette (command_palette, ⌘⇧P) lists every action by name and shows its current binding — a fast way to learn what a shortcut is called before you rebind it.
• The keybindings page carries the full action catalog: each action's config string, its parameters, and any alias you can use in its place.

Open the palette, find the action you want, note its token, and drop it onto a keybind line. That loop — palette to config and back — is all you need to bend the whole keymap to your hands.

Where to next