### Install Sheldon via Package Managers or Script

Source: https://context7.com/rossmacarthur/sheldon/llms.txt

Choose an installation method based on your system and preferences. Homebrew and the binary installer script are recommended for quick setup.

```sh
# Homebrew (macOS/Linux)
brew install sheldon
```

```sh
# Cargo (from crates.io)

```

```sh
cargo install sheldon --locked
```

```sh
# Cargo BInstall (downloads pre-built binaries)

```

```sh
cargo binstall sheldon
```

```sh
# Nix flake

```

```sh
nix profile install "github:rossmacarthur/sheldon"
```

```sh
# Pre-built binary installer (auto-detects OS/arch, installs to ~/.local/bin)

```

```sh
curl --proto '=https' -fLsS https://rossmacarthur.github.io/install/crate.sh \
    | bash -s -- --repo rossmacarthur/sheldon --to ~/.local/bin
```

```sh
# Build from source

```

```sh
git clone https://github.com/rossmacarthur/sheldon.git
cd sheldon
cargo build --release
# binary available at target/release/sheldon
```

--------------------------------

### Sheldon TOML Configuration Example

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/RELEASES.md

An example of how a plugin is represented in the Sheldon configuration file after using the `add` command.

```toml
[plugins.example]
github = "owner/repo"
tag = "v0.1.0"
```

--------------------------------

### Install Sheldon with cargo-binstall

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Installation.md

Install Sheldon using cargo-binstall, which downloads release artifacts directly from GitHub.

```bash
cargo binstall sheldon
```

--------------------------------

### Full plugins.toml Example for Zsh

Source: https://context7.com/rossmacarthur/sheldon/llms.txt

A comprehensive TOML configuration file for Sheldon, demonstrating custom templates, deferred loading, plugins, hooks, and profiles for Zsh.

```toml
# ~/.config/sheldon/plugins.toml

shell = "zsh"

# ── Custom templates ────────────────────────────────────────────────────────

[templates]
defer = '{{ hooks?.pre | nl }}{% for file in files %}zsh-defer source "{{ file }}"
{% endfor %}{{ hooks?.post | nl }}'

# ── Deferred loading infrastructure ─────────────────────────────────────────

[plugins.zsh-defer]
github = "romkatv/zsh-defer"

# ── Prompt / theme ───────────────────────────────────────────────────────────

[plugins.powerlevel10k]
github = "romkatv/powerlevel10k"
apply = ["source"]

# ── Completion engine ────────────────────────────────────────────────────────

[plugins.zsh-completions]
github = "zsh-users/zsh-completions"
apply = ["fpath"]

# ── Deferred UX plugins ───────────────────────────────────────────────────────

[plugins.zsh-autosuggestions]
github = "zsh-users/zsh-autosuggestions"
use = ["{{ name }}.zsh"]
apply = ["defer"]

[plugins.zsh-syntax-highlighting]
github = "zsh-users/zsh-syntax-highlighting"
apply = ["defer"]

# ── Navigation ───────────────────────────────────────────────────────────────

[plugins.z]
remote = "https://github.com/rupa/z/raw/master/z.sh"

# ── Work-only tools ──────────────────────────────────────────────────────────

[plugins.work-scripts]
local = "~/work/shell-tools"
profiles = ["work"]

# ── Inline utilities ─────────────────────────────────────────────────────────

[plugins.utils]
inline = '''
mkcd() { mkdir -p "$1" && cd "$1"; }
up()   { cd $(printf "%0.s../" $(seq 1 ${1:-1})); }
'''

```

--------------------------------

### Install Sheldon with Nix

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Installation.md

Use this command to install Sheldon as a flake using nix profile.

```bash
nix profile install "github:rossmacarthur/sheldon"
```

--------------------------------

### Plugin Apply Configuration

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Configuration.md

Specify which templates to apply to a plugin. This example applies the 'PATH' and 'fpath' templates, skipping the default 'source' template.

```toml
[plugins.example]
github = "owner/repo"
apply = ["PATH", "fpath"]
```

--------------------------------

### Configure Plugin Hooks (TOML)

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/README.md

Define statements to be executed before ('pre') or after ('post') plugin installation.

```toml
[plugins.example]
github = "owner/repo"

[plugins.example.hooks]
pre = "export TEST=test"
post = "unset TEST"

```

--------------------------------

### Install Sheldon with Homebrew

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Installation.md

Install Sheldon using the Homebrew package manager.

```bash
brew install sheldon
```

--------------------------------

### Install Sheldon with Compact Profile

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/RELEASES.md

Install Sheldon using the 'compact' release profile, optimized for binary size.

```sh
cargo install --profile compact sheldon
```

--------------------------------

### Source a plugin with default template

