Yazi

https://github.com/sxyazi/yazi
Admin
Yazi is a blazing fast, asynchronous terminal file manager written in Rust, offering efficient,...
Tokens:78,228
Snippets:553
Trust Score:9.6
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Rust example using yazi-fs init, Xdg, CWD, SizeCalculator, and Local engine

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-fs.md

Initializes the yazi-fs crate, gets the config directory via Xdg, reads and sets the current working directory with CWD, calculates total size of a directory with SizeCalculator, and demonstrates the Local engine for symlink metadata and reading directories.

```rust
use yazi_fs::{init, Xdg, engine::local::{Local, SizeCalculator}, CWD};

yazi_fs::init();

let cfg = Xdg::config_dir();                  // ~/.config/yazi
let cwd  = CWD.get();
CWD.set(UrlBuf::from("/new/dir"), || { /* callback */ });

let size = SizeCalculator::total(Url::from("/big/dir")).await?;

// Engine trait via local provider
let mut eng = Local::new(url).await?;
let stat = eng.symlink_metadata().await?;
if stat.is_dir() {
    let mut rd = eng.read_dir().await?;
    while let Some(entry) = rd.next().await { /* process */ }
}
```

--------------------------------

### setup() function

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-term.md

Initializes the global TERM static with a new Terminal instance using the TTY. Returns an anyhow::Result.

```rust
pub fn setup() -> anyhow::Result<()> {
    TERM.init(terminal::Terminal::new(&yazi_tty::TTY)?);
    Ok(())
}
```

--------------------------------

### Stat request example

Source: https://github.com/sxyazi/yazi/blob/main/yazi-sftp/README.md

Shows the idiomatic API using generic return parameters. The example sends a Stat request and awaits the response as responses::Attrs.

```rust
let attrs: responses::Attrs = session.send(requests::Stat::new(path)).await?
```

--------------------------------

### Install plugin globals in standard runtime

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-plugin-globals.md

Installs the eight plugin globals in the standard Lua runtime. The `ya` global is documented separately. All composable globals are `Composer`s with lazy key access; unknown keys evaluate to `nil`.

```rust
ui = crate::ui::compose();
ya = crate::utils::compose(false);
fs = crate::fs::compose();
vf = &*yazi_config::VFS;
ps = crate::pubsub::compose();
rt = crate::runtime::compose();
km = crate::keymap::compose();
th = crate::theme::compose();
```

--------------------------------

### ya.preview_widget(t, value)

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-plugin-ya.md

Async; installs renderable widget(s) into the preview lock. Raises an error if value is not a renderable element or a table of them.

```APIDOC
## ya.preview_widget(t, value)

### Description
Async; installs renderable widget(s) into the preview lock `t`: `value` is a `ui.*` userdata, a table of them, `nil` (clears), or an `Error` userdata; anything else raises `"preview widget must be a renderable element or a table of them"`.

### Parameters
- **t** (table) - Required - Preview lock table.
- **value** (any) - Required - A `ui.*` userdata, a table of them, `nil` (clears), or an `Error` userdata.

### Errors
- **"preview widget must be a renderable element or a table of them"** - Raised when `value` is not a renderable element or a table of them.
```

--------------------------------

### vfs.toml example: configuring VFS domain matchers

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/configuration.md

Shows how to configure the VFS engine with authority-to-domain matchers. Each entry specifies a 'kind' (view, hub, scope, noop, etc.) and a 'run' command. Domains must be one of the reserved names or a user scheme for sftp/lua services.

```toml
[fd.default]
kind = "view"   # view | hub | scope | noop | …
run  = "fd"

[trash."*"]
kind = "hub"
run  = "trash"

[go.boot]
kind = "scope"
run  = "go"

```

--------------------------------

### yazi binary startup sequence in yazi-fm/src/main.rs

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/index.md

The main function initializes various Yazi modules before calling the serve function to start the application loop.

```rust
#[tokio::main]
async fn main() -> anyhow::Result<()> {
	yazi_shim::init()?;
	yazi_shared::init();
	yazi_tty::init();
	yazi_emulator::init();
	yazi_fs::init();
	yazi_boot::init();
	yazi_vfs::init();
	yazi_runner::init(yazi_plugin::slim_lua);
	yazi_adapter::init();
	yazi_widgets::init();
	yazi_watcher::init();
	yazi_actor::init();
	yazi_fm::serve().await
}

async fn serve() -> anyhow::Result<()> {
	// Logs, signals, version print, terminal setup, emulator deinit,
	// panic handler, config setup (yazi.toml/keymap/theme/vfs),
	// DDS server+client, Lua runtime (yazi_plugin::setup), then:
	yazi_shared::LOCAL_SET.run_until(app::App::serve()).await
}
```

--------------------------------

### Process bindings install function in yazi-binding/src/process/mod.rs

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-binding.md

Installs the process userdata used by ya.proc_info, providing access to process metadata and command execution.

```rust
// process/mod.rs
pub fn install(lua: &Lua) -> mlua::Result<()>
```

--------------------------------

### Verify Rust installation

Source: https://github.com/sxyazi/yazi/blob/main/CONTRIBUTING.md

Check that the latest stable Rust compiler and package manager are installed.

```sh
rustc --version
cargo --version
```

--------------------------------

### Yazi CLI Command Examples

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-cli.md

