ANTIDOTE(1)

NAME
antidote - the cure to slow zsh plugin management

SYNOPSIS

antidote [-v | --version] [-h | --help] [--diagnostics] <command> [<args> ...]

DESCRIPTION

antidote is a Zsh plugin manager made from the ground up thinking about performance.

It is fast because it can do things concurrently, and generates an ultra-fast static plugin file that you can easily load from your Zsh config.

It is written natively in Zsh, is well tested, and picks up where Antigen and Antibody left off.

OPTIONS

-h, --help
    Show context-sensitive help for antidote.

-v, --version
    Show currently installed antidote version.

--diagnostics
    Show antidote and system diagnostics.

COMMANDS

help
    Show documentation

load
    Statically source all bundles from the plugins file

bundle
    Clone bundle(s) and generate the static load script

install
    Clone a new bundle and add it to your plugins file

update
    Update antidote and its cloned bundles

purge
    Remove a cloned bundle

home
    Print where antidote is cloning bundles

list
    List cloned bundles

path
    Print the path of a cloned bundle

snapshot
    Save, restore, or list bundle snapshots

init
    Initialize the shell for dynamic bundles

EXAMPLES

  A Simple Config

Create a .zsh_plugins.txt file with a list of the plugins you want:

    # ${ZDOTDIR:-$HOME}/.zsh_plugins.txt
    zsh-users/zsh-syntax-highlighting
    zsh-users/zsh-history-substring-search
    zsh-users/zsh-autosuggestions

Now, simply load your newly created static plugins file in your .zshrc.

    # ${ZDOTDIR:-$HOME}/.zshrc
    source /path/to/antidote/antidote.zsh
    antidote load

  A More Advanced Config

Your .zsh_plugins.txt file supports annotations. Annotations tell antidote how to do things like load plugins from alternate paths. This lets you use plugins from popular frameworks like Oh-My-Zsh:

    # ${ZDOTDIR:-$HOME}/.zsh_plugins.txt
    ohmyzsh/ohmyzsh path:lib
    ohmyzsh/ohmyzsh path:plugins/git
    ohmyzsh/ohmyzsh path:plugins/magic-enter
    etc...

  Dynamic Bundling

Users familiar with legacy plugin managers like Antigen might prefer to use dynamic bundling. With dynamic bundling you sacrifice some performance to avoid having separate plugin files. To use dynamic bundling, we need to change how antidote bundle handles your plugins. We do this by sourcing the output from antidote init.

An example config might look like this:

    source /path/to/antidote/antidote.zsh
    source <(antidote init)
    antidote bundle zsh-users/zsh-autosuggestions
    antidote bundle ohmyzsh/ohmyzsh path:lib
    antidote bundle ohmyzsh/ohmyzsh path:plugins/git

Instead of calling antidote bundle over and over, you might prefer to load bundles with a HEREDOC.

    source /path/to/antidote/antidote.zsh
    source <(antidote init)
    antidote bundle <<EOBUNDLES
        zsh-users/zsh-syntax-highlighting         # regular plugins
        ohmyzsh/ohmyzsh path:lib                  # directories
        ohmyzsh/ohmyzsh path:plugins/magic-enter  # frameworks
        https://github.com/zsh-users/zsh-history-substring-search  # URLs
    EOBUNDLES

  Installation

To install antidote you can clone it with git:

    git clone --depth=1 https://github.com/mattmc3/antidote.git ${ZDOTDIR:-$HOME}/.antidote

Then, simply add the following snippet to your .zshrc:

    source ${ZDOTDIR:-$HOME}/.antidote/antidote.zsh
    antidote load

CUSTOMIZATION

The location where antidote clones repositories can be customized by setting $ANTIDOTE_HOME:

    ANTIDOTE_HOME=/path/to/my/repos

The bundle directory naming style in ANTIDOTE_HOME can be controlled with the following zstyle:

    zstyle ':antidote:bundle' path-style full     # github.com/owner/repo (default)
    zstyle ':antidote:bundle' path-style short    # owner/repo
    zstyle ':antidote:bundle' path-style escaped  # https-COLON--SLASH--SLASH-github.com-SLASH-owner-SLASH-repo

The default bundle file is ${ZDOTDIR:-$HOME}/.zsh_plugins.txt. This can be overridden with the following zstyle:

    zstyle ':antidote:bundle' file /path/to/my/bundle_file.txt

The default static file is ${ZDOTDIR:-$HOME}/.zsh_plugins.zsh. This can be overridden with the following zstyle:

    zstyle ':antidote:static' file /path/to/my/static_file.zsh

The default options used by romkatv/zsh-defer can be changed with the following zstyle:

    zstyle ':antidote:bundle:*' defer-options '-a'
    zstyle ':antidote:bundle:foo/bar' defer-options '-p'

Bundles can be Zsh compiled with the following zstyle:

    zstyle ':antidote:bundle:*' zcompile 'yes'

Or, if you only want to zcompile specific bundles, you can set those individually:

    zstyle ':antidote:bundle:*' zcompile 'yes'
    zstyle ':antidote:bundle:zsh-users/zsh-syntax-highlighting' zcompile 'no'

The static file can be Zsh compiled with the following zstyle:

    zstyle ':antidote:static' zcompile 'yes'

Or, to Zsh compile everything, static file and all bundles:

    zstyle ':antidote:*' zcompile 'yes'

By default, antidote appends to the end of your $fpath. This is highly recommended, however if you really want to change that behavior, there’s a zstyle for that:

    zstyle ':antidote:fpath' rule 'prepend'

By default, antidote uses romkatv/zsh-defer for deferred plugins. If there’s a fork you’d prefer to use, you can specify that with this zstyle:

    zstyle ':antidote:defer' bundle 'getantidote/zsh-defer'

CONTROLLING OUTPUT

Output in antidote can be customized as well.

Colorization of certain output is supported in antidote, and color support detection is controlled by the COLORTERM variable, which modern terminals should set. If you want to override that behavior, setting the following variables can help control that:

NO_COLOR
    Set 'NO_COLOR=1' to disable color in output.

CLICOLOR_FORCE
    Set 'CLICOLOR_FORCE=1' to force color in output. NO_COLOR must be 0 or unset.

Additionally, JSON Lines (JSONL) output is supported for certain commands such as 'antidote list'. If you need JSONL support, look for this flag: -j, --jsonl:: Output in JSONL.

SEE ALSO

For more information, visit

BUGS

See GitHub Issues:

AUTHORS

    • Copyright (c) 2021-2026 Matt McElheny

    • antidote contributors:

LICENSE

MIT