Source: https://context7.com/rossmacarthur/sheldon/llms.txt

Example of sourcing a plugin using the default 'source' template. Demonstrates using custom config and data directories at runtime.

```sh
# source "/home/user/.local/share/sheldon/repos/github.com/zsh-users/zsh-autosuggestions/zsh-autosuggestions.zsh"

# Use a custom config/data dir at runtime
sheldon --config-dir ~/.sheldon --data-dir ~/.sheldon/data source
```

--------------------------------

### Plugin Hooks Configuration

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Configuration.md

Configure pre and post-installation hooks for plugins. These commands are executed before and after a plugin is installed.

```toml
[plugins.example]
github = "owner/repo"

[plugins.example.hooks]
pre = "export TEST=test"
post = "unset TEST"
```

--------------------------------

### Install Sheldon with Cargo

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Installation.md

Install Sheldon from Crates.io using Cargo, the Rust package manager.

```bash
cargo install sheldon
```

--------------------------------

### Install Sheldon using Pre-built Binaries Script

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Installation.md

Automatically detect host system, download, and extract the sheldon binary to a specified directory using a curl script.

```bash
curl --proto '=https' -fLsS https://rossmacarthur.github.io/install/crate.sh \
    | bash -s -- --repo rossmacarthur/sheldon --to ~/.local/bin
```

--------------------------------

### Custom Defer Template Example

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/RELEASES.md

Example of a custom 'defer' template in TOML format. It demonstrates the use of the optional access operator '.?' for safely accessing nested fields like 'hooks.pre' and 'hooks.post'.

```toml
[templates]
defer = "{{ hooks?.pre | nl }}{% for file in files %}zsh-defer source \"{{ file }}\"\n{% endfor %}{{ hooks?.post | nl }}"
```

--------------------------------

### Lock Plugins and Generate Lock File

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Command-line-interface.md

Installs plugin sources and generates the lock file. Rerunning without extra options verifies installation and regenerates the lock file.

```sh
sheldon lock
```

--------------------------------

### Install Sheldon with Cargo

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/README.md

Install Sheldon from crates.io using Cargo. Consider using the --locked option if you encounter issues.

```shell
cargo install sheldon
```

```shell
cargo install sheldon --locked
```

--------------------------------

### Lock Plugins and Generate Lock File

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/README.md

Installs plugin sources and generates a lock file. Rerunning without options verifies installation and regenerates the lock file. Use `--update` to update sources or `--reinstall` to force a reinstall.

```sh
sheldon lock
```

```sh
sheldon lock --update
```

```sh
sheldon lock --reinstall
```

--------------------------------

### Install Sheldon with Cargo (Locked)

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Installation.md

When Cargo installation fails due to missing Cargo.lock, use the --locked option.

```bash
cargo install sheldon --locked
```

--------------------------------

### TOML Configuration for Extended Glob Syntax

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/RELEASES.md

Example of using extended glob syntax in Sheldon's TOML configuration for plugin usage. Supports patterns like `{a,b}` and `!`. Ensure your patterns correctly match the desired files.

```toml
[plugins.ohmyzsh]
github = "ohmyzsh/ohmyzsh"
dir = "lib"
use = ["{!git,!nvm,*}.zsh]

```

--------------------------------

### Manage Plugin Sources and Lock File

Source: https://context7.com/rossmacarthur/sheldon/llms.txt

Generate or update the `plugins.lock` file by installing plugin sources. Use `--update` to pull latest changes or `--reinstall` to force a full re-clone.

```sh
# Verify installs and regenerate lock file (no re-download)

```

```sh
sheldon lock
```

```sh
# Update all plugins to the latest commit/tag

```

```sh
sheldon lock --update
```

```sh
# Force full reinstall of all plugin sources

```

```sh
sheldon lock --reinstall
```

--------------------------------

### Build Sheldon from Source with Cargo

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Installation.md

Build Sheldon from source after installing Rust and Cargo. The binary will be located in target/release/sheldon.

```bash
git clone https://github.com/rossmacarthur/sheldon.git
cd sheldon
cargo build --release
```

--------------------------------

### Install Sheldon with Vendored OpenSSL

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/RELEASES.md

Install Sheldon using Cargo with the 'vendored-openssl' feature flag. This ensures that OpenSSL dependencies are vendored locally.

```bash
cargo install sheldon --features vendored-openssl
```

--------------------------------

### Update Custom Template for Hooks

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/RELEASES.md

Update a custom template like 'defer' to support hooks. This example shows how to integrate 'pre' and 'post' hooks within the template.

```toml
[templates]
defer = "{{ hooks | get: \"pre\" | nl }}{% for file in files %}zsh-defer source \"{{ file }}\"\n{% endfor %}{{ hooks | get: \"post\" | nl }}"
```

