yazi

Main Yazi terminal file manager command

Overview

yazi is the main command to launch the Yazi terminal file manager. It provides a blazing fast file browsing and management experience built in Rust.

Synopsis

yazi [OPTIONS] [ENTRIES]...

Arguments

ENTRIES · path

Set the current working entry. You can specify 1 to 9 paths to open in multiple tabs.

# Open current directory
yazi

# Open specific directory
yazi /path/to/directory

# Open multiple directories in tabs
yazi /path/one /path/two /path/three

Options

--cwd-file · path

Write the current working directory path to this file on exit.

This is useful for shell integration, allowing your shell to change to the directory you navigated to in Yazi.

# Write cwd to a file on exit
yazi --cwd-file=/tmp/yazi-cwd

# Shell integration example (bash/zsh)
function ya() {
    local tmp="$(mktemp -t "yazi-cwd.XXXXX")"
    yazi "$@" --cwd-file="$tmp"
    if cwd="$(cat -- "$tmp")" && [ -n "$cwd" ] && [ "$cwd" != "$PWD" ]; then
        cd -- "$cwd"
    fi
    rm -f -- "$tmp"
}

--chooser-file · path

Write the selected files to this file when the open event is fired.

This allows Yazi to be used as a file picker for other applications.

# Use Yazi as a file chooser
yazi --chooser-file=/tmp/yazi-chosen

# After selecting files and pressing Enter
cat /tmp/yazi-chosen
# Output: selected file paths, one per line

--clear-cache · boolean · default: "false"

Clear the cache directory before starting.

Yazi caches previews and metadata. Use this option to clear stale cache data.

yazi --clear-cache

--client-id · number

Use the specified client ID. Must be a globally unique number.

This allows running multiple Yazi instances that can communicate with each other via DDS (Data Distribution Service).

# Start Yazi with a specific client ID
yazi --client-id=12345

--local-events · string

Report the specified local events to stdout.

Events should be comma-separated. This is useful for integrating Yazi with other tools.

# Monitor specific local events
yazi --local-events=cd,rename,delete

--remote-events · string

Report the specified remote events to stdout.

Events should be comma-separated. Remote events are those received from other Yazi instances via DDS.

# Monitor remote events from other instances
yazi --remote-events=hover,select

--debug · boolean · default: "false"

Print debug information.

Enables debug logging for troubleshooting.

yazi --debug

-V, --version · boolean · default: "false"

Print version information and exit.

yazi --version
# Output: yazi 0.x.x (commit-hash build-date)

Examples

Basic Usage

# Start Yazi in current directory
yazi

# Open a specific directory
yazi ~/Downloads

# Open multiple directories in tabs
yazi ~/Documents ~/Downloads ~/Pictures

Shell Integration

# Bash/Zsh: Change to the directory after exiting Yazi
function ya() {
    local tmp="$(mktemp -t "yazi-cwd.XXXXX")"
    yazi "$@" --cwd-file="$tmp"
    if cwd="$(cat -- "$tmp")" && [ -n "$cwd" ] && [ "$cwd" != "$PWD" ]; then
        cd -- "$cwd"
    fi
    rm -f -- "$tmp"
}

File Chooser Mode

# Use Yazi to select files for processing
CHOSEN=$(mktemp)
yazi --chooser-file="$CHOSEN"

# Process the selected files
while IFS= read -r file; do
    echo "Processing: $file"
done < "$CHOSEN"

rm "$CHOSEN"

Multiple Instances

# Terminal 1: Start first instance
yazi --client-id=1000

# Terminal 2: Start second instance
yazi --client-id=2000

# These instances can communicate via ya emit-to/pub-to commands

Environment Variables

Yazi respects several environment variables:

• YAZI_ID / YAZI_PID - Set automatically, contains the instance ID for IPC
• YAZI_FILE_ONE - Path to the first selected file
• Various XDG_* variables for config/cache/state directories

Exit Codes

• 0 - Success
• 1 - Error occurred

See Also

• ya - CLI utility for interacting with Yazi instances
• emit - Send commands to running instances
• pub-sub - Pub/sub messaging between instances
• package - Package management commands