Package/Tool zsh-plugin

A command-line tool to generate new Zsh plugins.

This tool scaffolds Zsh plugins with best practices built-in, including function tracking for clean unloading, optional alias support, autoloaded functions, and CI/CD workflows for shellcheck and shellspec. Choose from minimal, simple, or complete templates to match your plugin's complexity.

Install

❱ cargo install zsh-plugin

❱ zsh-plugin --help
A command-line tool to generate new Zsh plugins.

Usage: zsh-plugin [OPTIONS] <COMMAND>

Commands:
  init  Initialize a new Zsh plugin structure
  help  Print this message or the help of the given subcommand(s)

Options:
  -v, --verbose...  Increase logging verbosity
  -q, --quiet...    Decrease logging verbosity
  -h, --help        Print help
  -V, --version     Print version

Command init

❯ zsh-plugin init --help                                                                              
Initialize a new Zsh plugin structure

The resulting plugin contains the following content.

...

Usage: zsh-plugin init [OPTIONS] --github-user <GITHUB_USER> <NAME>

Arguments:
  <NAME>
          The name of the new plugin.
          
          Plugin names are restricted to a "safe" subset corresponding to the following regular expression `\[a-zA-Z\]\[a-zA-Z0-9_-\]``.

Options:
  -f, --force
          Force over-writing of existing files.
          
          If not set, the tool will fail when target directories or files exist.

  -v, --verbose...
          Increase logging verbosity.

  -q, --quiet...
          Decrease logging verbosity.

  -t, --template <TEMPLATE>
          A pre-configured template to use.

          Possible values:
          - minimal:  Minimal plugin structure
          - simple:   Simple in-line function plugin structure
          - complete: Complete plugin structure with all optional components included

  -a, --add-bin-dir
          Add a 'bin' sub-directory for plugin-specific binaries/scripts.

  -w, --add-bash-wrapper
          Add a Bash wrapper file to call the plugin from Bash scripts.

  -A, --no-aliases
          Do not include support for tracking aliases defined by the plugin.

  -C, --no-shell-check
          Do not include support for linting using shellcheck.
          
          Add linting steps to the Makefile and shell.yml (Github Action) files.

  -D, --no-shell-doc
          Do not include support for documentation generation with shdoc.
          
          Add documentation steps to the Makefile.

  -F, --no-functions-dir
          Do not include a 'functions' sub-directory and example file.

  -G, --no-git-init
          Do not initialize Git in the generated plugin.
          
          By default the created plugin directory is also initialized as a new Git repository. This option also stops creation a generic .gitignore file.

  -H, --no-github-dir
          Do not include a '.github' sub-directory.
          
          By default the created plugin includes a .github/worflows directory with a file shell.yml that defines a Github Actions workflow. Note that if both no-shell-check and no-shell_test options are set the workflow file is not created as it would effectively be a no-op.

  -R, --no-readme
          Do not include a README file.

  -S, --no-shell-spec
          Do not include support for testing using shellspec.
          
          Add testing steps to the Makefile and shell.yml (Github Action) files.

  -u, --github-user <GITHUB_USER>
          Set the name of the Github user for inclusion in README.md
          
          [env: USER=simon]

  -Z, --use-plain-plugins
          Do not use the `zplugins` plugin manager for support functions.

  -d, --description <DESCRIPTION>
          Short description of the plugin.
          
          This description is added to the plugin source and README.md files.

  -h, --help
          Print help (see a summary with '-h')

Results

Initialize a new Zsh plugin structure in the directory zsh-NAME-plugin. he resulting plugin contains the following content.

1. A file NAME.plugin.zsh which consists of the main plugin lifecycle functions.

   1. A function NAME_plugin_init is included with comments to show how to save environment variables, add aliases, and add to either path or fpath.
   2. A function NAME_plugin_unload is included with comments to demonstrate custom clean-up actions.
   3. An example global variable NAME_EXAMPLE set during source time.
   4. A call during source time to set any dependencies the plugin wishes to declare.

2. If the option add-bash-wrapper is defined, a file NAME.bash is included which provides an entry point for Bash users to load the plugin.

3. A directory .github/workflows and a Github Actions script named shell.yml to automate shellcheck and shellspec. Generation will be skipped if the no-github-dir option is checked or both the options no-shell-check and no-shell-spec are set as the workflow then has nothing to do.

4. A directory functions with an example autoloaded function named NAME_example. Generation will be skipped if the no-functions-dir option is set.

5. If the option add-bin-dir is set an empty bin directory for plugin specific binaries is created.

6. A file .gitignore. Generation will be skipped if both the options no-shell-check and no-shell-specare set.

7. A directory doc. Generation will be skipped if the no-shell-doc option is set.

8. A file Makefile for GNU Make. Generation will be skipped if the options no-shell-check, no-shell-doc, and no-shell-spec are all true.

9. A file README.md containing only a basic skeleton. Generation will be skipped if the no-readme is set.

Templates

Rather than setting all options manually, three templates are provided with pre-defined selection of settings. These are described in the table below.

Feature / Template	minimal	simple	complete
add-bin-dir	false	false	true
add-bash-wrapper	false	false	true
no-aliases	true	false	false
no-functions-dir	true	true	false
no-git-init	false	false	false
no-github-dir	true	true	false
no-readme	true	false	false
no-shell-check	true	false	false
no-shell-doc	true	false	false
no-shell-spec	true	false	false

Example

Given the following execution:

❱ zsh-plugin init containers --add-bash-wrapper --add-bin-dir
........ Done

A complete plugin, with all possible content, is created as follows:

─ zsh-containers-plugin
  ├─ .github/                # unless no-github-dir OR
  │  └─ workflows/           #   no-shell-check AND no-shell-check AND no-shell-spec
  │     └─ shell.yml
  ├─ bin/                    # when   add-bin-dir
  │  └─ .gitkeep
  ├─ functions/              # unless no-functions-dir
  │  └─ containers_example
  ├─ .git                    # unless no-git-init
  ├─ .gitignore              # unless no-git-init
  ├─ Makefile                # unless no-shell-check AND no-shell-check AND no-shell-spec
  ├─ mkdoc.zsh               # unless no-shell-doc
  ├─ README.md
  ├─ containers.bash         # when   add-bash-wrapper
  └─ containers.plugin.zsh  

License(s)

The contents of this repository are made available under the following licenses:

Apache-2.0

Copyright 2025 Simon Johnston <johnstonskj@gmail.com>

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

See the enclosed file LICENSE-Apache.

MIT

Copyright 2025 Simon Johnston <johnstonskj@gmail.com>

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the “Software”), to deal
in the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

See the enclosed file LICENSE-MIT.

Contributions

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

For information on contributing to this project, see the following.

1. Project Code of Conduct.
2. Project Contribution Guidelines.
3. Project TODO Items in Issues.
4. Repository Change Log.