pikl/examples/ipc-remote.md

IPC Remote Control

Interactive demo of pikl's IPC socket. Run pikl in one terminal, control it from another. Watch the menu respond in real time.

Prerequisites

• socat for socket I/O (pacman -S socat / brew install socat)
• python3 for pretty-printing JSON responses (optional, falls back to raw output)

Quick start

Terminal 1: start pikl with IPC enabled.

echo -e "alpha\nbeta\ngamma\ndelta\nepsilon" | pikl --ipc --session demo

Terminal 2: connect the remote control.

./examples/ipc-remote.sh demo

What you can do

The remote gives you single-key commands:

Key	Action
j / k	Move cursor down / up
g / G	Jump to top / bottom
f	Set filter text (then type the query)
F	Clear filter
Space	Toggle select on current item
a	Select all
c	Clear selections
s	Print current menu state (JSON)
S	Print current selection (JSON)
+	Add new items interactively
r	Replace all items
Enter	Confirm selection (exits pikl)
q	Cancel (exits pikl)
x	Exit remote without affecting pikl

Things to try

1. Press j a few times and watch the cursor move in the pikl terminal.
2. Press s to see the state, including cursor position and item count.
3. Press f, type al, and watch the filter narrow the list.
4. Press F to clear the filter.
5. Press + and add a few items. They appear in the pikl terminal immediately.
6. Press Space a couple times to toggle selections, then S to see what's selected.
7. Press Enter to confirm. pikl exits and prints the selection.

How it works

The remote sends newline-delimited JSON commands to pikl's Unix socket using socat. Write commands (move, filter, add items) are fire-and-forget. Read commands (get_state, get_selection) wait for a JSON response.

The socket path for a named session is /run/user/$UID/pikl-{session}.sock. Without --session, pikl uses the PID: /run/user/$UID/pikl-{pid}.sock.

Using socat directly

You don't need the remote script. Any tool that speaks Unix sockets works:

# Query state
echo '{"action":"get_state","id":"1"}' | socat - UNIX-CONNECT:/run/user/$(id -u)/pikl-demo.sock

# Move cursor down
echo '{"action":"move_down"}' | socat -t 0.1 - UNIX-CONNECT:/run/user/$(id -u)/pikl-demo.sock

# Add items
echo '{"action":"add_items","items":["foo","bar"]}' | socat -t 0.1 - UNIX-CONNECT:/run/user/$(id -u)/pikl-demo.sock