Skip to main content

The ya CLI Companion

ya is the command-line companion for Yazi. It handles package management, flavor installation, and DDS messaging across Yazi instances.

Plugin Management​

CommandDescription
ya pkg --install <name>Install a package from the registry
ya pkg --listList installed packages
ya pkg --upgradeUpgrade all installed packages
ya pkg --install --force <name>Force reinstall a package
# Install a plugin
ya pkg --install "some-plugin"

# List what's installed
ya pkg --list

# Upgrade everything
ya pkg --upgrade
warning

ya pkg --upgrade upgrades all packages. Use --install --force to reinstall a single package.

Flavor Management​

Flavors are handled through the same ya pkg interface:

# Install a flavor
ya pkg --install "catppuccin"

# List all flavors
ya pkg --list

DDS Pub-Sub Messaging​

The Data Distribution Service (DDS) lets Yazi instances communicate. ya exposes three subcommands:

CommandDescription
ya pub <kind> <body>Publish a message to the default receiver
ya pub-to <receiver> <kind> <body>Publish a targeted message to a specific receiver
ya emit <kind> <body>Emit a message without a receiver (one-to-many broadcast)
# Publish a message
ya pub "sync" '{"path": "/home/user/project"}'

# Publish to a specific receiver
ya pub-to "other-instance" "refresh" '{"tab": 1}'

# Emit a broadcast
ya emit "event" '{"type": "files-changed"}'

Subscribing​

Plugins subscribe to DDS events using package.toml:

[package]
name = "my-plugin"
version = "0.1.0"

[dds]
subscribe = ["sync", "refresh", "event"]

package.toml Reference​

Every Yazi package (plugin or flavor) declares itself with a package.toml:

[package]
name        = "my-plugin"
version     = "0.2.0"
description = "Does something useful"
authors     = ["You <you@example.com>"]
license     = "MIT"

[dependencies]
some-lib = "0.1"

[dds]
subscribe = ["custom-event"]
info

package.toml is required for packages published to the Yazi registry. Subscriptions are optional — omit the [dds] section if your package doesn't use DDS.

See Also​

  • DDS Overview — deep dive into pub-sub messaging architecture
  • Plugins — writing plugins that consume DDS events