Skip to main content

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.

​
Overview

The pub/sub commands provide a messaging system for communication between Yazi instances and external tools. Unlike emit which sends commands, pub/sub is designed for custom events and data exchange.

​
pub

Publish a message to the current Yazi instance.

​
Synopsis

ya pub <KIND> [OPTIONS]

​
Arguments

​
KIND
string
required
Kind of message to publish.This is a custom identifier for your message type. It should be unique and descriptive.
ya pub file-changed
ya pub custom-event
ya pub build-complete

​
Options

​
--str
string
Send the message with a string body.The string will be JSON-encoded.
ya pub greeting --str="Hello, Yazi!"
​
--json
string
Send the message with a JSON body.The JSON string should be valid JSON and will be sent as-is.
ya pub config-update --json='{"theme": "dark", "line_numbers": true}'
​
--list
string[]
Send the message as a list of strings.Multiple values can be provided, and they will be sent as a JSON array.
ya pub files-selected --list file1.txt file2.txt file3.txt

# Results in: ["file1.txt", "file2.txt", "file3.txt"]

​
Examples

# Simple notification
ya pub notification --str="Task completed"

# Send structured data
ya pub file-stats --json='{"size": 1024, "modified": "2024-03-01"}'

# Send list of items
ya pub selected-files --list file1.txt file2.txt file3.txt

# Event without body
ya pub refresh-complete

​
pub-to

Publish a message to a specific Yazi instance.

​
Synopsis

ya pub-to <RECEIVER> <KIND> [OPTIONS]

​
Arguments

​
RECEIVER
number
required
Receiver instance ID.The client ID of the target Yazi instance.
ya pub-to 12345 notification --str="Hello!"
​
KIND
string
required
Kind of message to publish.

​
Options

Same as pub command:
  • --str - String message body
  • --json - JSON message body
  • --list - List of strings

​
Examples

# Send notification to specific instance
ya pub-to 1000 alert --str="Build failed"

# Send data to specific instance
ya pub-to 1000 update --json='{"status": "running"}'

# Send list to specific instance
ya pub-to 1000 file-list --list file1 file2 file3

​
sub

Subscribe to messages from all remote instances.

​
Synopsis

ya sub <KINDS>

​
Arguments

​
KINDS
string
required
Kinds of messages to subscribe to, separated by commas.Multiple message kinds can be specified to listen for different event types.
# Subscribe to single message kind
ya sub file-changed

# Subscribe to multiple message kinds
ya sub file-changed,build-complete,notification

​
Behavior

  • Subscribes to the specified message kinds
  • Prints received messages to stdout
  • Runs until interrupted with Ctrl+C
  • Listens for messages from all remote Yazi instances

​
Examples

# Listen for file changes
ya sub file-changed

# Listen for multiple event types
ya sub notification,alert,warning

# Monitor all communication
ya sub file-changed,dir-changed,selection-changed,state-update

​
Output Format

Messages are printed to stdout as they arrive. The exact format depends on the message body: 
# String message
"Hello, Yazi!"

# JSON message
{"theme": "dark", "line_numbers": true}

# List message
["file1.txt", "file2.txt", "file3.txt"]

​
Use Cases

​
File Watching Integration

#!/bin/bash
# Watch for file changes and notify Yazi

fswatch -0 ~/watched-dir | while read -d "" event; do
    ya pub file-changed --str="$event"
done

​
Build System Integration

#!/bin/bash
# Notify Yazi when build completes

make build
if [ $? -eq 0 ]; then
    ya pub build-complete --str="success"
else
    ya pub build-complete --str="failure"
fi

​
Inter-Instance Communication

# Terminal 1: Subscribe to notifications
ya sub notification,alert

# Terminal 2: Send notifications to instance 1000
ya pub-to 1000 notification --str="Task completed"
ya pub-to 1000 alert --str="Attention required"

​
Custom Event Monitoring

#!/bin/bash
# Monitor and log Yazi events

ya sub file-changed,dir-changed | while IFS= read -r event; do
    echo "$(date): $event" >> yazi-events.log
done

​
Plugin Communication

-- Yazi plugin: Send message when action completes
local function notify_external(message)
    local cmd = string.format('ya pub plugin-event --str="%s"', message)
    os.execute(cmd)
end

notify_external("File processed successfully")

​
Status Broadcasting

#!/bin/bash
# Broadcast system status to all Yazi instances

while true; do
    DISK_USAGE=$(df -h / | awk 'NR==2 {print $5}')
    ya pub system-status --json="{\"disk_usage\": \"$DISK_USAGE\"}"
    sleep 60
done

​
Message Body Types

Pub/sub supports three body types:

​
String Body (--str)

Best for simple text messages. The string is JSON-encoded automatically: 
ya pub message --str="Hello world"
# Body: "Hello world"

​
JSON Body (--json)

Best for structured data. Must be valid JSON: 
ya pub data --json='{"key": "value", "count": 42}'
# Body: {"key": "value", "count": 42}

​
List Body (--list)

Best for multiple items. Creates a JSON array: 
ya pub items --list item1 item2 item3
# Body: ["item1", "item2", "item3"]

​
Empty Body

If no body options are specified, an empty message is sent: 
ya pub event-trigger
# Body: ""

​
Error Handling

Commands exit with status code 1 if:
  • Cannot connect to the target instance
  • Invalid instance ID (for pub-to)
  • Message fails to send
  • Invalid JSON in --json option
Example error: 
ya pub-to 99999 test --str="hello"
# Cannot send message: Connection refused

​
Environment Variables

​
YAZI_ID
string
Current Yazi instance ID.Used by pub to determine the target instance. Set automatically by Yazi.
​
YAZI_PID
string
Alternative to YAZI_ID.

​
See Also

  • emit - Send commands to Yazi instances
  • ya - Main CLI utility
  • yazi - Start Yazi with client ID

Build docs developers (and LLMs) love

Get started for freeTalk to us