Skip to main content

🛠 Commands

Commands available using ^TAB completion

zi ^TAB
add-fpath              -- Add plugin folder to $fpath
analytics -- Statistics, benchmarks and information
bindkeys -- Lists bindkeys set up by each plugin
cclear -- Clear stray and improper completions
cd -- Go into plugin directory
cdclear -- Clear compdef replay list
cdisable -- Disable completion
cdlist -- Show compdef replay list
cdreplay -- Replay compdefs (to be done after compinit)
cenable -- Enable completion
changes -- View the plugin git log
compile -- Compile plugin (or all plugins if --all passed)
compiled -- Show which plugins are compiled
compinit -- Refresh installed completions
completions clist -- List completions in use
create -- Create plugin (also together with Github repository)
creinstall -- Install completions for plugin
csearch -- Search for available completions from any plugin
cuninstall -- Uninstall completions for plugin
dclear -- Clear report of what was going on in session
delete -- Delete plugin
dreport -- Report what was going on in session
dstart dtrace -- Start tracking what's going on in session
dstop -- Stop tracking what's going on in session
dunload -- Revert changes recorded between dstart and dstop
edit -- Edit plugin's file with $EDITOR
env-whitelist -- Allows to specify names (also patterns) of variables left unchanged during an unload. -v - verbose
glance -- View the plugin source
help -- Usage information
icemods -- Shows ice-modifiers registered by annex
light -- Light load plugin
list -- List loaded plugins
load -- Load plugin
loaded -- Show loaded plugins
ls -- List snippets in formatted and colorized manner
man -- Manpage
module -- Manage binary Zsh module, see 'zi module help' for more info
recall -- Fetch saved ice modifiers and construct 'zi ice ...' command
recently -- Show plugins that changed recently, argument is e.g. 1 month 2 days
report -- Show plugins report (or all plugins if --all passed)
run -- Execute code inside plugin's folder
self-update -- Updates and compiles ❮ ZI
snippet -- Source (or add to PATH with --command) local or remote file (-f: force - do not use cache)
srv -- Control a service, command can be: stop,start,restart,next,quit; next'' moves the service to another Zshell
status -- Git status for plugin (or all plugins if --all passed)
stress -- Test the plugin for compatibility with set of options
subcmds -- Shows subcommands registered by annex
times -- Statistics on plugin loading times
uncompile -- Remove compiled version of plugin (or of all plugins if --all passed)
unload -- Unload plugin
update -- Git update plugin (or all plugins and snippets if --all passed)
zstatus -- Check and provide status information

Updates

To update Zi run zi self-update in the command line. To update all plugins and snippets, issue zi update. To update all in parallel (up to 40 at the time) zi update -p 40 If you wish to update only a single plugin/snippet instead issue zi update NAME_OF_PLUGIN. A list of commits will be shown if any.

Some plugins require acting each time they're updated. One way you can do this is by using the atpull'…' ice modifier. For example, writing zi ice atpull'./configure' before loading a plugin will execute ./configure after a successful update. Refer to Ice Modifiers for more information.

The ice modifiers for any plugin or snippet are stored in their directory in a ._zi subdirectory, hence the plugin doesn't have to be loaded to be correctly updated. There's one other file created there, .zi_lstupd – it holds the log of the new commits pulled-in in the last update.

tip

It is possible to combine system updates with tools like topgrade which will run Zi updates automatically.

Calling compinit without turbo mode

With no turbo mode in use, compinit can be called normally, i.e.: as autoload compinit; compinit. This should be done after loading all plugins and before possibly calling zi cdreplay. The cdreplay subcommand is provided to re-play all caught compdef calls. The compdef calls are used to define a completion for a command. For example, compdef _git git defines that the git command should be completed by a _git function. The compdef function is provided by compinit call.

As it should be called later, after loading all of the plugins, Zi provides its own compdef function that catches (i.e.: records in an array) the arguments of the call, so that the loaded plugins can freely call compdef. Then, the cdreplay (compdef-replay) can be used, after compinit will be called (and the original compdef function will become available), to execute all detected compdef calls.

Summary:

~/.zshrc
source ~/.zi/bin/zi.zshzi load "some/plugin"()compdef _gnu_generic fd  # this will be intercepted by ZI, because as the compinit                         # isn't yet loaded, thus there's no such function `compdef'; yet                         # ZI provides its own `compdef' function which saves the                         # completion-definition for later possible re-run with `zi                         # cdreplay' or `zicdreplay' (the second one can be used in hooks                         # like atload'…', atinit'…', etc.)()zi load "other/plugin"autoload -Uz compinitcompinitzi cdreplay -q      # -q is for quiet; actually, run all the `compdef's saved before                    #`compinit` call (`compinit' declares the `compdef' function, so                    # it cannot be used until `compinit' is run; ZI solves this                    # via intercepting the `compdef'-calls and storing them for later                    # use with `zi cdreplay')

This allows calling compinit once.

tip

Performance gains are huge, for example, shell startup time with double compinit: 0.980 sec, with cdreplay and single compinit: 0.156 sec.

Calling compinit with turbo mode

If you load completions using wait'…' turbo mode then you can add atinit'zicompinit' to the syntax-highlighting plugin (which should be the last one loaded, as their (2 projects, zsh-syntax-highlighting & F-Sy-H) documentation state), or atload'zicompinit' to last completion-related plugin. zicompinit is a function that just runs autoload compinit; compinit, created for convenience.

Alternatively, the zicompinit can be replaced with zicompinit_fast which checks the cached .zcompdump and determines when to regenerate the file. This restricts checking it once a day, as compinit doesn't always need to modify the compdump and compiles mapped to share in the background in multiple shells.

