rossmacarthur/sheldon: A Configurable Shell Plugin Manager

Sheldon's Role in Bash and Zsh Configuration

Sheldon manages shell enhancements that would otherwise require a collection of clone commands, installation steps, and source statements in `.bashrc` or `.zshrc`. It is aimed at users of Bash and Zsh who want plugin declarations, installation behavior, and shell loading to live in one configuration model. The README lists Git repositories, arbitrary remote scripts or binary plugins, local plugins, and inline plugins as supported source types.

The central interface is a TOML file named `plugins.toml`. Each entry has a unique plugin name and a source definition. Git-based plugins can use GitHub, Gist, generic Git, or SSH, while Git sources can select a branch, tag, commit, or submodule. A configuration can therefore describe plugins maintained in different locations without placing every fetch and source command directly in the shell startup file.

Sheldon divides plugin management into distinct operations. `init` creates configuration, `add`, `edit`, and `remove` modify it, `lock` handles plugin sources and the lock file, and `source` produces shell code. This separation gives users a declarative file without requiring the startup file to encode installation recipes. It also adds a runtime dependency: the shell evaluates output generated by Sheldon rather than relying entirely on static lines.

Sheldon's Configuration, Locking, and Source Flow

According to the README, `sheldon source` installs configured plugins, generates a lock file, and prints the shell script to source. The related `sheldon lock` command installs plugin sources and generates the lock file on its own. Rerunning `lock` without extra options does not reinstall every source; it verifies sources that are already present. That distinction reduces repeated installation work while retaining a record of resolved plugin state.

Plugin options include `use`, `apply`, `profiles`, and `hooks`. The README also documents global `shell` and `match` options. Templates define installation methods, and custom templates are supported. The `use` option selects the template associated with a plugin, while `apply` determines where the resulting source is applied. Profiles and matching allow configuration to vary by context, although the README excerpt does not provide the complete matching expression syntax.

The shell integration is concise. The user evaluates Sheldon's output from the shell startup file:

eval "$(sheldon source)"

That mechanism explains why the command belongs in the shell initialization path. Without `eval`, Sheldon would only print script text. The design also means a malformed configuration, unavailable source, or failure inside the generated script can affect shell startup. Sheldon therefore trades a longer static configuration for centralized source management.

Installing Sheldon Through Cargo, Homebrew, or Nix

The README provides several installation paths. Cargo is the direct Rust package route:

cargo install sheldon

The README warns that Cargo may not use `Cargo.lock` by default in some circumstances. It documents this locked alternative:

cargo install sheldon --locked

That option asks Cargo to respect the lock file during installation.

Homebrew users can install the packaged binary with:

brew install sheldon

For a Nix environment, the README describes the repository as a flake and provides this command:

nix profile install "github:rossmacarthur/sheldon"

Users who prefer release artifacts may use `cargo-binstall`:

cargo binstall sheldon

The README also states that pre-built binaries are available for Linux x86-64, Linux aarch64, Linux armv7, and macOS x86-64. A separate installation script can detect the host, download the appropriate archive, and extract `sheldon` into a selected directory. These paths serve different environments, but users should verify that their operating system and architecture have a documented artifact before relying on a direct release download.

Initializing Bash or Zsh Plugin Configuration

After installation, create the configuration with the shell selector. For Bash, run:

sheldon init --shell bash

For Zsh, run:

sheldon init --shell zsh

The README says this creates `plugins.toml` under `$XDG_CONFIG_HOME/sheldon`, which is usually `~/.config/sheldon/plugins.toml`. If the config file already exists, `init` does nothing. This makes the command safe to repeat for initialization, although it also means an existing file will not be replaced or upgraded automatically.

Users can edit `plugins.toml` directly or manage entries with Sheldon's CLI. The README also documents a plain `sheldon init` invocation, with sensible defaults for Bash or Zsh. An explicit `--shell` is preferable when the intended target is already known because it makes the selected startup shell visible in shell history and setup scripts.

The documented default directories are not a complete XDG configuration guide. The CLI does expose `--config-dir <path>`, `--data-dir <path>`, and `--config-file <path>`, but the README excerpt does not explain when to prefer each one. Users deploying through a restricted home directory or nonstandard XDG environment should check that section of the documentation before committing the startup integration.

Adding Base16 Through TOML and the CLI

The README's first plugin example is `chriskempson/base16-shell`. It can be declared manually in `plugins.toml`:

[plugins.base16]
github = "chriskempson/base16-shell"

`base16` is the unique name used for this entry. The `github` key tells Sheldon to manage that GitHub repository.

The equivalent documented CLI operation is:

sheldon add base16 --github chriskempson/base16-shell

This command automates the configuration edit rather than requiring the user to locate the TOML file manually. The external repository controls the plugin's shell behavior, while Sheldon handles its source and generated loading code.

At this stage, editing the configuration alone is not the complete setup. Sheldon still needs to acquire or verify the plugin, generate its shell code, and connect that code to shell startup. The README does not specify how to undo an `add` operation in its visible getting-started section, although it lists `remove` among the configuration-editing commands. That omission matters for provisioning scripts because `add` should not be treated as idempotent without checking the CLI documentation.

