FAQ and troubleshooting

Windows PowerShell's default execution policy doesn't run profile scripts, so the startup block opal adds can't run. Allow local scripts for your account (this doesn't need administrator rights):

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

opal setup warns about this when it sees it.

opal's binaries aren't code-signed. The install scripts download with PowerShell or curl, which doesn't trigger these warnings. If you downloaded an archive with a browser, Windows may show "Windows protected your PC" (click More info, then Run anyway) and macOS may refuse to open it until you allow it in System Settings > Privacy & Security.

To check that a download was built from this repository, compare it with the release's SHA256SUMS.txt, or with the GitHub CLI:

gh attestation verify opal_windows_amd64.zip --repo gjnail/opal

Opal Terminal's downloads (opal-terminal_windows_amd64.zip and so on) have their own opal-terminal_SHA256SUMS.txt and are attested the same way.

Open a new terminal: shells that were already running don't read the new startup block. If that doesn't help, run opal setup --dry-run to see which startup files opal knows about, and check that your terminal starts the shell you expect. On macOS, and in terminals that start bash as a login shell, bash reads .bash_profile; setup makes that file load .bashrc. Opal Bash reads neither; see below.

It depends on the shell:

• PowerShell: suggestions need PSReadLine 2.1 or newer, and Windows PowerShell 5.1 comes with 2.0. opal doctor shows your version. Upgrade it for your account with Install-Module PSReadLine -Scope CurrentUser -Force -SkipPublisherCheck, then open a new window.
• bash: readline can't draw them. Install ble.sh and opal loads it.
• zsh: opal draws them itself. If you load zsh-autosuggestions, it's used instead.
• fish: suggestions are built in; check that fish_autosuggestion_enabled isn't 0.

Suggestions only appear for commands you've run before in that shell.

PowerShell has built-in aliases with those names (gc is Get-Content, gl is Get-Location, gp is Get-ItemProperty), and opal keeps them unless you set shell.pwsh.clobber_builtin_aliases = true in the config. opal doctor lists every clash.

opal sets the prompt, so another prompt tool such as Starship replaces opal's prompt if it's loaded after opal, and is replaced by it if it's loaded before. zsh-autosuggestions, zsh-syntax-highlighting and fzf's key bindings work alongside opal; opal colors zsh-syntax-highlighting to match the theme and leaves Tab to fzf-tab if you use it. If something else also defines git aliases with the same names, whichever loads last wins.

opal waits for git status for 200 ms by default (git_timeout_ms). After that it shows the last known counts, marked with …, and updates them in the background, so the prompt shouldn't take much longer than that. Git's own core.fsmonitor and core.untrackedCache settings make git status itself faster in large repositories.

On Windows, the first prompt after starting a terminal can take a little longer while Windows loads git.

No. The prompt, completion, suggestions, history and tools work in any terminal. Opal Terminal is an extra that uses the same config and theme. To install opal without it, set OPAL_NO_TERMINAL=1 before running the install script.

That's on purpose: Opal Bash reads its own startup file, which loads opal, so it isn't affected by what other bash setups on the machine put in ~/.bashrc and ~/.bash_profile. Aliases, functions and environment variables for every shell go in config.toml (see Configuration). For things only bash understands, such as shopt settings, create ~/.config/opal/bashrc; Opal Bash reads it after loading opal.

Choose it under Shell on the settings page (Ctrl+Comma), or set it in config.toml:

[terminal]
shell = "PowerShell"

The command palette's "New tab" entries open any of the other shells without changing the default.

On Windows, the script won't replace files that are in use. Close every Opal Terminal window, and any program you started from Opal Bash that's still running, then run the script again.

The app has an ad-hoc signature rather than a Developer ID one, so macOS blocks a copy that was downloaded with a browser. The install script's copy isn't affected. Allow it with Open Anyway in System Settings > Privacy & Security, or run:

xattr -dr com.apple.quarantine "$HOME/Applications/Opal Terminal.app"

The ConPTY built into Windows drops the escape sequences images use. Opal Terminal uses Microsoft's newer one when conpty.dll and OpenConsole.exe are next to opal-terminal.exe. The install script and the Windows download include them; for a build of your own, run terminal/scripts/fetch-conpty.ps1.

• Config: ~/.config/opal/ on every system, including Windows (%USERPROFILE%\.config\opal).
• Data: %LOCALAPPDATA%\opal on Windows, ~/.local/share/opal elsewhere. It holds history.tsv (the shared history), jump.tsv (remembered folders), caches for git status and tool completions, Opal Bash's bash_history, and Opal Terminal's terminal-session.json, which holds the recent output of each pane for session restore.
• The program: %LOCALAPPDATA%\opal\bin or ~/.local/bin when installed with the scripts.
• Opal Terminal: %LOCALAPPDATA%\opal\terminal and a Start menu shortcut on Windows, ~/Applications/Opal Terminal.app on macOS, and ~/.local/bin/opal-terminal with a menu entry in ~/.local/share/applications on Linux.

No. opal only goes online when you run opal update, opal plugin install or opal plugin update, and on Windows when opal setup offers to upgrade PSReadLine and you accept. Opal Terminal has no network code. Installing it from a clone of the repository downloads Opal Bash's packages from MSYS2 and the newer ConPTY from Microsoft's NuGet feed.

Start it with a space. The shared history skips those lines, as bash and zsh do. To stop recording entirely, set shared = false under [history]. The history file is readable only by your account.

Run opal setup --remove to take opal out of your startup files, then delete the program, Opal Terminal and the folders listed above. On Windows, also remove %LOCALAPPDATA%\opal\bin from your user PATH in Settings > System > About > Advanced system settings > Environment Variables.

Open an issue on GitHub with your OS, shell and version, terminal, and the output of opal doctor. Problems that could make a shell run a command it shouldn't should be reported privately, as described in SECURITY.md. Pull requests are welcome; see the contributing guide.