--------------------------------

### Custom Template Definitions

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Configuration.md

Define custom templates for generating shell source code. This example shows how to define 'source', 'PATH', 'path', and 'fpath' templates.

```toml
[templates]
source = """
{{ hooks?.pre | nl }}{% for file in files %}source "{{ file }}"
{% endfor %}{{ hooks?.post | nl }}"""
PATH = 'export PATH="{{ dir }}:$PATH"'
path = 'path=( "{{ dir }}" $path )'
fpath = 'fpath=( "{{ dir }}" $fpath )'
```

--------------------------------

### Update Template for Per-Plugin Application

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/RELEASES.md

Modify templates to apply per plugin using a for loop, as the 'each' field is removed. This example shows the new syntax for the 'defer' template.

```toml
[templates]
defer = """
{% for file in files %}
  zsh-defer source "{{ file }}"
{% endfor %}
"""
```

--------------------------------

### Execute Hooks Before or After Sourcing Plugins

Source: https://context7.com/rossmacarthur/sheldon/llms.txt

Use `hooks.pre` to run commands before a plugin is sourced and `hooks.post` for commands after. These are inserted as raw shell strings.

```toml
[plugins.nvm]
github = "nvm-sh/nvm"
use = ["nvm.sh"]

[plugins.nvm.hooks]
pre  = 'export NVM_DIR="$HOME/.nvm"'
post = 'nvm use default --silent'
```

--------------------------------

### Initialize Sheldon Configuration

Source: https://context7.com/rossmacarthur/sheldon/llms.txt

Create a new `plugins.toml` configuration file. The `--shell` flag customizes defaults for Zsh or Bash.

```sh
# Initialize for Zsh (default)

```

```sh
sheldon init --shell zsh
# → creates ~/.config/sheldon/plugins.toml
```

```sh
# Initialize for Bash

```

```sh
sheldon init --shell bash
# → creates ~/.config/sheldon/plugins.toml with bash defaults
```

```sh
# Use a custom config directory via env var or flag

```

```sh
SHELDON_CONFIG_DIR=~/.sheldon sheldon init --shell zsh

```

```sh
sheldon --config-dir ~/.sheldon init --shell zsh
```

--------------------------------

### Plugin option: use

Source: https://context7.com/rossmacarthur/sheldon/llms.txt

Selects specific files from a plugin's source directory, overriding the global `match` pattern. Accepts a list of file names or globs.

```toml
[plugins.pure]
github = "sindresorhus/pure"
use = ["async.zsh", "pure.zsh"]   # source exactly these two files in order

[plugins.fzf-tab]
github = "Aloxaf/fzf-tab"
use = ["*.plugin.zsh"]
```

--------------------------------

### Global Apply Configuration

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Configuration.md

Specify the default list of templates to apply to all plugins. Defaults to applying the 'source' template.

```toml
apply = ["source"]
```

--------------------------------

### Add Plugins to `plugins.toml`

Source: https://context7.com/rossmacarthur/sheldon/llms.txt

Add plugin entries to your `plugins.toml` file using various source flags. Options like `--tag`, `--branch`, and `--use` allow fine-grained control.

```sh
# Add a GitHub plugin (shorthand for owner/repo)

```

```sh
sheldon add zsh-autosuggestions --github zsh-users/zsh-autosuggestions
```

```sh
# Add a GitHub plugin pinned to a specific tag

```

```sh
sheldon add example --github owner/repo --tag v2.3.0
```

```sh
# Add a GitHub plugin using SSH instead of HTTPS

```

```sh
sheldon add private-plugin --github myorg/private-repo --proto ssh
```

```sh
# Add a Gist plugin

```

```sh
sheldon add mygist --gist 579d02802b1cc17baed07753d09f5009
```

```sh
# Add a generic Git URL

```

```sh
sheldon add my-repo --git https://github.com/owner/repo.git
```

```sh
# Add a remote script (downloaded directly)

```

```sh
sheldon add my-script --remote https://example.com/plugin.zsh
```

```sh
# Add a local plugin directory

```

```sh
sheldon add my-local --local '~/projects/my-zsh-plugin'
```

```sh
# Add with custom file glob and apply templates

```

```sh
sheldon add pure --github sindresorhus/pure --use async.zsh pure.zsh
```

```sh
sheldon add autojump --github wting/autojump --dir bin --apply PATH source
```

--------------------------------

### Configure Plugin 'apply' Option (CLI)

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/README.md

Add a plugin using the 'sheldon add' command with the '--apply' option to specify templates.

```sh
sheldon add example --github owner/repo --apply source PATH

```

--------------------------------

### Configure Plugin 'use' Option (CLI)

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/README.md

Add a plugin using the 'sheldon add' command with the '--use' option to specify files or globs.

