79 lines
2.4 KiB
Markdown
79 lines
2.4 KiB
Markdown
# 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.
|
|
|
|
```sh
|
|
echo -e "alpha\nbeta\ngamma\ndelta\nepsilon" | pikl --ipc --session demo
|
|
```
|
|
|
|
**Terminal 2:** connect the remote control.
|
|
|
|
```sh
|
|
./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:
|
|
|
|
```sh
|
|
# 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
|
|
```
|