> ## 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.

# 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

```bash theme={null}
ya pub <KIND> [OPTIONS]
```

### Arguments

<ParamField path="KIND" type="string" required>
  Kind of message to publish.

  This is a custom identifier for your message type. It should be unique and descriptive.

  ```bash theme={null}
  ya pub file-changed
  ya pub custom-event
  ya pub build-complete
  ```
</ParamField>

### Options

<ParamField path="--str" type="string" optional>
  Send the message with a string body.

  The string will be JSON-encoded.

  ```bash theme={null}
  ya pub greeting --str="Hello, Yazi!"
  ```
</ParamField>

<ParamField path="--json" type="string" optional>
  Send the message with a JSON body.

  The JSON string should be valid JSON and will be sent as-is.

  ```bash theme={null}
  ya pub config-update --json='{"theme": "dark", "line_numbers": true}'
  ```
</ParamField>

<ParamField path="--list" type="string[]" optional>
  Send the message as a list of strings.

  Multiple values can be provided, and they will be sent as a JSON array.

  ```bash theme={null}
  ya pub files-selected --list file1.txt file2.txt file3.txt

  # Results in: ["file1.txt", "file2.txt", "file3.txt"]
  ```
</ParamField>

### Examples

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

```bash theme={null}
ya pub-to <RECEIVER> <KIND> [OPTIONS]
```

### Arguments

<ParamField path="RECEIVER" type="number" required>
  Receiver instance ID.

  The client ID of the target Yazi instance.

  ```bash theme={null}
  ya pub-to 12345 notification --str="Hello!"
  ```
</ParamField>

<ParamField path="KIND" type="string" required>
  Kind of message to publish.
</ParamField>

### Options

Same as `pub` command:

* `--str` - String message body
* `--json` - JSON message body
* `--list` - List of strings

### Examples

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

```bash theme={null}
ya sub <KINDS>
```

### Arguments

<ParamField path="KINDS" type="string" required>
  Kinds of messages to subscribe to, separated by commas.

  Multiple message kinds can be specified to listen for different event types.

  ```bash theme={null}
  # Subscribe to single message kind
  ya sub file-changed

  # Subscribe to multiple message kinds
  ya sub file-changed,build-complete,notification
  ```
</ParamField>

### 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

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

```bash theme={null}
# String message
"Hello, Yazi!"

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

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

## Use Cases

### File Watching Integration

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

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

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

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

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

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

```bash theme={null}
ya pub message --str="Hello world"
# Body: "Hello world"
```

### JSON Body (`--json`)

Best for structured data. Must be valid JSON:

```bash theme={null}
ya pub data --json='{"key": "value", "count": 42}'
# Body: {"key": "value", "count": 42}
```

### List Body (`--list`)

Best for multiple items. Creates a JSON array:

```bash theme={null}
ya pub items --list item1 item2 item3
# Body: ["item1", "item2", "item3"]
```

### Empty Body

If no body options are specified, an empty message is sent:

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

```bash theme={null}
ya pub-to 99999 test --str="hello"
# Cannot send message: Connection refused
```

## Environment Variables

<ParamField path="YAZI_ID" type="string">
  Current Yazi instance ID.

  Used by `pub` to determine the target instance. Set automatically by Yazi.
</ParamField>

<ParamField path="YAZI_PID" type="string">
  Alternative to `YAZI_ID`.
</ParamField>

## See Also

* [emit](emit) - Send commands to Yazi instances
* [ya](ya) - Main CLI utility
* [yazi](yazi) - Start Yazi with client ID