```sh
sheldon add example --github owner/repo --use '*.zsh'

```

--------------------------------

### Generate Shell Completion Scripts

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Command-line-interface.md

Generates shell completion scripts for Bash and Zsh. The output is sent to stdout and can be redirected to a file for installation.

```sh
sheldon completions --shell bash > /path/to/completions/sheldon.bash
```

```sh
sheldon completions --shell zsh > /path/to/completions/_sheldon
```

--------------------------------

### Configure Plugin Apply with PATH and fpath (TOML)

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/README.md

Apply specific templates like 'PATH' and 'fpath' to a plugin, controlling how its directory is integrated into the shell environment.

```toml
[plugins.example]
github = "owner/repo"
apply = ["PATH", "fpath"]

```

--------------------------------

### Declare Local source plugin

Source: https://context7.com/rossmacarthur/sheldon/llms.txt

Declares a plugin from a local directory path. Tilde expansion is supported for `$HOME`.

```toml
[plugins.my-dev-plugin]
local = "~/projects/my-zsh-plugin"

[plugins.work-tools]
local = "/opt/company/shell-tools"
```

--------------------------------

### Configure Oh My Zsh in ~/.zshrc

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Examples.md

Set the `ZSH` environment variable and evaluate Sheldon's source in your `~/.zshrc` file to integrate Oh My Zsh.

```sh
# ~/.zshrc

export ZSH="$HOME/.local/share/sheldon/repos/github.com/ohmyzsh/ohmyzsh"

# Oh My Zsh settings here

eval "$(sheldon source)"

```

--------------------------------

### Add Local Plugin Source

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Configuration.md

Configures a plugin to use a local directory path as its source. Tildes are expanded. Alternatively, use the `sheldon add --local` command.

```toml
[plugins.example]
local = "~/Downloads/plugin"
```

```sh
sheldon add example --local '~/Downloads/plugin'
```

--------------------------------

### Basic Plugin Configuration

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Configuration.md

Defines a plugin named 'base16' and specifies its GitHub repository. This is a fundamental TOML structure for adding plugins.

```toml
# ~/.config/sheldon/plugins.toml

#           ┌─ Unique name for the plugin
#        ┌──┴─┐
[plugins.base16]
github = "chriskempson/base16-shell"
#         └─────┬────┘ └─────┬────┘
#               │            └─ GitHub repository name
#               └─ GitHub user or organization
```

--------------------------------

### Conditionally Load Plugins with Profiles

Source: https://context7.com/rossmacarthur/sheldon/llms.txt

Use the `profiles` option to load plugins only when a specific profile is active. Plugins without this option are always loaded.

```toml
[plugins.work-tools]
github = "myorg/work-tools"
profiles = ["work"]

[plugins.personal-tools]
github = "myname/personal-dotfiles"
profiles = ["home", "personal"]

[plugins.always-loaded]
github = "zsh-users/zsh-autosuggestions"
# no profiles = loaded in all profiles
```

--------------------------------

### Configure Plugin 'use' Option (TOML)

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/README.md

Specify files or globs to use within a plugin's source directory. This is an alternative to using the global 'match' field.

```toml
[plugins.example]
github = "owner/repo"
use = ["*.zsh"]

```

--------------------------------

### Specify Files to Use in Plugin

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Configuration.md

Defines a list of files or globs within a plugin's source directory to be used. If omitted, the global `match` field is used. Alternatively, use the `sheldon add --use` command.

```toml
[plugins.example]
github = "owner/repo"
use = ["*.zsh"]
```

```sh
sheldon add example --github owner/repo --use '*.zsh'
```

--------------------------------

### Generate Sheldon Initialization Script

Source: https://context7.com/rossmacarthur/sheldon/llms.txt

Output the shell script that activates all configured plugins. This script is typically evaluated in your shell's RC file.

```sh
# Typical usage — place this single line in ~/.zshrc or ~/.bashrc

```

```sh
eval "$(sheldon source)"
```

```sh
# Inspect the generated script without evaluating it

```

```sh
sheldon source
```

--------------------------------

### Initialize Sheldon Config

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Command-line-interface.md

Initializes a new Sheldon configuration file. If a config file already exists, this command does nothing.

```sh
sheldon init
```

--------------------------------

### Global Match Configuration (Bash)

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Configuration.md

Define glob patterns for matching plugin files. This is the default configuration for Bash shells.

```toml
match = [
    "{{ name }}.plugin.bash",
    "{{ name }}.plugin.sh",
    "{{ name }}.bash",
    "{{ name }}.sh",
    "*.plugin.bash",
    "*.plugin.sh",
    "*.bash",
    "*.sh"
]
```

--------------------------------

### Set Global Defaults for Plugins