Common commands for interacting with Yazi instances, including directory navigation, event messaging, package management, and diagnostics.

```bash
# Change the current directory of the running instance
ya emit manager:cd -- /tmp

# Send a message to an explicit instance
ya pub-to 123456 my-plugin-event --json '{"a":1}'

# Execute and capture the result
ya exec manager:get -- …

# Package management
ya pkg add git.yazi theme-dark.yazi
ya pkg install
ya pkg upgrade

# Subscribe to remote events (prints each payload)
ya sub bulk-rename,trash

# Diagnostics
ya env
```

--------------------------------

### Format code

Source: https://github.com/sxyazi/yazi/blob/main/CONTRIBUTING.md

Install the nightly rustfmt component and format all Rust files in the project.

```sh
rustup component add rustfmt --toolchain nightly
rustfmt +nightly **/*.rs
```

--------------------------------

### keymap.toml example: defining keybindings for the mgr layer

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/configuration.md

Shows the structure of a keymap.toml file with a [mgr] section containing a list of chords. Each chord uses 'on' for the key or key sequence, 'run' for the action string, and 'desc' for the which menu description. Actions support --flag=value style arguments.

```toml
[mgr]
keymap = [
    { on = "<Esc>", run = "escape", desc = "..." },
    { on = [ "g", "g" ], run = "arrow top", desc = "..." },
    { on = "<C-s>", run = "notify --type=info --timeout=5 'hello'", desc = "..." },
]

```

--------------------------------

### Example usage of Operator with responses

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-sftp-responses.md

Shows how to use Operator to perform SFTP operations and inspect responses. It initializes the operator, calls lstat and open, and handles results using the Attrs and StatusCode types.

```rust
use yazi_sftp::{Operator, error::Error, responses::{Attrs, StatusCode}};

let mut op = Operator::make(stream);
op.init().await?;

// stat returns responses::Attrs handled by the generic send
match op.lstat("/path").await {
    Ok(a)  => println!("atime={:?} perm={:?}", a.atime, a.perm),
    Err(e) => eprintln!("lstat failed: {e}"),
}

// Direct Status inspection through the public field:
let handle = op.open("/f", Flags::READ, &Attrs::default()).await?;
```

--------------------------------

### AsyncSeek::start_seek

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-sftp-fs.md

Starts a seek operation on the remote file. Supports SeekFrom::Start, SeekFrom::Current, and SeekFrom::End. For SeekFrom::End, a blocking Fstat is issued with a 45-second timeout.

```APIDOC
## AsyncSeek::start_seek

### Description
Starts a seek operation on the remote file. Supports SeekFrom::Start, SeekFrom::Current, and SeekFrom::End. For SeekFrom::End, a blocking Fstat is issued with a 45-second timeout.

### Method
fn start_seek(self: Pin<&mut Self>, position: SeekFrom) -> Poll<Result<(), Error>>

### Parameters
- **position** (SeekFrom) - Required - The seek position.

### Returns
- **()** - Success indicator.
- **Error** - An error if the operation fails.

### Error Conditions
- **SeekFrom::Current(n)** - Returns error "seeking to a negative or overflowed position" if the new position is negative or overflows.
- **Another seek pending** - Returns error "other file operation is pending, call poll_complete before start_seek".

### Example
rust
file.seek(SeekFrom::Start(0)).await?;

```

--------------------------------

### Action struct definition

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/types.md

Defines the universal command/event unit in Yazi. Constructors include Action::new(name, source, layer), Action::new_relay(name), and Action::new_relay_args(name, args). Builder methods take mut self and return Self: with(name, value), with_list(name, values), with_any(name, data), with_opt(name, value), with_seq(values), and with_replier(tx). Getters use get<T>(name).

```rust
#[derive(Clone, Debug, Default, DeserializeFromStr)]
pub struct Action {
    pub(crate) cmd: Cmd,
    pub layer:      Layer,
    pub source:     Source,
}
impl Deref for Action { type Target = Cmd; ... }
```

--------------------------------

### TaskStatus enum definition

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-scheduler.md

Defines the TaskStatus enum with variants Pending, Started, Succeeded, Failed, and Canceled. The default is Pending. Transitions: Pending to Started on start; Pending|Started to Succeeded/Failed on succeed/fail; Pending|Started|Failed to Canceled on cancel. has_started covers Started|Succeeded|Failed; is_finished covers Succeeded|Failed|Canceled.

```rust
#[repr(u8)]
#[derive(Clone, Copy, Debug, Default, EnumIs, Eq, FromRepr, PartialEq)]
pub enum TaskStatus {
    #[default]
    Pending   = 0,
    Started   = 1,
    Succeeded = 2,
    Failed    = 3,
    Canceled  = 4,
}
```

--------------------------------

### Publish and subscribe with Lua plugin

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-dds-ember.md

Demonstrates how to subscribe to events using ps.sub and publish events using ps.pub or ps.pub_to.

```lua
-- Lua plugin: publish and subscribe
ps.sub("my-plugin", "my-event", function(payload)
    print("received from", payload.sender, "body", vim.inspect(payload.body))
end)

ps.pub("my-event", { any = "data", list = { 1, 2, 3 }, nested = { ok = true } })
ps.pub_to(123456, "private-kind", "string-body")
```

--------------------------------

### Using Composer and Runtime with Lua

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-binding.md

