pub, pub-to & sub

Publish-subscribe messaging between Yazi instances

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