Source: https://context7.com/rossmacarthur/sheldon/llms.txt

Configure global defaults for `shell`, `match`, and `apply` that affect all plugins unless overridden. The `shell` key determines available templates and match patterns.

```toml
# ~/.config/sheldon/plugins.toml

shell = "zsh"

# Custom global match order — prefer .zsh files over .sh
match = [
    "{{ name }}.plugin.zsh",
    "{{ name }}.zsh",
    "*.plugin.zsh",
    "*.zsh",
    "*.sh"
]

# Apply both "source" and "fpath" to all plugins by default
apply = ["source", "fpath"]

[plugins.zsh-autosuggestions]
github = "zsh-users/zsh-autosuggestions"
# inherits global apply = ["source", "fpath"]

[plugins.override-plugin]
github = "owner/repo"
apply = ["PATH"]   # overrides global apply for this plugin only
```

--------------------------------

### Initialize Sheldon in Shell Configuration

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Introduction.md

Add this line to your ~/.zshrc or ~/.bashrc to enable Sheldon's plugin management.

```shell
eval "$(sheldon source)"
```

--------------------------------

### Plugin option: apply

Source: https://context7.com/rossmacarthur/sheldon/llms.txt

Chooses which templates are applied to a plugin, overriding the global `apply` list. Determines how the plugin is activated.

```toml
# Add plugin directory to PATH and also source its files
[plugins.autojump]
github = "wting/autojump"
apply = ["PATH", "source"]

# Only add to PATH — do not source any files
[plugins.bin-plugin]
github = "owner/bin-only-plugin"
apply = ["PATH"]
```

--------------------------------

### Initialize Sheldon Configuration for Bash

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Getting-started.md

Use this command to initialize the Sheldon configuration file for Bash shell.

```sh
sheldon init --shell bash
```

--------------------------------

### Add Plugin to Sheldon Configuration (TOML)

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Getting-started.md

Append this TOML snippet to your plugins.toml file to add the base16-shell plugin.

```toml
# ~/.config/sheldon/plugins.toml

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

--------------------------------

### Apply Built-in Templates to Plugins

Source: https://context7.com/rossmacarthur/sheldon/llms.txt

Control how plugin directories and files are activated using built-in templates like `source`, `PATH`, `path`, and `fpath`.

```toml
# ~/.config/sheldon/plugins.toml

# source template (default) — sources every matched file
[plugins.zsh-syntax-highlighting]
github = "zsh-users/zsh-syntax-highlighting"
apply = ["source"]

# PATH template — makes executables in the plugin dir available
[plugins.diff-so-fancy]
github = "so-fancy/diff-so-fancy"
apply = ["PATH"]

# fpath template — registers Zsh completion functions without sourcing
[plugins.zsh-completions]
github = "zsh-users/zsh-completions"
apply = ["fpath"]

# Combined: expose binaries AND source the init script
[plugins.autojump]
github = "wting/autojump"
apply = ["PATH", "source"]
```

--------------------------------

### Initialize Sheldon Configuration for Zsh

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Getting-started.md

Use this command to initialize the Sheldon configuration file for Zsh shell.

```sh
sheldon init --shell zsh
```

--------------------------------

### Specify Templates to Apply to Plugin

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Configuration.md

Defines a list of template names to apply to the plugin, defaulting to the global `apply` field. Alternatively, use the `sheldon add --apply` command.

```toml
[plugins.example]
github = "owner/repo"
apply = ["source", "PATH"]
```

```sh
sheldon add example --github owner/repo --apply source PATH
```

--------------------------------

### TOML Plugin Configuration with Profiles

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/RELEASES.md

Configure a plugin to be applicable to specific profiles using the `profiles` key in TOML. This ensures the plugin is only included when Sheldon is run with a matching profile.

```toml
[plugins.example]
github = "owner/repo"
profiles = ["<name>"]
```

--------------------------------

### Force Reinstall Plugin Sources

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Command-line-interface.md

Forces a reinstall of all plugin sources and regenerates the lock file. Use the `--reinstall` flag to ensure all sources are downloaded again.

```sh
sheldon lock --reinstall
```

--------------------------------

### Add powerlevel10k plugin using sheldon command

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Examples.md

Automatically add the `powerlevel10k` plugin using the `sheldon add` command.

```sh
sheldon add powerlevel10k --github romkatv/powerlevel10k

```

--------------------------------

### Add zsh-syntax-highlighting plugin to Sheldon config

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Examples.md

Add the `zsh-syntax-highlighting` plugin to your Sheldon configuration.

```toml
[plugins.zsh-syntax-highlighting]
github = "zsh-users/zsh-syntax-highlighting"

