# Run QH in your terminal

## Requirements

Use macOS with Bun 1.3.5 or newer and Node.js 22.13 or newer. The project CI uses Node.js 24. Run `bun --version` and `node --version` to check them.

## Install and launch

```sh
git clone https://github.com/qentrah/qh.git
cd qh
bun install --frozen-lockfile
./bin/qh --help
./bin/qh
```

QH takes over the current terminal window. It starts a shell in the current directory using `$SHELL`, with `/bin/zsh` as the fallback. Press Ctrl+B, release it, then `q` to quit; confirm the live-session dialog. The host terminal should return.

To start in another folder, use the absolute path to the cloned launcher:

```sh
cd ~/Documents
/path/to/qh/bin/qh
```

Replace `/path/to/qh` with your actual clone path. The launcher needs Bun and Node.js on `PATH`. The desktop download does not install a global `qh` command. If you want a global command from the source checkout, run `bun link` in the repository, then `qh --help`.

## Keyboard controls

All commands below follow Ctrl+B, then release the keys before the next key:

| Key | Action |
| --- | --- |
| `c` | New tab |
| `n` / `p` | Next / previous tab |
| `%` / `"` | Side-by-side / stacked split |
| Arrow keys | Focus a pane |
| Shift+arrow | Resize a divider |
| `r` | Rename the current tab |
| `x` / `w` | Close a pane / tab |
| Page Up / Page Down | Scroll history |
| `?` | Show keyboard help |
| `q` | Quit |
| Ctrl+B again | Send a literal Ctrl+B to the shell |

Ctrl+C and ordinary typing go to the focused shell. Do not type desktop commands such as `/config` at the shell prompt; those belong in the desktop Commands panel.

## Keep your own zsh prompt

```sh
QENTRAH_SHELL_STYLE=original ./bin/qh
```

This disables QH's prompt and command-highlighting customization. User startup files still load. See [themes](/docs/qh/themes) for CLI colors.

## Install and update versions

```sh
qh install latest
qh install stable
qh install v0.6.10
qh install preview --check
qh update stable
qh update --check
```

`qh install latest version` is also accepted. Latest and stable select a complete stable release. Preview includes prereleases. `--check` reports the selected version without installing. `qh update` follows your configured update channel and does not downgrade a newer install. Explicit `install VERSION` can select an older version. Draft releases and builds missing a Mac ZIP or checksum are excluded.

The public install script comes from the latest GitHub Actions release; it accepts latest, stable, preview, or a version as its argument.