The Ultimate Guide to Zoxide Commands: Navigating Your Terminal at Light Speed

If you live in the terminal, you know that the cd command is the most frequently used tool in your arsenal. It is also the most inefficient. Typing out full paths, dealing with typos, and remembering complex directory structures is a cognitive drain that slows down development. Enter Zoxide, a smarter cd command inspired by z and autojump. It learns your habits, tracks your most visited directories, and allows you to jump anywhere with just a few keystrokes.

However, many users only scratch the surface by installing it and using the basic z alias. To truly unlock the productivity potential of this Rust-based tool, you need to master the full suite of zoxide commands. This guide will take you deep into the CLI (Command Line Interface) of Zoxide, exploring everything from database manipulation to advanced querying techniques.

Why Master Zoxide Commands?

Zoxide operates on a "frecency" algorithm—a weighted combination of frequency (how often you visit) and recency (how recently you visited). While the tool works like magic out of the box, understanding the specific zoxide commands allows you to:

1. Debug navigation issues: Why is z foo taking me to foobar instead of foo-project?
2. Clean your history: Remove non-existent or sensitive directories from your database.
3. Script your workflow: Use Zoxide's query engine inside Bash or Python scripts.
4. Migrate data: Import history from other tools without starting from scratch.

Let's break down the command structure.

1. Initialization Commands: The Foundation

Before you can jump, you must integrate Zoxide into your shell. This is handled by the init command, which generates the necessary shell script to hook into your prompt.

The Basic Init

The structure is zoxide init <shell>.

This sets up the z alias and the zi interactive command.

The --cmd Flag (The Power Move)

By default, Zoxide uses z. However, muscle memory is hard to break. The most powerful of the initialization zoxide commands involves replacing cd entirely.

When you use --cmd cd, Zoxide replaces the standard cd command.

• Space-Bar Compatibility: It still behaves like cd if you type a valid path.
• Smart Jumping: If the path doesn't exist locally, it queries the database.
• Why do this? This ensures every navigation event is recorded, making the database incredibly accurate over time.

2. Core Navigation Commands

These are the zoxide commands you will execute hundreds of times a day.

The Jump: z

This is the bread and butter. You don't need the full name of the directory.

Zoxide is smart enough to handle fuzzy matching. If you have work-personal and work-business, typing z bus is usually enough to disambiguate.

The Interactive Jump: zi

Sometimes the algorithm isn't enough, or you have five directories named "src". The zi command utilizes fzf (fuzzy finder) to present a selectable list.

This opens an interactive interface showing your top-ranked directories. You can type to filter the list and press Enter to jump. This is often cited as one of the most useful zoxide commands for exploring old projects.

3. Database Management Commands (add and remove)

Zoxide maintains a database file (usually in ~/.local/share/zoxide/db.zo). While it self-heals (removing directories that no longer exist upon failed entry), manual management is sometimes required.

zoxide add

You can manually train the algorithm. This is useful for new projects you haven't visited yet but plan to use frequently.

Using add ensures that the directory is immediately available for jumping, even if you haven't technically cd-ed into it yet.

zoxide remove

If you have a directory you want Zoxide to "forget"—perhaps a secret project or a temporary build folder that creates noise in your autocomplete—you use the remove command.

Pro Tip: You can combine this with specific zoxide commands for interactive removal:

If multiple matches are found, you may need to specify the exact path or use the interactive mode (often handled via flags in advanced setups).

4. The Brain of the Operation: zoxide query

For scripters and power users, zoxide query is the most important command. It exposes the raw logic of the tool without actually changing your directory. This is useful for building custom tools or verifying what Zoxide "thinks" is the best match.

Basic Query

This outputs the absolute path that z foo would jump to. It does not move you; it just prints the string.

Listing Matches (--list / -l)

If you want to see all potential candidates for a keyword:

This returns a list of all directories matching "foo", ordered by rank.

Scoring (--score / -s)

This is crucial for debugging. If you are wondering why Zoxide prefers one directory over another, use the score flag.

Output Example:

The number represents the "frecency" score. You can see how the algorithm weighs your habits. If you want to boost old-project, you can simply zoxide add it multiple times to artificially inflate its score.

Verification (--all / -a)

By default, zoxide query only returns directories that currently exist on the file system. If you are auditing your database to see everything (including deleted folders that haven't been purged yet), use the --all flag.

5. Migration Commands: import

If you are migrating from autojump or the original z, you don't want to lose years of navigation history. Zoxide includes a specific command to handle this transition smoothly.

Running this once populates your db.zo file with your existing habits, allowing you to hit the ground running.

6. Using Zoxide Commands in Scripts

One of the major advantages of Zoxide over shell aliases is its binary nature, which makes it safe and easy to use in shell scripts.

Scenario: You want a script that opens your latest project in your editor. Instead of hardcoding paths, you can leverage zoxide commands:

This makes your scripts dynamic. If you move your React project to a new drive, the script still works as long as Zoxide knows the new location.

Conclusion

While it is tempting to treat Zoxide as just a "magic cd," taking the time to learn the specific zoxide commands—particularly query, add, and remove—transforms it from a utility into a productivity platform.

By mastering the initialization flags to replace cd, using zi for visual navigation, and understanding how to read score outputs, you ensure that your terminal behaves exactly how you expect. The command line is powerful because of its precision; Zoxide adds intelligence to that precision.