```

--------------------------------

### Add powerlevel10k plugin to Sheldon config

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Examples.md

Add the `powerlevel10k` plugin to your Sheldon configuration.

```toml
[plugins.powerlevel10k]
github = "romkatv/powerlevel10k"

```

--------------------------------

### Add Pure Plugin (CLI)

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Examples.md

Add the pure plugin to your Sheldon config file using the CLI, specifying the use of specific files.

```sh
sheldon add pure --github sindresorhus/pure --use async.zsh pure.zsh

```

--------------------------------

### Add Pure Plugin (TOML)

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Examples.md

Add the pure plugin to your Sheldon config file using TOML, specifying the use of specific files.

```toml
[plugins.pure]
github = "sindresorhus/pure"
use = ["async.zsh", "pure.zsh"]

```

--------------------------------

### Global Match Configuration (Zsh)

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Configuration.md

Define glob patterns for matching plugin files. This is the default configuration for Zsh shells.

```toml
match = [
    "{{ name }}.plugin.zsh",
    "{{ name }}.zsh",
    "{{ name }}.sh",
    "{{ name }}.zsh-theme",
    "*.plugin.zsh",
    "*.zsh",
    "*.sh",
    "*.zsh-theme"
]
```

--------------------------------

### Specify Git Protocol (SSH)

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Configuration.md

Configures a GitHub or Gist source to use SSH for cloning instead of HTTPS. The `proto` field can be 'git', 'https', or 'ssh'. For plain Git sources, specify the URL with 'git://' or 'ssh://'.

```toml
[plugins.example]
github = "owner/repo"
proto = "ssh"
```

```toml
[plugins.example]
git = "ssh://git@github.com/owner/repo"
```

--------------------------------

### Add Spaceship Prompt Plugin (CLI)

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Examples.md

Add the spaceship prompt plugin to your Sheldon config file using the CLI.

```sh
sheldon add spaceship --github spaceship-prompt/spaceship-prompt

```

--------------------------------

### Add Git Plugin Source

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Configuration.md

Configures a plugin to use a generic Git repository URL as its source. Alternatively, use the `sheldon add --git` command.

```toml
[plugins.example]
git = "https://github.com/owner/repo"
```

```sh
sheldon add example --git https://github.com/owner/repo
```

--------------------------------

### Initialize Sheldon for Fish Shell

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/RELEASES.md

Initialize Sheldon to use the Fish shell. This adjusts global matches and templates for Fish compatibility.

```sh
sheldon init --shell fish
```

--------------------------------

### Add Spaceship Prompt Plugin (TOML)

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Examples.md

Add the spaceship prompt plugin to your Sheldon config file using TOML.

```toml
[plugins.spaceship]
github = "spaceship-prompt/spaceship-prompt"

```

--------------------------------

### Add Plugin to Sheldon using CLI

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Getting-started.md

Use the `sheldon add` command to add a plugin, specifying its name and GitHub repository.

```sh
sheldon add base16 --github chriskempson/base16-shell
```

--------------------------------

### Apply defer template to a plugin

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Examples.md

Apply the custom `defer` template to a specific plugin, such as `zsh-syntax-highlighting`, to enable deferred loading for it.

```toml
[plugins.zsh-syntax-highlighting]
github = "zsh-users/zsh-syntax-highlighting"
apply = ["defer"]

```

--------------------------------

### Declare Remote source plugin

Source: https://context7.com/rossmacarthur/sheldon/llms.txt

Declares a plugin from a single remote file URL. The specified URL will be downloaded by Sheldon.

```toml
[plugins.z]
remote = "https://github.com/rupa/z/raw/master/z.sh"
```

--------------------------------

### Add GitHub Plugin Source

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Configuration.md

Configures a plugin to use a GitHub repository as its source. Alternatively, use the `sheldon add --github` command.

```toml
[plugins.example]
github = "owner/repo"
```

```sh
sheldon add example --github owner/repo
```

--------------------------------

### Define Inline plugin

Source: https://context7.com/rossmacarthur/sheldon/llms.txt

Defines a plugin using raw inline shell code directly within the config file. No cloning or downloading is required.

```toml
[plugins.greeting]
inline = 'echo "Welcome back, $USER!"'

[plugins.helpers]
inline = '''
mkcd() { mkdir -p "$1" && cd "$1"; }
up() { cd $(printf "%0.s../" $(seq 1 $1)); }
'''
```

--------------------------------

### Add blackbox plugin using sheldon command

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Examples.md

Automatically add the `blackbox` plugin using the `sheldon add` command.

```sh
sheldon add blackbox --github StackExchange/blackbox

```

--------------------------------

### Configure Plugin Hooks in TOML

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/RELEASES.md

Specify arbitrary hooks for a plugin in TOML configuration. The 'post' hook is executed after the plugin is sourced.

```toml
[plugins.enhancd]
github = "b4b4r07/enhancd"

