Plugins

A plugin is a set of aliases, functions and environment variables written once in TOML. opal turns it into zsh, bash, fish or PowerShell code when each shell starts.

opal plugin list shows every plugin and whether it's active in the current shell. Enable or disable one with opal plugin enable NAME and opal plugin disable NAME, then open a new terminal or run reload.

Built-in plugins

Plugin	What it adds
`core`	`..`, `...`, `mkcd`, `up N`, `ll`, `la`, `reload`, and `open`, `clipcopy`/`clippaste`, `x` (extract), `ports` and `paths`. Adds `pbcopy` and `pbpaste` on systems that don't have them.
`git`	The git aliases below, plus `gcm`, `gswm` and `grbm`, which find the repository's main branch.
`jump`	`j WORDS` to go to a folder you've visited, and `ji` to pick one with fzf.
`python`	`va` activates the nearest virtualenv in any shell, `mkvenv` creates one, `vd` deactivates it, `pyserve` starts a web server.
`node`	`jsi`, `jsa`, `jsr`, `jsd`, `jsb`, `jst`, `jsx`: install, add, run, dev, build, test and dlx with npm, pnpm, yarn or bun, whichever the project's lockfile uses.
`docker`	`dps`, `dex`, `dlog`, `dc`, `dcu`, `dcd` and more. Only active where docker is installed.
`kubectl`	`k`, `kgp`, `kgs`, `kd`, `kl`, `kaf`, `kns` and more. Only active where kubectl is installed.
`pkg`	`pkg install\|remove\|search\|update\|upgrade\|list\|info` with brew, apt, dnf, pacman, zypper, apk, winget, scoop or choco. It prints the real command before running it.

Git aliases

Alias	Runs
`g`	`git`
`ga`	`git add`
`gaa`	`git add --all`
`gapa`	`git add --patch`
`gb`	`git branch`
`gba`	`git branch --all`
`gbd`	`git branch --delete`
`gc`	`git commit --verbose`
`gca`	`git commit --verbose --all`
`gcam`	`git commit --all --message`
`gcmsg`	`git commit --message`
`gcb`	`git checkout -b`
`gco`	`git checkout`
`gcl`	`git clone --recurse-submodules`
`gcp`	`git cherry-pick`
`gcf`	`git config --list`
`gd`	`git diff`
`gds`	`git diff --staged`
`gf`	`git fetch`
`gfa`	`git fetch --all --prune`
`gl`	`git pull`
`glo`	`git log --oneline --decorate`
`glog`	`git log --oneline --decorate --graph`
`gloga`	`git log --oneline --decorate --graph --all`
`gm`	`git merge`
`gp`	`git push`
`gpf`	`git push --force-with-lease`
`gpsup`	`git push --set-upstream origin HEAD`
`gr`	`git remote`
`grv`	`git remote --verbose`
`grb`	`git rebase`
`grbi`	`git rebase --interactive`
`grba`	`git rebase --abort`
`grbc`	`git rebase --continue`
`grh`	`git reset`
`grhh`	`git reset --hard`
`grs`	`git restore`
`grst`	`git restore --staged`
`gsh`	`git show`
`gsta`	`git stash push`
`gstp`	`git stash pop`
`gstl`	`git stash list`
`gst`	`git status`
`gss`	`git status --short`
`gsw`	`git switch`
`gswc`	`git switch --create`
`gcm`	Check out the main branch (main, trunk, master... whatever this repo uses)
`gswm`	Switch to the main branch
`grbm`	Rebase onto the main branch

In PowerShell, gc, gcm, gl, gm and gp clash with built-in aliases, which opal keeps by default. Set shell.pwsh.clobber_builtin_aliases = true to use the git versions.

Installing plugins from git

opal plugin install someone/opal-plugin-terraform
opal plugin update
opal plugin remove terraform

install clones the repository into ~/.config/opal/plugins/ and enables it. The name comes from the repository, without an opal-plugin- prefix. Any git URL works too. update runs git pull in each installed plugin.

Writing a plugin

Save a TOML file as ~/.config/opal/plugins/NAME.toml, add its name to plugins in the config, and open a new terminal.

name = "terraform"
description = "Terraform shortcuts"
requires = ["terraform"]            # skipped where terraform isn't installed

[aliases]
tf  = "terraform"
tfp = "terraform plan"
tfa = "terraform apply"

[functions.tfw]
desc = "Switch workspace"
sh   = 'terraform workspace select "$1"'
fish = 'terraform workspace select $argv[1]'
pwsh = 'terraform workspace select $args[0]'

[env]
CHECKPOINT_DISABLE = "1"          # no upgrade checks

[native]
bash = 'complete -o nospace -C terraform terraform'

Values follow the same rules as your own aliases and functions: a string applies everywhere, a table picks the most specific key for the shell and OS, and an empty string leaves the entry out. [native] holds code that's included as it is, for a shell feature opal doesn't translate.

To publish a plugin, put the file at the root of a git repository as plugin.toml. The repository can also contain init.zsh, init.bash, init.fish or init.ps1 files, which are included for that shell.