> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/sxyazi/yazi/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
yazi [OPTIONS] [ENTRIES]...
```

## Arguments

<ParamField path="ENTRIES" type="path" optional>
  Set the current working entry. You can specify 1 to 9 paths to open in multiple tabs.

  ```bash theme={null}
  # Open current directory
  yazi

  # Open specific directory
  yazi /path/to/directory

  # Open multiple directories in tabs
  yazi /path/one /path/two /path/three
  ```
</ParamField>

## Options

<ParamField path="--cwd-file" type="path" optional>
  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.

  ```bash theme={null}
  # 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"
  }
  ```
</ParamField>

<ParamField path="--chooser-file" type="path" optional>
  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.

  ```bash theme={null}
  # 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
  ```
</ParamField>

<ParamField path="--clear-cache" type="boolean" default="false">
  Clear the cache directory before starting.

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

  ```bash theme={null}
  yazi --clear-cache
  ```
</ParamField>

<ParamField path="--client-id" type="number" optional>
  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).

  ```bash theme={null}
  # Start Yazi with a specific client ID
  yazi --client-id=12345
  ```
</ParamField>

<ParamField path="--local-events" type="string" optional>
  Report the specified local events to stdout.

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

  ```bash theme={null}
  # Monitor specific local events
  yazi --local-events=cd,rename,delete
  ```
</ParamField>

<ParamField path="--remote-events" type="string" optional>
  Report the specified remote events to stdout.

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

  ```bash theme={null}
  # Monitor remote events from other instances
  yazi --remote-events=hover,select
  ```
</ParamField>

<ParamField path="--debug" type="boolean" default="false">
  Print debug information.

  Enables debug logging for troubleshooting.

  ```bash theme={null}
  yazi --debug
  ```
</ParamField>

<ParamField path="-V, --version" type="boolean" default="false">
  Print version information and exit.

  ```bash theme={null}
  yazi --version
  # Output: yazi 0.x.x (commit-hash build-date)
  ```
</ParamField>

## Examples

### Basic Usage

```bash theme={null}
# Start Yazi in current directory
yazi

# Open a specific directory
yazi ~/Downloads

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

### Shell Integration

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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](ya) - CLI utility for interacting with Yazi instances
* [emit](emit) - Send commands to running instances
* [pub-sub](pub-sub) - Pub/sub messaging between instances
* [package](package) - Package management commands