[plugins.enhancd.hooks]
post = 'export ENHANCD_HOOK_AFTER_CD = "ls"'
```

--------------------------------

### Add autojump plugin to Sheldon config

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Examples.md

Configure the `autojump` plugin in Sheldon, specifying the directory and applying `PATH` and `source` templates.

```toml
[plugins.autojump]
github = "wting/autojump"
dir = "bin"
apply = ["PATH", "source"]

```

--------------------------------

### Add Remote Plugin Source

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Configuration.md

Configures a plugin to use a remote file URL as its source. Alternatively, use the `sheldon add --remote` command.

```toml
[plugins.example]
remote = "https://github.com/owner/repo/raw/branch/plugin.zsh"
```

```sh
sheldon add example --remote https://github.com/owner/repo/raw/branch/plugin.zsh
```

--------------------------------

### Add ohmyzsh plugin to Sheldon config

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Examples.md

Add the `ohmyzsh` plugin to your Sheldon configuration file.

```toml
[plugins.oh-my-zsh]
github = "ohmyzsh/ohmyzsh"

```

--------------------------------

### Add zsh-syntax-highlighting plugin using sheldon command

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Examples.md

Automatically add the `zsh-syntax-highlighting` plugin using the `sheldon add` command.

```sh
sheldon add zsh-syntax-highlighting --github zsh-users/zsh-syntax-highlighting

```

--------------------------------

### Declare Generic Git plugin

Source: https://context7.com/rossmacarthur/sheldon/llms.txt

Declares a plugin from any Git URL, including SSH URLs. The `git` field accepts any clonable URL.

```toml
[plugins.custom-git]
git = "https://gitlab.com/owner/repo.git"

# SSH protocol
[plugins.ssh-plugin]
git = "ssh://git@github.com/owner/repo"
```

--------------------------------

### Add z.lua plugin using sheldon command

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Examples.md

Automatically add the `z.lua` plugin using the `sheldon add` command.

```sh
sheldon add z.lua --github skywind3000/z.lua

```

--------------------------------

### Add base16 plugin using sheldon command

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Examples.md

Automatically add the `base16` plugin using the `sheldon add` command.

```sh
sheldon add base16 --github chriskempson/base16-shell

```

--------------------------------

### Define Custom Templates with Upon

Source: https://context7.com/rossmacarthur/sheldon/llms.txt

Define or override templates using the `upon` templating engine in the `[templates]` table. Variables like `{{ name }}`, `{{ dir }}`, and `{{ file }}` are available.

```toml
# ~/.config/sheldon/plugins.toml

[templates]
# Override PATH to append instead of prepend
PATH = 'export PATH="$PATH:{{ dir }}"'

# Deferred loading via zsh-defer (add zsh-defer plugin BEFORE this template is used)
defer = '{{ hooks?.pre | nl }}{% for file in files %}zsh-defer source "{{ file }}"
{% endfor %}{{ hooks?.post | nl }}'

# Custom template that both sources files and exports a variable
source-with-env = '{% for file in files %}export {{ name | upcase }}_DIR="{{ dir }}"
source "{{ file }}"
{% endfor %}'

# Plugin using the defer template
[plugins.zsh-defer]
github = "romkatv/zsh-defer"
apply = ["source"]

[plugins.zsh-syntax-highlighting]
github = "zsh-users/zsh-syntax-highlighting"
apply = ["defer"]
```

--------------------------------

### Add blackbox plugin to Sheldon config

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Examples.md

Add the `blackbox` plugin to your Sheldon configuration.

```toml
[plugins.blackbox]
github = "StackExchange/blackbox"

```

--------------------------------

### Add enhancd plugin using sheldon command

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Examples.md

Automatically add the `enhancd` plugin using the `sheldon add` command.

```sh
sheldon add enhancd --github b4b4r07/enhancd

```

--------------------------------

### Add autojump plugin using sheldon command

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Examples.md

Automatically add the `autojump` plugin using the `sheldon add` command, specifying `--dir` and `--apply` options.

```sh
sheldon add autojump --github wting/autojump --dir bin --apply PATH source

```

--------------------------------

### Add z.lua plugin to Sheldon config

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Examples.md

Add the `z.lua` plugin to your Sheldon configuration.

```toml
[plugins."z.lua"]
github = "skywind3000/z.lua"

```

--------------------------------

### Declare GitHub Gist plugin

Source: https://context7.com/rossmacarthur/sheldon/llms.txt

Declares a plugin sourced from a GitHub Gist using its hash. Can optionally include the username prefix.

```toml
[plugins.my-gist-plugin]
gist = "579d02802b1cc17baed07753d09f5009"

