# Hyper User Guide

**Hyper** is a beautiful, fully extensible terminal application built on open web
technologies (Electron, React, and `xterm.js`). It runs on macOS, Windows, and
Linux, renders your shell inside a hardware-accelerated terminal, and lets you
reshape almost everything — colors, fonts, key bindings, even whole UI
components — through a single configuration file and an ecosystem of npm-published
plugins and themes.

This guide covers everything you need to install Hyper, drive it day to day,
customize its appearance, manage plugins, and recover when something goes wrong.
Every command, option, default value, and keyboard shortcut described here is
taken directly from Hyper's source code.

> [!NOTE]
> This guide documents Hyper **4.0.0-canary.5**. The configuration file in Hyper 4
> is **`hyper.json`** (JSON format). If you are upgrading from Hyper 3, which used a
> JavaScript `~/.hyper.js` file, Hyper migrates your settings automatically the
> first time it launches — see [Upgrading from Hyper 3](#upgrading-from-hyper-3).

---

## 1. Quick Start

1. **Install Hyper** for your platform (see [Installation](#2-installation)).
2. **Launch it.** Hyper opens a window running your system's default login shell.
3. **Open a new tab** with `Cmd+T` (macOS) or `Ctrl+Shift+T` (Windows/Linux).
4. **Split the current tab into panes** with `Cmd+D` (split right) or
   `Cmd+Shift+D` (split down) on macOS; `Ctrl+Shift+D` / `Ctrl+Shift+E` elsewhere.
5. **Open your config** with `Cmd+,` (macOS) or `Ctrl+,` (Windows/Linux) to start
   customizing. Saving the file applies changes instantly — no restart needed.
6. **Install a plugin** from a terminal: `hyper install hyperpower`, then save your
   config or restart to load it.

> [!TIP]
> Hyper reloads its configuration the moment you save `hyper.json`. You can tweak
> colors, fonts, and key bindings and watch them apply live, without ever
> restarting the app.

---

## 2. Installation

Download the latest release from **[hyper.is](https://hyper.is/#installation)**,
or use your platform's package manager. Hyper ships installers and packages for
every major desktop platform.

> [!IMPORTANT]
> Versions published to Homebrew, Chocolatey, Snapcraft, or the AUR can lag
> behind the official release. If you need the newest version, download it
> directly from [hyper.is](https://hyper.is/#installation).

=== "macOS"

    Install with [Homebrew Cask](https://brew.sh):

    ```bash
    brew update
    brew install --cask hyper
    ```

    Or download the `.dmg` from [hyper.is](https://hyper.is/#installation).
    Universal builds are provided for both Intel (`x64`) and Apple Silicon
    (`arm64`).

=== "Windows"

    Install with [Chocolatey](https://chocolatey.org/):

    ```bash
    choco install hyper
    ```

    Or download the NSIS installer (`.exe`) from
    [hyper.is](https://hyper.is/#installation). Builds are provided for `x64`
    and `arm64`. The installer lets you choose the installation directory.

=== "Linux (Arch)"

    Hyper is in the [AUR](https://aur.archlinux.org/packages/hyper/). Use an AUR
    helper such as [paru](https://github.com/Morganamilo/paru):

    ```sh
    paru -S hyper
    ```

=== "Linux (NixOS)"

    Hyper is packaged in nixpkgs:

    ```sh
    nix-env -i hyper
    ```

=== "Linux (other)"

    Download a package matching your distribution from
    [hyper.is](https://hyper.is/#installation). Official builds are produced in
    `deb`, `rpm`, `AppImage`, `snap`, and `pacman` formats.

### What gets installed

When Hyper launches for the first time it sets up a few things automatically:

- It creates your configuration directory and writes a default `hyper.json`.
- It creates the plugin directories (`plugins/` and `plugins/local/`) inside the
  config directory.
- It attempts to install the **`hyper` command-line tool** into your `PATH` so
  you can manage plugins and launch Hyper from any terminal (see
  [The `hyper` CLI](#9-the-hyper-command-line-tool)).
- On non-macOS platforms it can register itself as the default handler for
  `ssh://` URLs (controlled by the `defaultSSHApp` setting).

> [!NOTE]
> On macOS and Linux the CLI is installed as a symlink at `/usr/local/bin/hyper`.
> On Windows, Hyper adds its `bin` directory to your user `PATH` via the registry,
> and you may need to restart your computer for the change to take effect. On
> Linux AppImage installs, the CLI symlink is intentionally skipped because the
> AppImage is mounted at a temporary path.

---

## 3. Your First Look at the Window

A Hyper window contains one or more **tabs**, and each tab can be divided into
multiple **panes** (split terminals). The terminal area is rendered by
`xterm.js`, giving you a fast, standards-compliant VT emulator with truecolor
support.

| UI element | What it is |
|---|---|
| **Tab bar** | One tab per top-level terminal group; shows the tab title from the running program |
| **Pane** | An individual shell session inside a tab; tabs can hold many panes via splitting |
| **Hamburger menu** | On Windows/Linux (frameless windows), the menu is reachable with `Alt+F` |
| **Window controls** | Minimize / maximize / close buttons (hidden or repositionable via config) |
| **Search box** | An in-terminal find bar opened with the search shortcut |

On macOS, Hyper uses a native frame with an inset title bar. On Windows and
Linux the window is **frameless** by default, and the application menu is
available through the hamburger menu (`Alt+F`).

---

## 4. Everyday Usage

This section walks through the tasks you'll perform most often. Every action
below maps to a default keyboard shortcut (see the full
[Keyboard Shortcuts](#7-keyboard-shortcuts) reference) and, where relevant, a menu
item.

### Tabs

A tab is a top-level terminal group. Each new tab launches a fresh shell session.

- **New tab** — `Cmd+T` (macOS) / `Ctrl+Shift+T` (Win/Linux), or **Shell → New Tab**.
- **Next / previous tab** — `Cmd+Shift+]` / `Cmd+Shift+[` (macOS) and several
  other bindings; on Windows/Linux `Ctrl+Tab` / `Ctrl+Shift+Tab`.
- **Jump to tab N** — hold the tab-jump modifier and press a digit: `Cmd+1`…`Cmd+8`
  on macOS (`Ctrl+1`…`Ctrl+8` on Win/Linux). The **9** slot jumps to the **last**
  tab.

> [!TIP]
> The tab-jump shortcut is generated from a single `tab:jump:prefix` binding. By
> default the prefix is `Cmd` on macOS and `Ctrl` on Windows/Linux, so `prefix+1`
> through `prefix+8` select tabs 1–8 and `prefix+9` selects the last tab.

### Panes (splitting a tab)

Splitting divides the active tab into multiple side-by-side or stacked terminals,
each running its own shell.

- **Split right (vertical divider)** — `Cmd+D` (macOS) / `Ctrl+Shift+D` (Win/Linux).
- **Split down (horizontal divider)** — `Cmd+Shift+D` (macOS) / `Ctrl+Shift+E`
  (Win/Linux).
- **Move focus to next / previous pane** — `Cmd+]` / `Cmd+[` (macOS);
  `Ctrl+PageUp` / `Ctrl+PageDown` (Win/Linux).
- **Close the active pane** — `Cmd+W` (macOS) / `Ctrl+Shift+W` (Win/Linux). Closing
  the last pane in a tab closes the tab; closing the last tab closes the window.

> [!TIP]
> By default, when you create a new split or tab, Hyper opens it in the **same
> working directory** as the currently active pane. This is controlled by the
> `preserveCWD` setting (on by default). Set it to `false` if you'd rather start
> new sessions in your home directory.

### Windows

- **New window** — `Cmd+N` (macOS) / `Ctrl+Shift+N` (Win/Linux).
- **Close window** — `Cmd+Shift+W` (macOS) / `Ctrl+Shift+Q` (also `Alt+F4` on
  Windows).
- **Minimize** — `Cmd+M` (macOS) / `Ctrl+Shift+M` (Win/Linux).
- **Toggle full screen** — `Cmd+Ctrl+F` (macOS) / `F11` (Win/Linux).
- **Toggle "Always on Top"** — available from the **Window** menu.

New windows open offset from the last focused window and are kept on the correct
monitor in multi-display setups. Hyper remembers the last window's size and
position between launches.

### Copy and paste

- **Copy** — `Cmd+C` (macOS) / `Ctrl+Shift+C` (Win/Linux).
- **Paste** — `Cmd+V` (macOS) / `Ctrl+Shift+V` (Win/Linux).
- **Select all** — `Cmd+A` (macOS) / `Ctrl+Shift+A` (Win/Linux).

> [!TIP]
> Enable `copyOnSelect` in your config to automatically copy any text you select
> to the clipboard. On Windows, `quickEdit` (on by default there) lets you
> right-click to copy the selection — or paste when nothing is selected.

### Searching terminal output

- **Open search** — `Cmd+F` (macOS) / `Ctrl+Shift+F` (Win/Linux).
- **Close search** — `Esc`.

The search box finds text within the current pane's scrollback buffer.

### Zooming (font size)

Adjust the on-screen font size for the current window without editing your config:

- **Zoom in** — `Cmd+Plus` / `Cmd+=` (macOS); `Ctrl+=` (Win/Linux).
- **Zoom out** — `Cmd+-` (macOS) / `Ctrl+-` (Win/Linux).
- **Reset zoom** — `Cmd+0` (macOS) / `Ctrl+0` (Win/Linux).

> [!NOTE]
> Hyper won't shrink the font below ~5px, because `xterm.js` begins to render
> incorrectly at very small sizes.

### Line-editing shortcuts

Hyper provides Emacs-style line-editing shortcuts that send the corresponding
control sequences to your shell. These are available from the **Edit → Move to…**
and **Edit → Delete…** menus and via keyboard:

| Action | macOS | Windows / Linux |
|---|---|---|
| Move to previous word | `Alt+Left` | `Ctrl+Left` |
| Move to next word | `Alt+Right` | `Ctrl+Right` |
| Move to beginning of line | `Cmd+Left` | `Home` |
| Move to end of line | `Cmd+Right` | `End` |
| Delete previous word | `Alt+Backspace` | `Ctrl+Backspace` |
| Delete next word | `Alt+Delete` | `Ctrl+Del` |
| Delete to beginning of line | `Cmd+Backspace` | `Ctrl+Home` |
| Delete to end of line | `Cmd+Delete` | `Ctrl+End` |
| Clear buffer | `Cmd+K` | `Ctrl+Shift+K` |
| Send interrupt (`Ctrl+C`) | `Ctrl+C` | `Ctrl+C` |

### Opening files and folders in Hyper

- **Drag and drop** a file or folder onto a terminal pane to insert its path (a
  folder becomes a `cd` command).
- On macOS, Hyper registers as a handler for folders and Unix executables, so you
  can open them with Hyper from Finder.
- On Windows you can add **"Open Hyper here"** to the Explorer right-click menu via
  **Tools → Add Hyper to system context menu**.

### Opening `ssh://` links

Hyper can act as the default application for `ssh://` URLs. When you open such a
link, Hyper launches a session and runs the corresponding `ssh` command
(including user, host, and port). This is controlled by the `defaultSSHApp`
setting (on by default).

---

## 5. The `hyper.json` Configuration File

All of Hyper's behavior is driven by a single JSON file named **`hyper.json`**.

### Opening your config

- Press `Cmd+,` (macOS) or `Ctrl+,` (Windows/Linux), **or**
- Use the menu: **Hyper → Preferences…** (macOS) or **Edit → Preferences…**
  (Windows/Linux).

This opens `hyper.json` in your default editor. (On Windows, if no editor is
associated with `.js`/JSON files, Hyper falls back to Notepad.)

### Where it lives

| Platform | Location |
|---|---|
| macOS / Linux | `~/.config/Hyper/hyper.json` |
| Windows | `%APPDATA%`-style user-data directory, `…\Hyper\hyper.json` |
| Any platform with `XDG_CONFIG_HOME` set | `$XDG_CONFIG_HOME/Hyper/hyper.json` |

### File structure

`hyper.json` has four top-level keys:

```json
{
  "config": {
    "fontSize": 12,
    "fontFamily": "Menlo, \"DejaVu Sans Mono\", Consolas, monospace",
    "cursorColor": "rgba(248,28,229,0.8)"
  },
  "plugins": [],
  "localPlugins": [],
  "keymaps": {}
}
```

| Key | Purpose |
|---|---|
| `config` | All terminal and appearance settings (covered below) |
| `plugins` | npm packages to install and load (see [Plugins](#8-plugins-and-themes)) |
| `localPlugins` | Local plugin directories to load without installing from npm |
| `keymaps` | Custom key bindings, overriding the platform defaults |

> [!IMPORTANT]
> Edits apply automatically when you save the file. If Hyper can't parse your
> `hyper.json`, it shows a notification ("Couldn't parse config file. Using
> default config instead.") and keeps running on the previous/default config — so
> a typo won't lock you out.

The most-used appearance and behavior settings are described in the next two
sections. For an exhaustive reference of every available `config` key — including
types, defaults, and allowed values — see the **Admin Guide**.

---

## 6. Customizing Appearance

These settings live under the `config` key in `hyper.json`.

### Fonts

```json
{
  "config": {
    "fontSize": 12,
    "fontFamily": "Menlo, \"DejaVu Sans Mono\", Consolas, monospace",
    "fontWeight": "normal",
    "fontWeightBold": "bold",
    "lineHeight": 1,
    "letterSpacing": 0
  }
}
```

| Setting | Meaning | Default |
|---|---|---|
| `fontSize` | Font size in pixels | `12` |
| `fontFamily` | Font stack with fallbacks | `Menlo, "DejaVu Sans Mono", Consolas, "Lucida Console", monospace` |
| `fontWeight` | Normal-text weight (`'normal'`, `'bold'`, or `'100'`–`'900'`) | `normal` |
| `fontWeightBold` | Weight for bold characters | `bold` |
| `lineHeight` | Line height as a relative unit | `1` |
| `letterSpacing` | Letter spacing as a relative unit | `0` |
| `disableLigatures` | Set to `false` to enable font ligatures | `true` |

### Colors and theme

```json
{
  "config": {
    "foregroundColor": "#fff",
    "backgroundColor": "#000",
    "cursorColor": "rgba(248,28,229,0.8)",
    "cursorAccentColor": "#000",
    "selectionColor": "rgba(248,28,229,0.3)",
    "borderColor": "#333",
    "colors": {
      "black": "#000000",
      "red": "#C51E14",
      "green": "#1DC121",
      "yellow": "#C7C329",
      "blue": "#0A2FC4",
      "magenta": "#C839C5",
      "cyan": "#20C5C6",
      "white": "#C7C7C7",
      "lightBlack": "#686868",
      "lightRed": "#FD6F6B",
      "lightGreen": "#67F86F",
      "lightYellow": "#FFFA72",
      "lightBlue": "#6A76FB",
      "lightMagenta": "#FD7CFC",
      "lightCyan": "#68FDFE",
      "lightWhite": "#FFFFFF"
    }
  }
}
```

The `colors` object maps the 16 standard ANSI colors. Color values accept any CSS
color format: hex, `rgb()`, `rgba()`, `hsl()`, `hsv()`, `hwb()`, or `cmyk()`.

> [!NOTE]
> Background-color **opacity** (the alpha channel of an `rgba()` background) is only
> honored on macOS. Transparent backgrounds also require the canvas renderer
> rather than WebGL — see `webGLRenderer` in the Admin Guide.

### Cursor

| Setting | Meaning | Default |
|---|---|---|
| `cursorShape` | `'BEAM'` (`|`), `'UNDERLINE'` (`_`), or `'BLOCK'` (`█`) | `BLOCK` |
| `cursorColor` | Cursor color and opacity | `rgba(248,28,229,0.8)` |
| `cursorAccentColor` | Text color under a `BLOCK` cursor | `#000` |
| `cursorBlink` | Set to `true` for a blinking cursor | `false` |

### Window and padding

```json
{
  "config": {
    "padding": "12px 14px",
    "showHamburgerMenu": "",
    "showWindowControls": ""
  }
}
```

- `padding` accepts standard CSS padding syntax (`top right bottom left`,
  `vertical horizontal`, or a single value).
- `showHamburgerMenu` — set to `false` on Linux setups that show native menus.
  (Default behaves as `true` on Windows/Linux; ignored on macOS.)
- `showWindowControls` — set to `false` to hide minimize/maximize/close, or
  `'left'` to move them to the left (Ubuntu-style). Ignored on macOS.

### Custom CSS

For deeper visual tweaks you can inject CSS:

- `css` — custom CSS for the main window.
- `termCSS` — custom CSS for the terminal area.

> [!WARNING]
> Hyper 2 switched from `hterm` to `xterm.js`, which renders terminal output to a
> canvas rather than the DOM. As a result, older CSS selectors like `x-screen`,
> `x-row`, `cursor-node`, and `::selection` no longer work and are **deprecated**.
> If your config uses them, Hyper warns: *"Your configuration uses some deprecated
> CSS classes."* Use the documented configuration options or `xterm.js`-compatible
> styling instead.

### Installing themes

Themes are just plugins that decorate Hyper's config. Install one the same way you
install any plugin:

```bash
hyper install hyperyellow
```

Browse available themes with `hyper search <term>` (theme packages are tagged
`hyper-theme` on npm).

---

## 7. Keyboard Shortcuts

Hyper ships a complete set of platform-specific default key bindings. You can
override any of them in the `keymaps` section of `hyper.json` (see
[Customizing key bindings](#customizing-key-bindings)). The tables below list
every default binding.

### macOS defaults

| Command | Shortcut |
|---|---|
| `window:new` | `Cmd+N` |
| `window:minimize` | `Cmd+M` |
| `window:zoom` | `Ctrl+Alt+Cmd+M` |
| `window:toggleFullScreen` | `Cmd+Ctrl+F` |
| `window:close` | `Cmd+Shift+W` |
| `window:reload` | `Cmd+Shift+R` |
| `window:reloadFull` | `Cmd+Shift+F5` |
| `window:preferences` | `Cmd+,` |
| `window:devtools` | `Cmd+Alt+I` |
| `tab:new` | `Cmd+T` |
| `tab:next` | `Cmd+Shift+]`, `Cmd+Shift+Right`, `Cmd+Alt+Right`, `Ctrl+Tab` |
| `tab:prev` | `Cmd+Shift+[`, `Cmd+Shift+Left`, `Cmd+Alt+Left`, `Ctrl+Shift+Tab` |
| `tab:jump` (prefix) | `Cmd+1`…`Cmd+9` (9 = last) |
| `pane:next` | `Cmd+]` |
| `pane:prev` | `Cmd+[` |
| `pane:splitRight` | `Cmd+D` |
| `pane:splitDown` | `Cmd+Shift+D` |
| `pane:close` | `Cmd+W` |
| `zoom:in` | `Cmd+Plus`, `Cmd+=` |
| `zoom:out` | `Cmd+-` |
| `zoom:reset` | `Cmd+0` |
| `editor:copy` | `Cmd+C` |
| `editor:paste` | `Cmd+V` |
| `editor:cut` | `Cmd+X` |
| `editor:selectAll` | `Cmd+A` |
| `editor:undo` | `Cmd+Z` |
| `editor:redo` | `Cmd+Y` |
| `editor:search` | `Cmd+F` |
| `editor:search-close` | `Esc` |
| `editor:clearBuffer` | `Cmd+K` |
| `editor:break` | `Ctrl+C` |
| `plugins:update` | `Cmd+Shift+U` |

### Windows / Linux defaults

| Command | Shortcut |
|---|---|
| `window:new` | `Ctrl+Shift+N` |
| `window:minimize` | `Ctrl+Shift+M` |
| `window:zoom` | `Ctrl+Shift+Alt+M` |
| `window:toggleFullScreen` | `F11` |
| `window:close` | `Ctrl+Shift+Q` (also `Alt+F4` on Windows) |
| `window:reload` | `Ctrl+Shift+R` |
| `window:reloadFull` | `Ctrl+Shift+F5` |
| `window:preferences` | `Ctrl+,` |
| `window:devtools` | `Ctrl+Shift+I` |
| `window:hamburgerMenu` | `Alt+F` |
| `tab:new` | `Ctrl+Shift+T` |
| `tab:next` | `Ctrl+Tab` (Linux also `Ctrl+Shift+]`, `Ctrl+Shift+Right`, `Ctrl+Alt+Right`) |
| `tab:prev` | `Ctrl+Shift+Tab` (Linux also `Ctrl+Shift+[`, `Ctrl+Shift+Left`, `Ctrl+Alt+Left`) |
| `tab:jump` (prefix) | `Ctrl+1`…`Ctrl+9` (9 = last) |
| `pane:next` | `Ctrl+PageUp` |
| `pane:prev` | `Ctrl+PageDown` |
| `pane:splitRight` | `Ctrl+Shift+D` |
| `pane:splitDown` | `Ctrl+Shift+E` |
| `pane:close` | `Ctrl+Shift+W` |
| `zoom:in` | `Ctrl+=` |
| `zoom:out` | `Ctrl+-` |
| `zoom:reset` | `Ctrl+0` |
| `editor:copy` | `Ctrl+Shift+C` |
| `editor:paste` | `Ctrl+Shift+V` |
| `editor:cut` | `Ctrl+Shift+X` |
| `editor:selectAll` | `Ctrl+Shift+A` |
| `editor:search` | `Ctrl+Shift+F` |
| `editor:search-close` | `Esc` |
| `editor:clearBuffer` | `Ctrl+Shift+K` |
| `editor:break` | `Ctrl+C` |
| `plugins:update` | `Ctrl+Shift+U` |

### Customizing key bindings

Add a `keymaps` object to `hyper.json`. Each entry maps a command name to one
shortcut (a string) or several (an array):

```json
{
  "keymaps": {
    "window:devtools": "cmd+alt+o",
    "pane:splitRight": ["ctrl+shift+d", "ctrl+shift+e"]
  }
}
```

Key combinations use [Mousetrap](https://craig.is/killing/mice#keys) key names.

> [!NOTE]
> Use `command` (not the older `cmd`) in shortcuts on macOS. If you write `cmd`,
> Hyper warns that it's deprecated and substitutes `command` for you.

---

## 8. Plugins and Themes

Hyper's extensibility is its defining feature. **Plugins** are npm packages that
can recolor the terminal, add UI, change behavior, register new commands, and
more. **Themes** are simply plugins focused on appearance.

### Installing a plugin

The easiest way is the [`hyper` CLI](#9-the-hyper-command-line-tool):

```bash
hyper install hyperpower
```

```text
hyperpower installed successfully!
```

This adds the plugin to the `plugins` array in your `hyper.json`. Hyper detects
the change and installs/loads it automatically. You can also edit `hyper.json`
directly:

```json
{
  "plugins": ["hyperpower", "hyper-pane", "@company/internal-plugin#1.2.0"]
}
```

Plugin entries follow the npm format `[@org/]project[#version]`:

- `hyperpower` — latest version
- `hyper-pane` — latest version
- `project#1.0.1` — a specific version
- `@company/project` — a scoped package

### Updating plugins

- Hyper auto-updates installed plugins periodically (every 5 hours by default,
  controlled by `autoUpdatePlugins`).
- Force an update now with **Tools → Update plugins** or `Cmd+Shift+U` /
  `Ctrl+Shift+U`.

> [!NOTE]
> After plugins update, Hyper notifies you: *"Restart the app or hot-reload with
> 'View' > 'Reload' to enjoy the updates!"* Use **View → Reload** to apply changes
> without a full restart.

### Removing a plugin

```bash
hyper uninstall hyperpower
```

```text
hyperpower uninstalled successfully!
```

### Finding plugins and themes

```bash
hyper search pane          # search npm for matching plugins/themes
hyper list-remote          # list all hyper plugins and themes on npm
hyper docs hyperpower      # open a plugin's npm/ghub.io page in your browser
```

Plugin and theme packages are tagged `hyper-plugin` and `hyper-theme` on npm.

### Local plugins (for development)

If you're writing your own plugin, place it in the `plugins/local/` directory
inside your config directory and list its folder name under `localPlugins`:

```json
{
  "localPlugins": ["my-plugin"]
}
```

Local plugins are loaded directly and are **not** fetched from npm. For full
plugin-authoring documentation — the available extension hooks, decorators, and
component HOC patterns — see the **Admin Guide** and the project's `PLUGINS.md`.

---

## 9. The `hyper` Command-Line Tool

Hyper installs a `hyper` command into your `PATH` for managing plugins and
launching the app from any terminal.

### Commands

| Command | Aliases | Description |
|---|---|---|
| `hyper install <plugin>` | `i` | Install a plugin from npm |
| `hyper uninstall <plugin>` | `u`, `rm`, `remove` | Uninstall a plugin |
| `hyper list` | `ls` | List installed plugins |
| `hyper search <query>` | `s` | Search npm for plugins/themes |
| `hyper list-remote` | `lsr`, `ls-remote` | List all available plugins/themes on npm |
| `hyper docs <plugin>` | `d`, `h`, `home` | Open a plugin's npm page in the browser |
| `hyper version` | — | Print the Hyper version |
| `hyper [path]` | — | Launch Hyper (optionally opening a file or directory) |

### Options

| Option | Description |
|---|---|
| `-v`, `--verbose` | Verbose mode (streams the launched app's stdout/stderr) |

### Examples

```bash
hyper install hyper-pane
```

```text
hyper-pane installed successfully!
```

```bash
hyper list
```

```text
hyperpower
hyper-pane
```

```bash
hyper ~/projects/my-app
```

Launches Hyper (or focuses an existing instance on macOS) opening the given
directory.

> [!IMPORTANT]
> Plugin subcommands require that Hyper has run at least once, because they read
> and write your `hyper.json`. If the config file doesn't exist yet you'll see:
> *"Error! Config file not found … Please launch Hyper and retry."*

---

## 10. Shell Configuration

By default Hyper launches your system's login shell with the argument `--login`.
You can choose a different shell and arguments in `hyper.json`:

```json
{
  "config": {
    "shell": "/usr/local/bin/fish",
    "shellArgs": ["--login"]
  }
}
```

- `shell` — full path to the shell binary. Leave empty (`""`) to use the system
  login shell.
- `shellArgs` — array of arguments passed to the shell. Defaults to `["--login"]`.
  For an interactive shell you might use `["-i"]`.

=== "WSL (Windows Subsystem for Linux)"

    ```json
    { "config": { "shell": "C:\\Windows\\System32\\wsl.exe", "shellArgs": [] } }
    ```

=== "PowerShell (Windows)"

    ```json
    { "config": { "shell": "C:\\WINDOWS\\System32\\WindowsPowerShell\\v1.0\\powershell.exe", "shellArgs": [] } }
    ```

=== "Git Bash (Windows)"

    ```json
    { "config": { "shell": "C:\\Program Files\\Git\\bin\\bash.exe", "shellArgs": [] } }
    ```

> [!WARNING]
> On Windows, remove `--login` from `shellArgs` for most shells — it's a Unix
> convention. Use a full path if just the binary name doesn't work.

> [!TIP]
> If your configured shell exits immediately (within one second) with a non-zero
> exit code — usually a sign of a bad shell path or arguments — Hyper prints a
> diagnostic message in the terminal and falls back to a working shell
> configuration so you aren't left with a window that closes instantly.

When you change the shell while a session is running, Hyper notifies you that the
change applies to **new** tabs and windows: *"Open a new tab or window to start
using the new shell."*

### Environment variables

Add environment variables for spawned shells with the `env` setting:

```json
{
  "config": {
    "env": { "MY_VAR": "value", "EDITOR": "vim" }
  }
}
```

Hyper also sets several variables for every session automatically, including
`TERM=xterm-256color`, `COLORTERM=truecolor`, `TERM_PROGRAM`, and
`TERM_PROGRAM_VERSION`.

---

## 11. Profiles

Profiles let you define multiple named shell configurations and switch between
them when opening tabs, windows, or splits.

```json
{
  "config": {
    "defaultProfile": "default",
    "profiles": [
      { "name": "default", "config": {} },
      {
        "name": "work",
        "config": {
          "shell": "/bin/zsh",
          "backgroundColor": "#001100",
          "env": { "ENVIRONMENT": "work" }
        }
      }
    ]
  }
}
```

- `defaultProfile` — the profile used when launching a normal session.
- `profiles` — a list of `{ name, config }` objects. Any option set in a profile's
  `config` overrides the root config for sessions started with that profile.

Once you've defined profiles, the **Shell** (macOS) / **File** (Windows/Linux)
menu gains a submenu for each profile, letting you open a **New Tab**, **New
Window**, **Split Down**, or **Split Right** using that profile.

---

## 12. Advanced Features

### Inline images (Sixel / iTerm2)

Set `imageSupport` to `true` (the default) to enable Sixel and the iTerm2 inline
image protocol, so programs that emit images render them directly in the terminal.

### WebGL rendering

```json
{ "config": { "webGLRenderer": false } }
```

When `false` (the default), Hyper uses canvas-based rendering, which is slower but
supports transparent backgrounds. Set it to `true` for the faster WebGL renderer
(at the cost of background transparency).

### Web link activation

```json
{ "config": { "webLinksActivationKey": "" } }
```

By default, clicking a URL in the terminal opens it. Set `webLinksActivationKey`
to `ctrl`, `alt`, `meta`, or `shift` to require that modifier when clicking a
link.

### Accessibility (screen readers)

Set `screenReaderMode` to `true` to let screen readers such as NVDA read the
terminal contents.

### macOS option-key selection

`macOptionSelectionMode` controls column selection when the Option key is held:
`'vertical'` (default) for column mode, or `'force'` to force selection even when
the terminal is in mouse-events mode (e.g. inside tmux or Vim with mouse mode on).

### The bell

```json
{ "config": { "bell": "SOUND", "bellSoundURL": "/path/to/sound.wav" } }
```

- `bell` — `'SOUND'` to enable an audible bell, or `false` to turn it off.
- `bellSoundURL` — absolute path to a custom sound file.

---

## 13. Updating Hyper

Hyper checks for application updates automatically on launch and periodically
thereafter. You can choose between two release channels:

```json
{ "config": { "updateChannel": "stable" } }
```

- `stable` — highly polished releases (default).
- `canary` — less polished but more frequent updates.

To turn auto-updates off entirely:

```json
{ "config": { "disableAutoUpdates": true } }
```

> [!NOTE]
> On macOS and Windows, updates are downloaded and can be installed in place
> (Hyper restarts to apply). On Linux, Hyper notifies you when a new version is
> available but does not self-install — update through your package manager or by
> downloading the new release.

---

## 14. Upgrading from Hyper 3

Hyper 3 stored its configuration in a JavaScript file at `~/.hyper.js`. Hyper 4
uses a JSON file, `hyper.json`, in a platform-specific config directory.

The **first time** Hyper 4 launches, it migrates automatically:

- Your old `~/.hyper.js` is read and its settings are merged into a new
  `hyper.json`.
- Any custom logic in the old `config` object (which JS allowed) is converted into
  a local plugin named `migrated-hyper3-config`, preserved under
  `plugins/local/`.
- Your old local plugins are copied over.

You'll see a notification: *"Settings location and format has changed to
`…/hyper.json`."* If migration can't complete, Hyper creates a fresh default
config and tells you so.

> [!IMPORTANT]
> Plugins that depended on the old `hterm` API (Hyper 1) generally do **not** work
> in Hyper 2+, which uses `xterm.js`. In particular, styling terminal text or
> links via `termCSS` is no longer possible the way it was under `hterm` — use
> `xterm.js` configuration options instead.

---

## 15. How Hyper Works (in brief)

Understanding the basics helps when debugging plugins or unusual behavior:

- Hyper is an **Electron** app. The **main process** (the `app/` code) owns the
  windows, spawns shells via `node-pty`, loads your config and plugins, and runs
  auto-updates. The **renderer** (the `lib/` code) is a **React + Redux** UI that
  draws the terminal with `xterm.js`.
- Each terminal you see is a **pseudo-terminal (PTY)** session. Keystrokes travel
  from the renderer to the main process and into the shell; output streams back
  and is rendered by `xterm.js`.
- **Tabs** are top-level "term groups"; **splits/panes** are nested term groups
  within a tab.
- **Plugins** are loaded by the main process and the renderer and can "decorate"
  almost any part of Hyper — config, menus, key bindings, and React components.

For a full architectural treatment — the IPC/RPC bridge, the session data
pipeline, the plugin extension API, security model, and build/deployment — see the
**Admin Guide**.

---

## 16. Troubleshooting

### Error: `node-pty failed to load`

**Cause:** The native `node-pty` module (which provides the pseudo-terminal) was
built incorrectly or is incompatible with your install.

**Solution:** Reinstall Hyper from an official package. If you are running from
source for development, rebuild it with `pnpm run rebuild-node-pty`.

**Prevention:** Use the official installers from
[hyper.is](https://hyper.is/#installation) rather than ad-hoc builds.

### My configured shell opens and closes instantly

**Cause:** An invalid `shell` path or bad `shellArgs` — the shell exits with a
non-zero code right away.

**Solution:** Hyper detects this and prints the failing configuration plus the
fallback it used. Check the `shell` and `shellArgs` values in `hyper.json`. On
Windows, remove `--login` from `shellArgs`.

**Prevention:** Use a full absolute path to the shell binary and test it in an
existing terminal first.

### Error: `Couldn't parse config file. Using default config instead.`

**Cause:** `hyper.json` contains a JSON syntax error.

**Solution:** Reopen the file (`Cmd+,` / `Ctrl+,`) and fix the syntax — a missing
comma, trailing comma, or unbalanced brace. Hyper keeps running on the default
config until the file is valid.

**Prevention:** Edit `hyper.json` in an editor with JSON validation.

### Warning: *Your configuration uses some deprecated CSS classes*

**Cause:** Your `css` or `termCSS` uses pre-`xterm.js` selectors such as
`x-screen`, `x-row`, `cursor-node`, or `::selection`.

**Solution:** Replace them with supported configuration options or
`xterm.js`-compatible selectors.

### A plugin doesn't load / "does not expose any Hyper extension API methods"

**Cause:** The plugin package doesn't export any recognized Hyper extension hook,
or failed to load.

**Solution:** Verify the package name in `plugins`, run **Tools → Update
plugins**, and check the Developer Tools console (`Cmd+Alt+I` / `Ctrl+Shift+I`)
for the plugin's error. Confirm the plugin supports your Hyper version.

### The `hyper` CLI says the config file isn't found

**Cause:** Hyper hasn't been launched yet, so no `hyper.json` exists.

**Solution:** Launch the Hyper app once, then retry the CLI command.

### The `hyper` command isn't recognized after install (Windows)

**Cause:** The `PATH` change made by Hyper hasn't taken effect.

**Solution:** Restart your computer (Hyper's installer notes this), or add Hyper's
`bin` directory to your `PATH` manually. You can also re-run **Tools → Install
Hyper CLI command in PATH**.

### Reporting a bug

Use **Help → Report Issue**. Hyper opens a pre-filled GitHub issue containing your
version, OS, Electron version, shell, and a redactable copy of your `hyper.json`
and plugin list — everything maintainers need to reproduce the problem.

---

## 17. Frequently Asked Questions

**Q: Where is my configuration stored?**
In `hyper.json` inside your config directory: `~/.config/Hyper/` on macOS/Linux,
the user-data directory on Windows, or `$XDG_CONFIG_HOME/Hyper/` if that variable
is set.

**Q: Do I have to restart Hyper after changing settings?**
No. Hyper watches `hyper.json` and applies most changes the instant you save.
Shell changes apply to new tabs/windows.

**Q: How do I change the color scheme?**
Edit the `colors`, `foregroundColor`, and `backgroundColor` settings, or install a
theme plugin like `hyperyellow` with `hyper install`.

**Q: How do I install a plugin?**
Run `hyper install <name>`, or add it to the `plugins` array in `hyper.json`.

**Q: How do I make text transparent / use a transparent background?**
Use an `rgba()` `backgroundColor` with alpha < 1, keep `webGLRenderer` set to
`false` (canvas rendering), and note that background opacity is only honored on
macOS.

**Q: Can I use a different shell, like fish or zsh?**
Yes — set `shell` to the binary's full path in `hyper.json`. See
[Shell Configuration](#10-shell-configuration).

**Q: What's the difference between a tab and a pane?**
A tab is a separate terminal group shown in the tab bar. A pane is a split within
a tab — multiple shells visible side by side or stacked.

**Q: How do I split the terminal?**
`Cmd+D` (split right) and `Cmd+Shift+D` (split down) on macOS; `Ctrl+Shift+D` and
`Ctrl+Shift+E` on Windows/Linux.

**Q: How do I open my config quickly?**
`Cmd+,` (macOS) or `Ctrl+,` (Windows/Linux).

**Q: How do I jump straight to tab 3?**
Hold the tab-jump modifier (`Cmd` on macOS, `Ctrl` elsewhere) and press `3`. The
`9` key jumps to the last tab.

**Q: Can I change the keyboard shortcuts?**
Yes — add a `keymaps` object to `hyper.json` mapping command names to Mousetrap key
combinations.

**Q: How do I update Hyper itself?**
Hyper auto-updates on macOS and Windows. Choose `stable` or `canary` with
`updateChannel`, or disable updates with `disableAutoUpdates`. On Linux, update via
your package manager.

**Q: How do I keep the working directory when I open a new tab or split?**
That's the default (`preserveCWD: true`). Set it to `false` to start new sessions
in your home directory instead.

**Q: Does Hyper accept command-line arguments to change behavior?**
No. Running `hyper --help` or `hyper --version` prints diagnostic information, but
Hyper does not accept arguments to configure the terminal — use `hyper.json`
instead. (The `hyper` CLI does accept a path to open a file/folder.)

**Q: How do I report a bug with all the right details?**
**Help → Report Issue** generates a pre-filled GitHub issue including your
environment and config.

**Q: Where can I find more plugins and themes?**
Run `hyper list-remote` or `hyper search <term>`, or browse the community list at
[Awesome Hyper](https://github.com/bnb/awesome-hyper).

---

_Generated June 2026 from vercel/hyper at da0c401. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._