1Password shell-plugins: a registry of credential brokers for the terminal

What this repository is, and what it is not

The name suggests a set of shell scripts, and it is not. This is the Go source repository for the plugins that 1Password CLI uses to authenticate command line tools. The problem it addresses is narrow and real: tools like the GitHub CLI expect a credential sitting in a file under your home directory, and a shell plugin replaces that static secret with a short-lived one that you approve from the terminal, by fingerprint on the platforms where 1Password supports it.

What you find in the tree is a plugin directory, an SDK package, and command line tools for contributors. The description on the repository is that 1Password shell plugins authenticate any CLI with your fingerprint, and the documentation links point to the 1Password developer site for usage and contribution guides. The plugin code here is not what runs on an end user's machine in the normal case. The compiled plugins ship as part of 1Password CLI, and this repository holds the sources plus the scaffolding used to add new ones.

The mechanism is a shell function that calls op plugin run

The runtime contract is visible in the pattern the documentation uses for every plugin. A shell function with the same name as the target tool delegates to `op plugin run`, passing the tool name and the original arguments through. The GitHub CLI example is the clearest one:

gh() {
  op plugin run -- gh "$@"
}

The plugin is not a wrapper script that reads a secret and exports an environment variable. It is a Go program that knows how to obtain a credential for one specific service, using the provider and item identifiers declared in the plugin's own configuration. When the function runs, the plugin asks 1Password for that credential, prompts you for approval, and hands the tool a session that expires on its own.

The fish version of the same function uses the `--wraps` mechanism and a description string:

function gh --wraps gh --description "1Password shell plugin for GitHub CLI"
  op plugin run -- gh $argv
end

That is the whole extension surface for a user: a function that shadows the command, and a plugin behind it.

The approach differs from the usual way of getting a token into a CLI. The alternative is a long-lived credential written into a file under the home directory, which the shell plugin exists to replace, in the project's own phrase a way of having no more plaintext credentials in your home directory. The difference is where the secret lives and how long it lives there: the file approach keeps a durable value on disk that any process running as you can read, while the plugin asks 1Password for a short-lived session and has you approve each use, so the durable value stays inside the vault rather than in a dotfile.

op plugin init writes plugins.sh and then owns that file

The default path avoids dotfiles entirely. The documentation states that `op plugin init` writes its configuration to `~/.config/op/plugins.sh` and manages that file for you. In practice that means the file with all your generated function definitions appears in a hidden config directory, and the tool keeps it current as plugins are added or changed.

The trade-off is ownership. The file is generated, not hand-written, and a user who edits it directly is editing something the CLI will rewrite. The documentation draws a clear line here: `op plugin init <plugin>` edits that path directly and will not update your own dotfiles, so a user who wants dotfile management has to configure plugins manually and tell the CLI that the work is already done.

For a team that keeps shell configuration in version control, that split is the decision to make. Either the CLI owns `~/.config/op/plugins.sh` and the repository stays out of it, or the team owns the functions and the CLI is told to keep its hands off.

OP_PLUGIN_ALIASES_SOURCED is the switch for dotfile-managed setups

The escape hatch is an environment variable. If you define the shell functions yourself and source them from your shell configuration, you set `OP_PLUGIN_ALIASES_SOURCED=1` so 1Password CLI knows the aliases are already in place and does not try to manage them. In bash and zsh that is a plain export:

export OP_PLUGIN_ALIASES_SOURCED="1"

In fish the same thing is expressed as a exported variable:

set -x OP_PLUGIN_ALIASES_SOURCED 1

This is a small mechanism with a wide blast radius, which is worth stating plainly. The variable tells the CLI that alias definitions exist elsewhere, so from that point the CLI will not generate or maintain them. If a plugin is later added to your 1Password account and the CLI does not create its function, the cause is almost always this flag, and the fix is to add the function yourself or to unset the variable.

The documentation's own advice is worth repeating in another form: the supported route for dotfile users is to define the functions by hand and source them, rather than running `op plugin init` and then copying the result.

Writing a plugin starts with make new-plugin

Contributing is a Makefile-driven workflow, and the quick start given for a new contributor is a single command:

make new-plugin

The Makefile shows what that does. The `new-plugin` target depends on `beta-notice` and runs `go run cmd/contrib/main.go new-plugin`, so the scaffolding is generated by a Go program under `cmd/contrib` rather than by a template file copied by hand.

The Makefile also shows the shape of the rest of the workflow. The `registry` target deletes `plugins/plugins.go` and regenerates it, and most validation targets depend on it, so the plugin registry is a generated artefact that has to be rebuilt whenever a plugin is added. A per-plugin build target compiles a single plugin to an output directory with the plugin name baked in through a linker flag, and the `validate` target runs the same contrib program in validation mode. The `test` target runs the Go test suite across the module, and the `lint` target runs golangci-lint in a container, pinned to a specific version that the Makefile says should stay in sync with the version used in CI.

The beta notice in the Makefile is a warning about recompilation

Several contributor-facing targets depend on a `beta-notice` target whose output is a three line comment printed before the build runs. It reads that the plugin ecosystem is in beta and subject to change, and that you may have to update or recompile your local builds every now and then to keep them compatible with 1Password CLI updates.

That is a real constraint on anyone writing a plugin, and it is the reason the repository can move fast without promising stability. The plugin build output goes into a plugins directory under the local 1Password config, and the Makefile sets restrictive permissions on the config directory and the plugins directory it creates, 700 for both. A plugin built locally is a binary you compiled yourself and placed there, and it is only useful if it stays compatible with the CLI version you have.

The README marks the contribution path as beta for the same reason. Contributing is a pull request against this repository, and the project offers pairing sessions and a developer Slack workspace to people who want help building a plugin.

Go dependencies reveal the credential path, and where the project stops

The go.mod file shows the module path `github.com/1Password/shell-plugins`, requires Go 1.24, and pulls in a set of libraries that map directly onto how a plugin gets a credential. The AWS SDK v2 and its STS service are there, so AWS sessions are issued rather than copied. Two keyring libraries appear, the 99designs keyring and its keychain and wincred backends, which points at the system keychain as the place where long-lived secrets are held on a user's machine. The hashicorp go-plugin library provides the plugin process model, and the TOML, INI and YAML libraries reflect the configuration formats the plugins read.

What the repository does not contain is equally telling. There is no plugin binary here for the end user, since the built plugins ship inside 1Password CLI itself. The repository has no GitHub releases, so there is no tagged version of the plugin set to pin against, and the version that matters in practice is the one inside the 1Password CLI you installed. The result is a codebase that is a source of truth and an extension point, but not the thing you run.

Editorial conclusion

Adopt this repository if you are writing a shell plugin for a CLI that 1Password does not cover yet, and you can accept that the ecosystem is labelled beta and that your plugin has to be recompiled when 1Password CLI moves on. Skip it if your only need is a working alias for an already supported tool, because the plugin binary itself ships with 1Password CLI and this repository is the source for extending it. Verify first that `op plugin init` writes to a path you are willing to let the tool manage, and that the plugin you need is either already listed or accepted as a pull request against this repository.

Frequently asked questions

Official sources

1. 1Password/shell-plugins on GitHub
2. Issues
3. License: MIT
4. Project website
5. README