# With username prefix
[plugins.other-gist]
gist = "someuser/579d02802b1cc17baed07753d09f5009"
```

--------------------------------

### Declare GitHub plugin

Source: https://context7.com/rossmacarthur/sheldon/llms.txt

Defines a plugin from a GitHub repository. Supports pinning to branches, tags, or commits, and cloning via HTTPS or SSH.

```toml
# ~/.config/sheldon/plugins.toml

shell = "zsh"

# Basic GitHub plugin — auto-detects *.plugin.zsh files
[plugins.zsh-syntax-highlighting]
github = "zsh-users/zsh-syntax-highlighting"

# Pinned to a specific tag
[plugins.fzf]
github = "junegunn/fzf"
tag = "0.54.0"

# Pinned to a branch
[plugins.my-plugin]
github = "owner/repo"
branch = "develop"

# Pinned to a specific commit
[plugins.another-plugin]
github = "owner/repo"
rev = "abc1234def5678"

# Clone via SSH (requires SSH agent for private repos)
[plugins.private-repo]
github = "myorg/private-plugin"
proto = "ssh"
```

--------------------------------

### Update Plugin Sources

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Command-line-interface.md

Updates all plugin sources and regenerates the lock file. Use the `--update` flag to fetch the latest versions of all plugin sources.

```sh
sheldon lock --update
```

--------------------------------

### Add enhancd plugin to Sheldon config

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Examples.md

Add the `enhancd` plugin to your Sheldon configuration.

```toml
[plugins.enhancd]
github = "b4b4r07/enhancd"

```

--------------------------------

### Add base16 plugin to Sheldon config

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Examples.md

Add the `base16` plugin to your Sheldon configuration.

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

```

--------------------------------

### Add Gist Plugin Source

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Configuration.md

Configures a plugin to use a GitHub Gist as its source. Alternatively, use the `sheldon add --gist` command.

```toml
[plugins.example]
gist = "579d02802b1cc17baed07753d09f5009"
```

```sh
sheldon add example --gist 579d02802b1cc17baed07753d09f5009
```

--------------------------------

### Add Plugin to Configuration

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/README.md

Adds a plugin to the Sheldon configuration file. This can be done manually by editing `plugins.toml` or using the `add` command.

```toml
# ~/.config/sheldon/plugins.toml

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

```sh
sheldon add base16 --github chriskempson/base16-shell
```

--------------------------------

### Add GitHub Repository as Plugin Source

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Command-line-interface.md

Adds a new GitHub repository as a plugin source to the Sheldon configuration file. This command only edits the config file.

```sh
sheldon add my-repo --git https://github.com/owner/repo.git
```

--------------------------------

### Define Inline Plugin (TOML)

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/README.md

Define an inline plugin by setting the 'inline' field with raw shell code.

```toml
[plugins.example]
inline = 'example() { echo "Just an example of inline shell code" }'

```

--------------------------------

### Activate Sheldon Profile

Source: https://context7.com/rossmacarthur/sheldon/llms.txt

Activate a specific profile for Sheldon either at shell startup or via a CLI flag.

```sh
# Activate the "work" profile at shell startup
SHELDON_PROFILE=work eval "$(sheldon source)"

# Or pass it as a CLI flag
sheldon --profile work source
```

--------------------------------

### Add a Sheldon Plugin

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/RELEASES.md

Use this command to add a new plugin to your Sheldon configuration. It specifies the plugin's name, its GitHub repository, and a specific tag.

```sh
sheldon add example --github owner/repo --tag v0.1.0
```

--------------------------------

### Initialize Sheldon Config for Specific Shell

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Command-line-interface.md

Initializes a new Sheldon configuration file, specifying the target shell. If a config file already exists, this command does nothing.

```sh
sheldon init --shell bash
```

```sh
sheldon init --shell zsh
```

--------------------------------

### Add zsh-defer plugin to Sheldon config

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Examples.md

Add `zsh-defer` as a plugin to your Sheldon configuration. This should be placed before any plugins that will use the `defer` template.

```toml
[plugins.zsh-defer]
github = "romkatv/zsh-defer"

```

--------------------------------

### Add ohmyzsh plugin using sheldon command

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/Examples.md

Automatically add the `ohmyzsh` plugin to your Sheldon configuration using the `sheldon add` command.

```sh
sheldon add oh-my-zsh --github "ohmyzsh/ohmyzsh"

```

--------------------------------

### Migrate Sheldon Directories

Source: https://github.com/rossmacarthur/sheldon/blob/trunk/docs/src/RELEASES.md

Commands to migrate Sheldon's default directories to new locations. This is necessary for versions that changed the default root and clone directories.

```sh
mv ~/.zsh ~/.sheldon
mv ~/.sheldon/repositories ~/.sheldon/repos
```