Demonstrates initializing a Lua runtime with Yazi's Runtime and setting up a Composer table to bridge Rust and Lua values.

```rust
use yazi_binding::{Composer, Runtime, runtime, Scope};
use mlua::Lua;

let lua = Lua::new();
lua.set_app_data(Runtime::new("my-plugin", Scope::default()));

let mut table = Composer::new(
    |lua, key| if key == b"answer" { 42.into_lua(lua)? } else { Value::Nil },
    |_, _, v| Ok(v),
);
lua.globals().raw_set("t", table)?;   // t.answer == 42
```

--------------------------------

### Build the project

Source: https://github.com/sxyazi/yazi/blob/main/CONTRIBUTING.md

Compile the project using Cargo.

```sh
cargo build
```

--------------------------------

### Bootstrap initialization in yazi-boot/src/lib.rs

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-cli.md

Initializes the global ID, ARGS, and BOOT statics. ARGS is parsed from command-line arguments, ID is set to the client_id or a unique ID, and BOOT is set to its default value.

```rust
pub static ID: RoCell<Id> = RoCell::new();
pub static ARGS: RoCell<Args> = RoCell::new();
pub static BOOT: RoCell<Boot> = RoCell::new();

pub fn init() {
    ARGS.init(Args::parse());
    ID.init(ARGS.client_id.unwrap_or_else(Id::unique));
    BOOT.init(Default::default());
}
pub fn init_default()  // defaults ARGS/BOOT; ID = client_id or unique
```

--------------------------------

### Invalid event kinds

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-dds-ember.md

Examples of event kinds that trigger errors, such as system events or non-kebab-case strings.

```lua
ps.pub("cd", {})            -- error: "Cannot construct system event"
ps.pub("Bad Kind!", {})     -- error: "Kind `Bad Kind!` must be in kebab-case"
```

--------------------------------

### Initialize yazi-fs with CWD, mounts, and Xdg

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-fs.md

Initializes the filesystem foundation by setting up the CWD, mounts, and Xdg directories. Called during startup.

```rust
pub fn init() {
    CWD.init(<_>::default());
    mounts::init();
    Xdg::load();
}
```

--------------------------------

### TaskHandle struct and method signatures

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-scheduler.md

Defines the public, cloneable TaskHandle returned to spawners and exposed to Lua as the ya.task handle. It implements impl_data_any! (boxed as Data::Any). Methods: started() waits until non-Pending and returns true once Started; future() waits until finished and returns true iff Succeeded; start/succeed/fail/cancel are crate-private; status() returns TaskStatus; is_canceled() returns bool.

```rust
#[derive(Clone, Debug)]
pub struct TaskHandle {
    pub id: Id,
    inner:  Arc<(AtomicU8, Notify)>,
}

impl TaskHandle {
    pub(super) fn new(id: Id) -> Self
    pub async fn started(&self) -> bool      // waits until non-Pending; true once Started
    pub async fn future(&self) -> bool       // waits until finished; true iff Succeeded
    pub(crate) fn start(&self) / succeed(&self) / fail(&self) / cancel(&self)
    pub(crate) fn status(&self) -> TaskStatus
    pub(crate) fn is_canceled(&self) -> bool
}
```

--------------------------------

### Using Yazi FFI for COM and Shared Memory

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-ffi.md

Demonstrates initializing the Windows COM runtime using RAII and creating a named shared memory segment for image data.

```rust
use yazi_ffi::{Com, shm::NamedSharedMemory};

// Windows COM runtime
{
    let com = Com::new()?;          // CoInitializeEx
    // ... shell trash COM calls ...
}                                   // CoUninitialize on drop

// Shared-memory image packet (kgp)
let shm = NamedSharedMemory::new(&image_bytes)?;
let name = shm.name;                // send "name" + "len" to the terminal
unsafe { /* write into shm.as_mut_slice() before placement */ }
```

--------------------------------

### CWD

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-fs.md

Documentation for the CWD static, which manages the current working directory and provides methods to get, set, and ensure working paths.

```APIDOC
## `CWD` — Current Working Directory

### Description
Manages the current working directory state, allowing retrieval, setting, and ensuring a working path.

### Methods

#### `get(&self) -> UrlBuf`
Returns the current working directory as a `UrlBuf`.

#### `set(&self, url: &UrlBuf, callback: fn()) -> bool`
Sets the current working directory with `ln -sfn` semantics. Returns `true` if the directory actually changed, and invokes the provided callback on a real change.

#### `ensure(url: Url) -> Cow<Path>`
Ensures the given URL is a valid working path, returning a `Cow<Path>`.

### Usage
```rust
let current = CWD.get();
let changed = CWD.set(&new_url, || { /* callback */ });
let path = CWD.ensure(url);
```
```

--------------------------------

### ya.co(...)

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-plugin-ya.md

Creates a CoHandle (coroutine wrapper via yazi_runner::CoHandle::create). The handle supports status(), resume(), cancel(), and started() methods.

```APIDOC
## ya.co(...)

### Description
Creates a CoHandle (coroutine wrapper via yazi_runner::CoHandle::create). The handle supports status(), resume(), cancel(), and started() methods.

### Method
Function call

### Endpoint
utils/sync.rs

### Parameters
No explicit parameters documented.

### Response
#### Success Response
- **CoHandle** - Coroutine handle with methods: status(), resume(), cancel(), started().
```

