Configuration

All shells read the same file: ~/.config/opal/config.toml, on Windows as well. opal config edit opens it, and opal config path prints where it is.

Most settings apply at the next prompt. Aliases, functions, plugins and key bindings apply in new terminals, or after running reload.

General

[prompt]

[history]

[shell.fish] and [shell.pwsh]

[core], [pkg] and [update]

[terminal]

Opal Terminal's settings. Its settings page (Ctrl+Comma, or Cmd+Comma on macOS) edits them and applies each change right away; changes made by hand apply after Reload settings in the command palette, or the next time Opal Terminal starts.

Programs can use the clipboard through OSC 52, which is how copying works over ssh:

[terminal.colors] overrides colors the theme sets: foreground, background, cursor, cursor_text, selection, and palette, a list of up to 16 colors for the ANSI palette.

[terminal]
font_family = ["JetBrains Mono", "Cascadia Mono"]
font_size = 13
shell = "PowerShell"

[terminal.colors]
background = "#101014"
palette = ["#000000", "#ff5555"]    # the first two ANSI colors

Profiles

Each [[terminal.profiles]] entry adds a shell or program to the command palette's "New tab" list, and shell can name it. A profile with the same name as a shell Opal Terminal finds replaces that one.

[[terminal.profiles]]
name = "work box"
command = "ssh"
args = ["me@work"]

[[terminal.profiles]]
name = "api"
command = "pwsh"
cwd = "~/src/api"
env = { ASPNETCORE_ENVIRONMENT = "Development" }

Keys

[terminal.keys] maps a shortcut to an action. "none" removes a default. Shortcuts are written like "ctrl+shift+t", "alt+enter" or "super+k" (Cmd on macOS). The defaults are on the Opal Terminal page.

[terminal.keys]
"ctrl+shift+t" = "new_tab"
"ctrl+alt+k" = "clear_scrollback"
"f11" = "none"

The actions: new_tab, new_window, duplicate_tab, rename_tab, close_tab, close_pane, next_tab, prev_tab, goto_tab_1 to goto_tab_9, split_right, split_down, split_auto, focus_left, focus_right, focus_up, focus_down, resize_left, resize_right, resize_up, resize_down, toggle_zoom, toggle_broadcast, toggle_fullscreen, copy, paste, select_all, select_last_output, copy_last_output, find, quick_select, command_palette, history_search, recent_dirs, prev_prompt, next_prompt, scroll_up, scroll_down, scroll_page_up, scroll_page_down, scroll_top, scroll_bottom, clear_scrollback, reset_terminal, restart_pane, font_bigger, font_smaller, font_reset, settings, open_config and reload_config.

Your own aliases, functions and environment variables

These go in [aliases], [functions.NAME] and [env], and take precedence over plugins. A plain string works in every shell:

[aliases]
k = "kubectl"

[env]
EDITOR = "nvim"

When a value needs to differ, use a table. The most specific key that exists wins, in this order: the shell with the OS (bash.windows), the shell (zsh, bash, fish, pwsh), sh for bash and zsh together, the OS (wsl, linux, macos, windows), unix for macOS and Linux, and finally default. An empty string means "not in this shell".

[aliases]
ll  = { unix = "ls -lh", pwsh = "Get-ChildItem" }
cls = { sh = "clear", fish = "clear", pwsh = "" }

[env]
PAGER = { unix = "less -R", windows = "" }

Functions have one body per shell, because each shell reads arguments differently:

[functions.mkproj]
sh   = 'mkdir -p "$HOME/src/$1" && cd "$HOME/src/$1"'
fish = 'mkdir -p ~/src/$argv[1]; and cd ~/src/$argv[1]'
pwsh = '$d = Join-Path $HOME "src/$($args[0])"; New-Item -ItemType Directory -Force $d | Out-Null; Set-Location $d'

Any entry can have requires = ["tool"], to be skipped where a command isn't installed, or unless = ["tool"], to be skipped where it is.

Environment variables