There's also zicdreplay which will replay any caught compdefs so you can also do: atinit'zicompinit; zicdreplay', etc.

It is recommended to run compinit call in atinit or atload hook of the last related plugin with the use of the helper functions zicompinit,zicdreplay & zicdclear as shown below:

Summary of compinit call

~/.zshrc
source ~/.zi/bin/zi.zsh# Load using the for-syntaxzi wait lucid for \    "some/plugin"zi wait lucid for \    "other/plugin"zi wait lucid atload"zicompinit; zicdreplay" blockf for \    zsh-users/zsh-completions

Ignoring compdefs

If you want to ignore compdefs provided by some plugins or snippets, place their load commands before commands loading other plugins or snippets, and issue zi cdclear (or zicdclear, designed to be used in hooks like atload'…'):

source ~/.zi/bin/zi.zshzi snippet OMZP::gitzi cdclear -q # <- forget completions provided by Git pluginzi load "some/plugin"()zi load "other/plugin"autoload -Uz compinitcompinitzi cdreplay -q # <- execute compdefs provided by rest of pluginszi cdlist # look at gathered compdefs

The cdreplay is important if you use plugins like OMZP::kubectl or asdf-vm/asdf because these plugins call compdef.

Following commands are passed to zi … to obtain described effects.

Loading and unloading

CommandDescription
load '…'Load plugin, can also receive absolute local path.
light -b '…'Light plugin load, without reporting/investigating. -b – investigate bindkey-calls only. 1
unload -q '…'Unload plugin loaded with zi load …. -q – quiet.
snippet -f URLSource local (full path) or remote file (URL). -f – don't use cache (force re-download). 2

Completions management

CommandDescription
clist columns or completions columnsList completions in use, with columns completions per line. zi clist 5 will for example print 5 completions per line. Default is 3.
cdisable '…'Disable completion.
cenable '…'Enable completion.
creinstall -q -Q '…'Install completions for the plugin, can also receive absolute local path. -q – quiet. -Q - quiet all.
cuninstall '…'Uninstall completions for the plugin.
csearchSearch for available completions from any plugin.
compinitRefresh installed completions.
cclearClear stray and improper completions.
cdlistShow compdef replay list.
cdreplay -qReplay compdefs (to be done after compinit). -q – quiet.
cdclear -qClear compdef replay list. -q – quiet.

Tracking of the active session

CommandDescription
dtrace, dstartStart investigating what's going on in the session.
dstopStop investigating what's going on in the session.
dunloadRevert changes recorded between dstart and dstop.
dreportReport what was going on in the session.
dclearClear report of what was going on in the session.

Reports and statistics

CommandDescription
times -s -m -aStatistics on plugin load times, sorted in order of loading. -s – use seconds instead of milliseconds. -m – show plugin loading moments and -a both.
zstatusOverall ZI status.
report '…' --allShow plugin report. --all – do it for all plugins.
loadedShow loaded plugins
list keywordFilter loaded plugins with only 'keyword'
lsList snippets in a formatted and colorized manner. Requires tree program.
status '…' or URL --allGit status for plugin or svn status for the snippet. --all – do it for all plugins and snippets.
recently time-specShow plugins that changed recently, the argument is e.g. 1 month 2 days.
bindkeysLists bindkeys set up by each plugin.

Compiling

CommandDescription
compile '…' --allCompile plugin. --all – compile all plugins.
uncompile '…' --allRemove compiled version of the plugin. --all – do it for all plugins.
compiledList plugins that are compiled.

Other commands

CommandDescription
self-updateUpdates and compiles Zi.
update -q -r '…' or --allUpdate all plugins and snippets with --all – for quiet -q – execute git reset --hard or svn revert before pulling changes with -r.
ice '…'Add ice to next command, argument e.g.: from"gitlab".
delete '…' or --clean --allRemove plugin or snippet from disk (good to forget wrongly passed ice-modifiers) --all – delete plugins and snippets that are not loaded with --clean.
cd '…'Jump into the plugin's directory. Also support snippets if fed with URL.
edit '…'Edit plugin's file with set $EDITOR.
glance '…'Look at plugin's source (pygmentize, {,source-}highlight).
stress '…'Test plugin for compatibility with a set of options.
changes '…'View plugin's git log.
create '…'Create plugin (also together with GitHub repository).
srv service-id {command}Control a service, command can be: stop,start,restart,next,quit; next moves the service to another Z shell.
recall '…' URLFetch saved ice modifiers and construct zi ice '…' command.
env-whitelist -v -h {env..}Allows to specify names or patterns of variables left unchanged during an unload – verbose -v – help -h.
moduleManage binary Zsh module shipped with ZI, see zi module help.
add-fpath fpath -f --front '…' sub-directoryAdds given plugin (not yet snippet) directory to $fpath. If the second argument is given, it is appended to the directory path. 3
run -l plugin {command}Runs the given command in the given plugin's directory. 4

Help & Manual

CommandDescription
-h, helpUsage information.
manManual.

  1. The URL can use the following shorthands: PZT:: (Prezto), PZTM:: (Prezto module), OMZ:: (Oh-My-Zsh), OMZP:: (OMZ plugin), OMZL:: (OMZ library), OMZT:: (OMZ theme), e.g.: PZTM::environment, OMZP::git, etc.
  2. There's also light-mode ice which can be used to induce the no-investigating (i.e.: light) loading, regardless of the command used.
  3. If the option -l will be given then the plugin should be skipped – the option will cause the previous plugin to be reused.
  4. The '…' can be an absolute path, i.e.: it's possible to also add regular directories. If the option -f or --front is given, the directory path is prepended instead of appended to $fpath.