--------------------------------

### Using Yazi VFS Engine for File Operations

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-vfs.md

Demonstrates performing local file calculations, reading remote directories via SFTP, and executing cross-service file copies with progress tracking.

```rust
use yazi_vfs::engine;

// Local URL
let size = engine::calculate("~/Downloads").await?;
let abs  = engine::absolute("file.txt").await?.into_owned();

// Remote (sftp) authority handled transparently
let entries = engine::read_dir("sftp://user@host/srv").await?;
while let Some(de) = entries.next().await {
    println!("{}", de.url);
}

// Cross-service copy with progressive reporting
let tx = engine::copy("sftp://host/a", "local:/tmp/b", Attrs::default()).await?;
while tx.progress().await { /* drive Transmit */ }
```

--------------------------------

### Dimension struct

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-term.md

Defines the Dimension struct with columns, rows, width, and height. Provides methods for checking validity, getting area, and computing pixel-per-cell ratio. Implements From<Winsize> on Unix.

```rust
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub struct Dimension { pub cols: u16, pub rows: u16, pub width: u16, pub height: u16 }

impl Dimension {
    pub fn checked(self) -> io::Result<Self>   // Err when cols/rows == 0 (ioctl and env both failed)
    pub fn area(self) -> (u16, u16)            // (cols, rows)
    pub fn ratio(self) -> Option<(f64, f64)>   // px-per-cell ratio when both sizes are known
}
impl From<rustix::termios::Winsize> for Dimension   // unix
```

--------------------------------

### fs.create(url)

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-plugin-globals.md

Opens a file for writing (truncate) and returns a File userdata.

```APIDOC
## fs.create(url)

### Description
Opens a file for writing (truncate) and returns a File userdata.

### Parameters
- **url** (string or UrlBuf) - Required - The URL of the file to create.

### Returns
- **File** - A File userdata for writing.
```

--------------------------------

### Manage tasks in Rust with TaskHandle

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-scheduler.md

Demonstrates creating a task handle, waiting for task completion, and handling cancellation in Rust.

```rust
use yazi_scheduler::{TaskHandle, TaskStatus};

let handle = TaskHandle::new(Id::unique());
// hand to a worker; worker calls handle.start(), then handle.succeed()/fail()

assert!(handle.started().await);      // true once started
let ok = handle.future().await;       // true iff succeeded

// cancellation
handle.cancel();
assert!(handle.status().is_canceled());
```

--------------------------------

### Id struct definition

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/types.md

Defines the Id type with a ZERO constant and a unique() constructor that uses a timestamp to ensure global uniqueness. The struct derives common traits and provides a get() accessor.

```rust
#[derive(Clone, Copy, Debug, Default, Deserialize, Eq, Hash, Ord, PartialEq, PartialOrd, Serialize)]
pub struct Id(pub(super) u64);

impl Id {
    pub const ZERO: Self = Self(0);
    #[inline]
    pub const fn get(self) -> u64 { self.0 }
    pub fn unique() -> Self { Self(crate::timestamp_us()) }
}
```

--------------------------------

### Spawn and track tasks in Lua with ya.task

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-scheduler.md

Shows how to initialize a custom task, spawn it, and report progress updates in Lua.

```lua
local t = ya.task("custom", { pool = "plugin", scope = rt.scope() })
    :name("preview-gen")
    :spawn()
assert(t:acquire(), "task should start")

for i = 1, 10 do
    ya.sleep(20)
    t:progress { total = 10, success = i }
end
t:succeed({ url })
```

--------------------------------

### CWD static and Cwd methods

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-fs.md

Defines the CWD static and Cwd struct with get, set, and ensure methods. The set method uses ln -sfn semantics and fires a callback only on real changes.

```rust
pub static CWD: RoCell<Cwd> = RoCell::new();
#[derive(...)] pub struct Cwd(ArcSwap<UrlBuf>);

impl Cwd {
    pub fn get(&self) -> UrlBuf
    pub fn set(&self, url: &UrlBuf, callback: fn()) -> bool   // ln -sfn semantics; fires callback on real change
    pub fn ensure(url: Url) -> Cow<Path>
}
```

--------------------------------

### Streaming read of a directory with Operator

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-sftp-fs.md

Shows how to create an Operator, initialize it, and stream-read a directory, printing each entry's path and nlink, and checking if attributes are empty.

```rust
use yazi_sftp::{Operator, fs::{Attrs, Flags, DirEntry}};

// Streaming read of a directory
let mut op = Operator::make(stream);
op.init().await?;

let mut rd = op.read_dir("/srv").await?;
while let Some(entry) = rd.next().await? {
    println!("{}  nlink={:?}", entry.path(), entry.nlink());
    if entry.attrs().is_empty() {
        println!("  (no attributes)");
    }
}
```

--------------------------------

### Basic session usage with Operator::make and stat

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-sftp.md

Shows how to create an Operator from a ChannelStream, initialize it, and perform a stat request. The attrs.size field is an Option<u64>.

```rust
use yazi_sftp::{Operator, requests::Stat, responses::Attrs};
use russh::client::ChannelStream;

// stream: ChannelStream<Msg> obtained from an ssh session
let mut op = Operator::make(stream);
op.init().await?;

let attrs: Attrs = op.stat("/remote/path.txt").await?;
let size = attrs.size; // Option<u64>
```

