🛠 Commands

Updates

To update and recompile 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 <plugin-name>. 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.

Self-update & compile:

zi self-update

Update plugins and snippets:

zi update --all
zi update --reset
zi update --quiet

Update plugins or snippets:

zi update --plugins
zi update --snippets

Update specific plugins. Default is GitHub but can specify any with ice from'…':

zi update <user>/<repo>

Plugin parallel update plugins:

zi update --parallel

Increase the number of jobs in a concurrent set to 40

zi update --parallel 40

Compinit

note

Calling compinit once is a huge performance gain, for example, shell startup time with double compinit: 0.980 sec, with cdreplay and single compinit: 0.156 sec.

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 the 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.

~/.zshrc
source ~/.zi/bin/zi.zsh

zi 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 compinit
compinit

zi 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')

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 the compinit call in the atinit or atload hook of the last related plugin with the use of the helper functions zicompinit,zicdreplay & zicdclear as shown below:

~/.zshrc
source ~/.zi/bin/zi.zsh

# Load using the for-syntax
zi 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.zsh
zi snippet OMZP::git
zi cdclear -q # <- forget completions provided by Git plugin

zi load "some/plugin"

(…)

zi load "other/plugin"

autoload -Uz compinit
compinit
zi cdreplay -q # <- execute compdefs provided by rest of plugins
zi 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

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

Completions management

Command	Description
`clist` `columns` or `completions` `columns`	List 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.
`csearch`	Search for available completions from any plugin.
`compinit`	Refresh installed completions.
`cclear`	Clear stray and improper completions.
`cdlist`	Show compdef replay list.
`cdreplay` `-q`	Replay compdefs (to be done after compinit). `-q` – quiet.
`cdclear` `-q`	Clear compdef replay list. `-q` – quiet.

Tracking of the active session

Command	Description
`dtrace, dstart`	Start investigating what's going on in the session.
`dstop`	Stop investigating what's going on in the session.
`dunload`	Revert changes recorded between `dstart` and `dstop`.
`dreport`	Report what was going on in the session.
`dclear`	Clear report of what was going on in the session.

Reports and statistics

Command	Description
`times` `-s` `-m` `-a`	Statistics on plugin load times, sorted in order of loading. `-s` – use seconds instead of milliseconds. `-m` – show plugin loading moments and `-a` both.
`zstatus`	Overall ZI status.
`report` `'…'` `--all`	Show plugin report. `--all` – do it for all plugins.
`loaded`	Show loaded plugins
`list` `keyword`	Filter loaded plugins with only 'keyword'
`ls`	List snippets in a formatted and colorized manner. Requires tree program.
`status` `'…'` or `URL` `--all`	Git status for plugin or svn status for the snippet. `--all` – do it for all plugins and snippets.
`recently` `time-spec`	Show plugins that changed recently, the argument is e.g. 1 month 2 days.
`bindkeys`	Lists bindkeys set up by each plugin.

Compiling

Command	Description
`compile` `'…'` `--all`	Compile plugin. `--all` – compile all plugins.
`uncompile` `'…'` `--all`	Remove compiled version of the plugin. `--all` – do it for all plugins.
`compiled`	List plugins that are compiled.

Other commands

Command	Description
`self-update`	Updates and compiles Zi.
`update` `-q` `-r` `'…'` or `--all`	Update 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` `--all`	Remove 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 '…'` `URL`	Fetch 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`.
`module`	Manage binary Zsh module shipped with ZI, see `zi module help`.
`add-fpath` `fpath` `-f` `--front` `'…'` `sub-directory`	Adds given plugin (not yet snippet) directory to `$fpath`. If the second argument is given, it is appended to the directory path. ³
`run` `-l` `plugin` `{command}`	Runs the given command in the given plugin's directory. ⁴

Help & manual

Command	Description
`-h, help`	Usage information.
`man`	Manual.

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

There's also light-mode ice which can be used to induce the no-investigating (i.e.: light) loading, regardless of the command used. ↩
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. ↩
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. ↩
If the option -l will be given then the plugin should be skipped – the option will cause the previous plugin to be reused. ↩

Updates​

Compinit​

Calling compinit without turbo mode​

Calling compinit with turbo mode​

Ignoring compdefs​

Loading and unloading​

Completions management​

Tracking of the active session​

Reports and statistics​

Compiling​

Other commands​

Help & manual​

Commands available using ^TAB completion​

Footnotes​