Loading Sheldon Plugins During Shell Startup

Run `source` directly to install the configured plugin, generate the lock file, and inspect the shell code it prints:

sheldon source

For persistent loading, add the following line to `~/.bashrc` or `~/.zshrc`:

eval "$(sheldon source)"

This is the complete shell integration shown in the getting-started guide. The surrounding `eval` executes the emitted script in the current shell, which is necessary for aliases, functions, variables, and shell options to affect that session.

The arrangement makes `sheldon source` part of the startup path rather than a one-time installation script. Each new interactive shell can therefore encounter source retrieval, verification, or generated-code failures. Sheldon's `lock` command provides a separate way to prepare plugin sources and lock state, but the README does not show a startup configuration that runs `lock` once and later sources an already generated file.

The README claims fast plugin loading and parallel installation, and it links to a separate benchmark repository. Since the linked results are not present in this repository's README, no measured startup figure can be confirmed here. The documented architecture supports the claim that installation can be parallelized, but it does not justify promising a particular latency on every shell or machine.

Templates, Source Types, and Configuration Trade-offs

Sheldon's flexibility comes from its separation of plugin identity, source type, and installation template. Git plugins can select branches, tags, commits, and submodules. Remote plugins can fetch arbitrary scripts or binaries, local plugins refer to paths on the machine, and inline plugins keep definitions in configuration. First-class GitHub and Gist sources sit alongside generic Git.

Templates control how a selected source is installed. The README describes highly configurable installation methods and custom templates, which is useful when plugins do not all follow one universal layout. It also documents hooks and application controls. The cost is configuration complexity. A user must understand source selection, shell matching, profiles, templates, and where `apply` places the resulting plugin.

Source selection can also create operational dependencies. Branch-based Git sources may change when their upstream branch changes. Remote scripts can change without a repository commit. A lock file records resolution, but the README excerpt does not state its complete schema or explain commands for reviewing and accepting updates. Teams that require reproducible upgrades should inspect the lock documentation and test whether each source should be fixed to a tag or commit.

Another boundary is startup transparency. Evaluating generated code hides many commands from direct inspection in the startup file, while `sheldon source` remains visible as the entry point. Users who require a completely static, auditable shell file may prefer direct source lines and treat Sheldon's template system as unnecessary complexity.

Sheldon Maintenance, Rust Requirements, and Licensing

The repository is not archived, and its last push was on 2026-08-29. The release list includes 0.8.5 on 2025-07-22, 0.8.4 on 2025-07-08, and 0.8.3 on 2025-06-30. These records show recent repository activity and published versions, but they do not establish a long-term support policy or guarantee compatibility for an older release.

The `Cargo.toml` file declares version 0.8.5, Rust edition 2021, and `rust-version = "1.90.0"`. A source build therefore requires a compatible Rust toolchain. The README also warns that Cargo installation can fail when `Cargo.lock` is not used, which gives users a documented `cargo install sheldon --locked` response.

Plugin maintenance remains separate from Sheldon maintenance. Upgrading the binary does not by itself explain whether branch references, remote scripts, or locally built plugins have changed. Likewise, regenerating a lock file is not the same as upgrading the Sheldon executable. The README excerpt does not document rollback, so upgrade procedures should be based on the documented lock and template behavior rather than an assumed recovery command.

The repository description identifies Apache-2.0, while `Cargo.toml` declares `MIT OR Apache-2.0`. The top-level tree includes both `LICENSE-APACHE` and `LICENSE-MIT`. That is a licensing choice to verify, not legal advice, particularly for organizations that redistribute binaries or modify the source.

Sheldon Compared with Static Shell Plugin Loading

The practical alternative is direct source management in `.bashrc` or `.zshrc`. For one stable plugin, a user can clone it manually and add the required source line. That approach has fewer components: Git, Bash or Zsh, and the startup file are enough. It also leaves every executed line visible without requiring a config parser or generated shell output.

Sheldon changes that workflow by storing sources in `plugins.toml`, editing entries through commands such as `add` and `remove`, handling multiple source types, and applying templates during installation. It becomes more useful when plugins come from several hosts, revisions need explicit selection, or installation logic differs between plugins. It also becomes unnecessary when a shell environment has only static source files.

There is no wrong answer for every environment, but the boundary is clear. Direct loading is simpler when there are few plugins and no managed revision policy. Sheldon is more appropriate when one declarative file and generated startup code reduce repeated manual work. A shell that must start without invoking any external command is a poor Sheldon candidate because the documented integration depends on `sheldon source`.

Editorial conclusion

Adopt Sheldon if you want a declarative plugin workflow that combines Git, local, remote, and inline sources for Bash or Zsh. Do not select it when startup cannot depend on an external command or when a transparent static shell file is easier to maintain. Verify the shell integration, source revisions, template behavior, and lock-file update process before deployment. The repository manifest declares MIT OR Apache-2.0, so redistribution work should begin with the repository's LICENSE-APACHE and LICENSE-MIT files.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. rossmacarthur/sheldon on GitHub