Getting started

Install opal, open a new terminal, and try the features that work the same in every shell.

1. Install

On Windows, in PowerShell:

irm https://raw.githubusercontent.com/gjnail/opal/main/install/install.ps1 | iex

On macOS and Linux, and in WSL:

curl -fsSL https://raw.githubusercontent.com/gjnail/opal/main/install/install.sh | sh

The script downloads the latest release, checks it against the release's SHA256SUMS.txt, and puts opal in %LOCALAPPDATA%\opal\bin on Windows or ~/.local/bin elsewhere. Then it runs opal setup, which:

creates ~/.config/opal/config.toml;
adds a block marked # >>> opal >>> to the startup file of each shell it finds (.zshrc, .bashrc, fish's conf.d/opal.fish, and the profiles of Windows PowerShell and PowerShell 7), keeping a .opal-backup of each file it changes;
imports your existing PowerShell, bash, zsh and fish history into the shared history;
on Windows, offers to upgrade PSReadLine if it's too old for suggestions.

The script also installs Opal Terminal, opal's own terminal app: with a Start menu shortcut on Windows, where it comes with its own bash, Opal Bash; in ~/Applications on macOS; and with a menu entry on Linux desktops. Set OPAL_NO_TERMINAL=1 before running it to leave the terminal out. opal terminal opens it in the current folder.

To build from source instead, clone the repository and run ./install/install.sh or .\install\install.ps1. You need Go 1.22 or newer, or 1.24 or newer on macOS; Opal Terminal needs Go 1.26, and is downloaded instead when your Go is older.

2. Open a new terminal

Terminals that were already open don't see the change. In a new one you'll get a short banner and the prompt:

zsh  ╭─◆ opal/internal/prompt on main ⇡1 +2 !1 ?3                      took 3.2s
     ╰─❯ 
bash ╭─◆ opal/internal/prompt on main ⇡1 +2 !1 ?3 ◇ api
     ╰─❯ 
fish ╭─◆ opal/internal/prompt on main ⇡1 +2 !1 ?3                            ✦ 1
     ╰─❯ 
pwsh ╭─◆ opal\internal\prompt on main ⇡1 +2 !1 ?3                ✘ 127 not found
     ╰─❯

Inside a git repository the path starts at the repository's folder, and the counts after the branch are commits ahead (⇡), staged (+), modified (!) and untracked (?) files. The duration shows up after commands that take longer than two seconds, and the exit code after commands that fail.

Run opal doctor to see what opal detected about your system, terminal and shell, and which features are active.

3. Tab completion

Type git checkout and press Tab to see your branches. The git aliases complete the same way: gco then Tab. In PowerShell this comes from opal; zsh, bash and fish already have git completion, and opal adds its own commands and the aliases.

If docker, kubectl, gh, helm, uv, deno, pnpm, just or winget is installed, opal also loads the completion script that tool generates. It's cached and loaded the first time you press Tab after that command.

4. Suggestions

Start typing a command you've run before. Grey text shows the rest of it; press Tab or the Right arrow to accept it. In PowerShell, Ctrl+Space opens the completion menu even when a suggestion is showing, and F2 switches to a list of suggestions.

Suggestions come from fish and PSReadLine themselves, from opal's own engine in zsh (or zsh-autosuggestions if you load it), and from ble.sh in bash if it's installed. See the FAQ if you don't see them.

5. Shared history

Press Ctrl+R. A full-screen search opens over every command you've run in any shell. Type words in any order to narrow it down, use the arrow keys to pick one, and press Enter to put it on your command line. Ctrl+R again switches between all shells, the current folder and the current shell. Esc closes it.

Commands that start with a space aren't recorded, as in bash and zsh.

6. Jump between folders

opal remembers the folders you visit. j proj goes to the folder you use most whose name contains "proj". j work api narrows it down further. With fzf installed, ji lets you pick from a list.

7. Pick a theme

opal theme preview
opal theme set boulder

The new theme applies at the next prompt. See Themes for what each one looks like.

8. Make it yours

opal config edit opens the config file. You can add your own aliases, functions and environment variables there, turn features off, and enable or disable plugins. See Configuration.

Updating and removing opal

opal update installs the latest release (or, if you built opal from a clone, pulls and rebuilds it). opal setup --remove removes the blocks opal added to your startup files; after that you can delete the opal program and the folders listed in the FAQ.