--------------------------------

### ya.preview_code(t)

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-plugin-ya.md

Async; renders syntax-highlighted code and pushes it into the preview. Returns nothing on success, or nil and max on PeekError::Exceeded, or the error message on other errors.

```APIDOC
## ya.preview_code(t)

### Description
Async; takes a single table `t` with `area` (`ui.Area`), `file` (`FileRef`), and preview-lock fields (`skip`, `lock`, ...). Renders syntax-highlighted code via `Highlighter::oneshot` and pushes it into the preview via `MgrProxy::update_peeked` (returns nothing on success). On `PeekError::Exceeded(max)` returns `nil, max`; on other errors returns the error message.

### Parameters
- **t** (table) - Required - Table with `area` (ui.Area), `file` (FileRef), and preview-lock fields (`skip`, `lock`, ...).

### Returns
- **nil** - On success.
- **nil, max** - On `PeekError::Exceeded(max)`.
- **string** - On other errors, returns the error message.
```

--------------------------------

### Flags bitflags definition

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-sftp-fs.md

Defines the Flags type using the bitflags crate, with constants READ, WRITE, APPEND, CREATE, TRUNCATE, and EXCLUDE. Usage examples include Flags::READ, Flags::READ | Flags::WRITE, and Flags::CREATE | Flags::TRUNCATE | Flags::WRITE.

```rust
#[derive(Clone, Copy, Debug, Default, Deserialize, Serialize)]
pub struct Flags(u32);

bitflags! {
    impl Flags: u32 {
        const READ     = 0b000001;
        const WRITE    = 0b000010;
        const APPEND   = 0b000100;
        const CREATE   = 0b001000;
        const TRUNCATE = 0b010000;
        const EXCLUDE  = 0b100000;
    }
}
```

--------------------------------

### ya.target_os() -> string

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-plugin-ya.md

Returns the target operating system as a string, such as "linux", "macos", "windows", or "android".

```APIDOC
## ya.target_os()

### Description
Returns the target OS of the system.

### Method
Function call

### Endpoint
`ya.target_os()`

### Parameters
None

### Returns
- **string** - The target OS name (e.g., "linux", "macos", "windows", "android").
```

--------------------------------

### TERM static and Terminal struct (unix)

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-term.md

Defines the global TERM static and the Terminal struct for Unix. The Terminal struct holds a reference to the TTY, an event source, and a restorer. Its methods handle terminal setup, dimension retrieval, and raw/cooked mode switching. On drop, the restorer restores the terminal.

```rust
pub static TERM: RoCell<Terminal<...>>;   // initialized by setup()

// yazi-term/src/terminal/unix.rs
pub struct Terminal<'a> {
    tty:          &'a Tty,
    pub source:   Arc<EventSource<'a>>,
    pub restorer: Restorer,
}
impl<'a> Terminal<'a> {
    pub(crate) fn new(tty: &'a Tty) -> io::Result<Self>
    pub fn setup(&self) -> io::Result<()>           // no-op on unix
    pub fn dimension(&self) -> Dimension             // ioctl winsize; falls back to $LINES/$COLUMNS
    pub fn enter_raw_mode(&self) -> io::Result<()>   // termios::make_raw (Flush)
    pub fn enter_cooked_mode(&self) -> io::Result<()>
}
impl Drop for Terminal<'_> { fn drop(&mut self) { self.restorer.restore(self.tty); } }
```

--------------------------------

### Windows COM RAII wrapper (yazi-ffi/src/com.rs)

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-ffi.md

RAII wrapper that initializes COM on the current thread with COINIT_APARTMENTTHREADED and uninitializes on drop. Used by the Windows trash backend.

```rust
pub struct Com;
impl Com {
    pub fn new() -> io::Result<Self>   // CoInitializeEx(None, COINIT_APARTMENTTHREADED); io::Error::other on failure
}
impl Drop for Com { fn drop(&mut self) { unsafe { CoUninitialize() } } }
```

--------------------------------

### Initialize terminal and poll events

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-term.md

Demonstrates setting up the terminal, entering raw mode, and using try_poll to block until an event is received.

```rust
use yazi_term::{TERM, setup, event::{Event, KeyCode}};

setup()?;
TERM.enter_raw_mode()?;

// try_poll is synchronous and blocking; it returns the first matching event
// or `io::ErrorKind::TimedOut` when `timeout` elapses
let event = TERM.source.try_poll(None, |e| e.is_key());
match event {
    Ok(Event::Key(k)) if k.code == KeyCode::Char('q') => { /* quit */ }
    Ok(Event::Resize(d)) => redraw(d.cols, d.rows),
    Ok(Event::Mouse(m)) => { /* m.kind, m.column, m.row */ }
    Err(e) => { /* TimedOut etc. */ }
}
```

--------------------------------

### Crate root initialization functions

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-dds.md

Core functions for initializing, serving, and shutting down the DDS service.

```rust
pub fn init()       // sets up queues, clients, state, pubsub tables; manages YAZI_ID/YAZI_PID/YAZI_LEVEL env vars
pub fn serve()      // init() + Pump::serve() + Client::serve()
pub async fn shutdown()  // Pump::shutdown()
```

--------------------------------

### Init

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-sftp-requests.md

