Overview
zoxide remembers the folders you visit and lets you jump to one with a short part of its name. After you set it up in your shell with zoxide init, the command z proj takes you to the folder that matches proj best, judged by how often and how recently you went there. It is a smarter cd. This page also answers for z, the command that zoxide init defines in your shell: z is a shell function and not a program on the PATH, so it exists only after the setup line has run.
Background
zoxide is an open-source tool whose manual is in its repository. It keeps a small database in your data folder. The tool tested here is zoxide 0.10.0.
Examples
Print the version:
zoxide --version
Tell it about a folder with zoxide add, then ask for the best match for a word; the answer is a full path, so the start is cut off:
mkdir p && zoxide add "$PWD/p" && zoxide query p | sed "s#$PWD/##"
Print the shell code that sets it up for Bash; reviewed only, because the code changes with each release:
zoxide init bash
Subcommands
zoxide init SHELL prints the code that defines z and zi. zoxide add PATH records a folder. zoxide query WORDS prints the best match. zoxide remove PATH forgets a folder.
Common mistakes
The z command does not exist until you put eval "$(zoxide init bash)" (or the line for your shell) in your shell's startup file. It learns from your visits, so a folder you have never visited is not found: use cd once. A word can match several folders; zi lets you choose with fzf. The database is a file, and removing a deleted folder from it is done with zoxide remove or with zoxide query that skips missing ones.
Portability
The commands are the same on every system. The examples use a throw-away data folder, because the tests run with a clean home folder. The first two examples were executed on zoxide 0.10.0 (see the development guide for the exact check); the setup code is reviewed only.
About upstream zoxide
This is the upstream zoxide tool. It is one program everywhere; what differs is the version.
References
Original explanations, with upstream documentation for further reading. FreeBSD references are comparison material, not a claim of Apple version equivalence.