The Init request struct for initializing an SFTP session. It contains a protocol version and client extension advertisements. The default version is 3.

```APIDOC
## Init

### Description
Represents an SFTP initialization request, carrying the protocol version and client extension advertisements.

### Fields
- **version** (u32) - Protocol version (default 3)
- **extensions** (HashMap<String, String>) - Client extension advertisements

### Default
- version = 3, empty extensions

### Usage
Sent via Operator::init, which sends Init::default() and stores the returned extensions.
```

--------------------------------

### Push changes

Source: https://github.com/sxyazi/yazi/blob/main/CONTRIBUTING.md

Upload your branch to your fork.

```sh
git push origin your-branch-name
```

--------------------------------

### Run tests

Source: https://github.com/sxyazi/yazi/blob/main/CONTRIBUTING.md

Execute the workspace tests with verbose output.

```sh
cargo test --workspace --verbose
```

--------------------------------

### View the project directory structure

Source: https://github.com/sxyazi/yazi/blob/main/CONTRIBUTING.md

An overview of the Yazi project layout, including core modules, configuration, and assets.

```sh
.
├── assets/             # Assets like images and fonts
├── nix/                # Nix-related configurations
├── scripts/            # Helper scripts used by CI/CD
├── snap/               # Snapcraft configuration
├── yazi-adapter/       # Yazi image adapter
├── yazi-binding/       # Yazi Lua bindings
├── yazi-boot/          # Yazi bootstrapper
├── yazi-cli/           # Yazi command-line interface
├── yazi-codegen/       # Yazi code generator
├── yazi-config/        # Yazi configuration file parser
├── yazi-core/          # Yazi core logic
├── yazi-dds/           # Yazi data distribution service
├── yazi-ffi/           # Yazi foreign function interface
├── yazi-fm/            # Yazi file manager
├── yazi-fs/            # Yazi file system
├── yazi-macro/         # Yazi macros
├── yazi-plugin/        # Yazi plugin system
├── yazi-proxy/         # Yazi event proxy
├── yazi-scheduler/     # Yazi task scheduler
├── yazi-shared/        # Yazi shared library
├── yazi-term/          # Yazi terminal extensions
├── yazi-widgets/       # Yazi user interface widgets
├── .github/            # GitHub-specific files and workflows
├── Cargo.toml          # Rust workflow configuration
└── README.md           # Project overview
```

--------------------------------

### ya.join(...fns)

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-plugin-ya.md

Async; calls every function argument, awaits them concurrently, and returns their results as multiple values.

```APIDOC
## ya.join(...fns)

### Description
Async; calls every function argument, awaits them concurrently, and returns their results as multiple values.

### Method
Function call

### Endpoint
utils/sync.rs

### Parameters
#### Path Parameters
- **...fns** (functions) - Required - Functions to call concurrently.

### Response
#### Success Response
- **values** (multiple) - Results of each function.
```

--------------------------------

### Environment variable initialization logic

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-dds.md

Logic used by init() to manage YAZI_ID, YAZI_PID, and YAZI_LEVEL environment variables.

```rust
unsafe {
    if let Some(s) = std::env::var("YAZI_ID").ok().filter(|s| !s.is_empty()) {
        std::env::set_var("YAZI_PID", s);          // promote YAZI_ID → YAZI_PID
    }
    std::env::set_var("YAZI_ID", yazi_boot::ID.to_string());
    std::env::set_var("YAZI_LEVEL",
        (std::env::var("YAZI_LEVEL").unwrap_or_default().parse().unwrap_or(0u16) + 1).to_string());
}
```

--------------------------------

### Copy task in async context (Lua)

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-plugin-ya.md

Demonstrates spawning a 'copy' task inside `ya.async` with the `from` and `to` fields required for the copy kind. The `:spawn()` method submits the task to the scheduler.

```lua
-- Copy task (as used by the clipboard plugin)
ya.async(function()
    ya.task("copy", { from = from_url, to = to_url }):spawn()
end)()
```

--------------------------------

### Set up the upstream remote

Source: https://github.com/sxyazi/yazi/blob/main/CONTRIBUTING.md

Configure the upstream remote to keep your fork synchronized with the main Yazi repository.

```sh
git remote add upstream https://github.com/sxyazi/yazi.git
```

--------------------------------

### ya.task

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-plugin-ya.md

Spawns a background task of a specified kind (copy, move, plugin, custom) and returns a TaskOpt builder. The builder allows setting the task name and spawning it, returning a Task handle for progress reporting and control.

```APIDOC
## ya.task

### Description
Spawns a background task of a specified kind (copy, move, plugin, custom) and returns a TaskOpt builder. The builder allows setting the task name and spawning it, returning a Task handle for progress reporting and control.

### Method
N/A (Lua function)

### Endpoint
N/A (Lua function)

### Parameters
#### Request Body
- **kind** (string) - Required - The task kind: "copy", "move", "plugin", or "custom". Unknown kinds raise an error.
- **opts** (table) - Required - Options table specific to the task kind.
  - For "copy": { from, to, force = false, follow = false }
  - For "move": { from, to, force = false }
  - For "plugin": PluginInEntry (plugin name/args/scope)
  - For "custom": { pool, scope, track, progress }

### Request Example
```lua
local task = ya.task("custom", { pool = "plugin", scope = rt.scope() })
    :name("Drop data")
    :spawn()
```

### Response
#### Success Response (200)
- **TaskOpt** (userdata) - Builder object with methods:
  - **name(str)** - Sets the task title; returns the same TaskOpt.
  - **spawn()** - async - Submits the task to the scheduler and returns a Task handle.
- **Task** (userdata) - Handle with fields and methods:
  - **id** (field) - The task ID.
  - **acquire()** - Returns true once started.
  - **progress{total=,success=,failed=,workload=,processed=}** - Reports progress.
  - **succeed(urls)** - Marks the task as successful.
  - **fail(reason)** - Marks the task as failed.
  - **log(line)** - Logs a line.

#### Response Example
```lua
local task = ya.task("custom", { pool = "plugin", scope = rt.scope() })
    :name("Drop data")
    :spawn()
local ok = task:acquire()
for i = 1, 10 do
    ya.sleep(50)
    task:progress { total = 10, success = i }
end
task:succeed()
```
```

--------------------------------

### ya.spot_table(t, table)

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-plugin-ya.md

Synchronous. Borders the given table, pushes a clear + rounded border + table into the spot lock, and calls MgrProxy::update_spotted.

```APIDOC
## ya.spot_table(t, table)

### Description
Synchronous. Borders the given table, pushes a clear + rounded border + table into the spot lock, and calls MgrProxy::update_spotted.

### Method
Function call

### Endpoint
utils/spot.rs

### Parameters
#### Path Parameters
- **t** (SpotLock) - Required - Spot lock table.
- **table** (ui.Table) - Required - Table widget to display.

### Response
No return value.
```

--------------------------------

### Create a new branch

Source: https://github.com/sxyazi/yazi/blob/main/CONTRIBUTING.md

Initialize a new Git branch for your proposed changes.

```sh
git checkout -b your-branch-name
```

--------------------------------

### fs.expand_url(s)

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-plugin-globals.md

Expands ~, environment variables, and relative paths into an absolute URL.

```APIDOC
## fs.expand_url(s)

### Description
Expands ~, environment variables, and relative paths into an absolute URL.

### Parameters
- **s** (string) - Required - The string to expand.

### Returns
- **UrlBuf** - The expanded absolute URL.
```

--------------------------------

### fs.op(...)

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-plugin-globals.md

Generic VFS operation dispatcher.

```APIDOC
## fs.op(...)

### Description
Generic VFS operation dispatcher.

### Parameters
- **...** - Variable arguments depending on the operation.
```

--------------------------------

### vf.service(auth)

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-plugin-globals.md

Resolves the configured service (sftp/lua/built-in) for a given authority. Returns the service name as a string.

```APIDOC
## vf.service(auth)

### Description
Resolves the configured service (sftp/lua/built-in) for a given authority. Returns the service name as a string.

### Method
vf.service

### Parameters
- **auth** (string) - Required - The authority to resolve the service for.

### Returns
- **service** (string) - The configured service name (sftp/lua/built-in).
```

--------------------------------

### fs.partitions()

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-plugin-globals.md

Returns the mount partition table from yazi_fs::mounts::PARTITIONS.

```APIDOC
## fs.partitions()

### Description
Returns the mount partition table from yazi_fs::mounts::PARTITIONS.

### Returns
- **table** - The partition table.
```

--------------------------------

### Open<'a>

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-sftp-requests.md

The Open request struct for opening a file on the SFTP server. It contains the target path, file flags, and initial attributes for created files.

```APIDOC
## Open<'a>

### Description
Represents an SFTP open request, specifying the target path, file flags, and initial attributes for created files.

### Fields
- **path** (SftpPath<'a>) - Target path
- **flags** (fs::Flags) - READ, WRITE, APPEND, CREATE, TRUNCATE, EXCLUDE
- **attrs** (Cow<'a, Attrs>) - Initial attributes for created files
```

--------------------------------

### ya.chunk(plugin_name) -> { sync_peek }

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-plugin-ya.md

Async; ensures the named plugin chunk is loaded and returns a table with a sync_peek function (or nil, message when the chunk cannot be loaded).

```APIDOC
## ya.chunk(plugin_name) -> { sync_peek }

### Description
Async; ensures the named plugin chunk is loaded and returns a table with a sync_peek function (or nil, message when the chunk cannot be loaded).

### Method
Function call

### Endpoint
utils/sync.rs

### Parameters
#### Path Parameters
- **plugin_name** (string) - Required - Name of the plugin chunk.

### Response
#### Success Response
- **table** - Table containing sync_peek function.

#### Error Response
- **nil** - If chunk cannot be loaded.
- **message** (string) - Error message.
```

--------------------------------

### fs.copy(from, to[, opts])

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-plugin-globals.md

Copies a file or directory through the VFS engine. Returns a Transmit-like result.

```APIDOC
## fs.copy(from, to[, opts])

### Description
Copies a file or directory through the VFS engine. Returns a Transmit-like result.

### Parameters
- **from** (string or UrlBuf) - Required - Source URL.
- **to** (string or UrlBuf) - Required - Destination URL.
- **opts** (table) - Optional - Additional options.

### Returns
- **Transmit** - A Transmit-like result.
```

--------------------------------

### Spawn custom task and report progress (Lua)

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-plugin-ya.md

Spawns a custom task with `ya.task` in the 'plugin' pool, acquires it, reports progress with `:progress{total=,success=}` in a loop, and calls `:succeed()`. The pattern comes from `dnd.lua`.

```lua
-- Spawn a custom task and report progress (pattern from yazi-plugin/preset/plugins/dnd.lua)
local task = ya.task("custom", { pool = "plugin", scope = rt.scope() })
    :name("Drop data")
    :spawn()
local ok = task:acquire()          -- true once started
for i = 1, 10 do
    ya.sleep(50)
    task:progress { total = 10, success = i }
end
task:succeed()
```

--------------------------------

### Session method signatures

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-sftp.md

Method signatures for the Session type. `make` creates the session and spawns writer/reader tasks; `send` uses a 45-second timeout and converts Status replies to errors; `send_sync` registers a oneshot callback; `send_with_timeout` wraps `send_sync` in a timeout; `is_closed` checks if the outbound queue is closed.

```rust
pub(crate) fn make(stream: ChannelStream<Msg>) -> Arc<Self>
pub(crate) async fn send<'a, I, O>(self: &Arc<Self>, input: I) -> Result<O, Error>
    where I: Into<Packet<'a>> + Serialize,
          O: TryFrom<Packet<'static>, Error = Error> + 'static
pub(crate) fn send_sync<'a, I>(self: &Arc<Self>, input: I) -> Result<Receiver, Error>
    where I: Into<Packet<'a>> + Serialize
pub(crate) async fn send_with_timeout<'a, I, O>(self: &Arc<Self>, input: I, timeout: Duration) -> Result<O, Error>
    where I: Into<Packet<'a>> + Serialize,
          O: TryFrom<Packet<'static>, Error = Error> + 'static
pub fn is_closed(self: &Arc<Self>) -> bool
```

--------------------------------

### fs.write(url)

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-plugin-globals.md

Opens a file for append/write and returns a File userdata.

```APIDOC
## fs.write(url)

### Description
Opens a file for append/write and returns a File userdata.

### Parameters
- **url** (string or UrlBuf) - Required - The URL of the file to write.

### Returns
- **File** - A File userdata for writing.
```

--------------------------------

### File read loop with error handling

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-sftp-fs.md

Demonstrates opening a file with Flags::READ and reading in a loop, handling EOF (Status::Eof) and errors. On drop, the remote handle is closed automatically.

```rust
use tokio::io::{AsyncRead, ReadBuf};

let mut file = op.open("/big.bin", Flags::READ, &Attrs::default()).await?;
let mut buf = ReadBuf::new(vec![0; 8192]);

loop {
    match file.read(&mut buf).await {
        Ok(0) => break,                 // EOF (Status::Eof)
        Ok(n) => process(buf.as_slice()[..n]),
        Err(e) => { eprintln!("read failed: {e}"); break; }
    }
}
// on drop, yazi_sftp::fs::File closes the remote handle
```

--------------------------------

### Args struct definition in yazi-boot/src/args.rs

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-cli.md

Defines the command-line arguments for the yazi binary using clap. Includes positional entries, --cwd-file, --chooser-file, --client-id, --local-events, --remote-events, and -V/--version.

```rust
#[derive(Debug, Default, Parser)]
#[command(name = "yazi")]
pub struct Args {
    /// Set the current working entry
    #[arg(index = 1, num_args = 1..=9)]
    pub entries: Vec<StrandBuf>,
    /// Write the cwd on exit to this file
    #[arg(long)]
    pub cwd_file:     Option<PathBuf>,
    /// Write the selected files to this file on open fired
    #[arg(long)]
    pub chooser_file: Option<PathBuf>,
    #[arg(long)] pub(crate) client_id: Option<Id>,
    #[arg(long, default_value = "", hide_default_value = true, value_parser = events())]
    pub local_events:  HashSet<String>,
    #[arg(long, default_value = "", hide_default_value = true, value_parser = events())]
    pub remote_events: HashSet<String>,
    #[arg(short = 'V', long)] pub(crate) version: bool,
}
```

--------------------------------

### Run validation and formatting commands for Yazi

Source: https://github.com/sxyazi/yazi/blob/main/AGENTS.md

Use these commands to check, test, lint, and format the codebase. The `-p <package>` flags target specific crates; use multiple flags for affected crates. `rustfmt +nightly` formats Rust files, and `stylua --check` checks Lua formatting.

```sh
cargo check -p <package>
cargo test -p <package>
cargo clippy -p <package>
rustfmt +nightly **/*.rs
stylua --color always --check .
```

--------------------------------

### Init request struct (requests/init.rs)

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-sftp-requests.md

Wire type for the SFTP INIT request. The Default impl sets version to 3 and an empty extensions map. Used by Operator::init to send Init::default() and store returned extensions.

```rust
#[derive(Debug, Deserialize, Serialize)]
pub struct Init {
    version:    u32,
    extensions: HashMap<String, String>,
}
impl Default for Init { fn default() -> Self; } // version = 3, empty extensions
```

--------------------------------

### Server struct definition in yazi-dds/src/server.rs

Source: https://github.com/sxyazi/yazi/blob/main/_autodocs/api-reference/yazi-dds.md

Defines the Server structure and the make method for initializing the server.

```rust
pub(super) struct Server;
impl Server {
    pub(super) async fn make() -> Result<JoinHandle<()>>
}
```
Tokens:
Raw