LocalSend

Interactive file transfer between devices on the local network using real Telegram inline keyboard buttons. Works with any device running the LocalSend app (Android, iOS, Windows, macOS, Linux).

Install

The localsend-cli is a zero-dependency Python CLI. Install from GitHub:

CODEBLOCK0

Full docs: https://github.com/Chordlini/localsend-cli

Requires Python 3.8+ and openssl (for TLS).

---

Telegram Button Format

All menus MUST use OpenClaw's inline button format. Send buttons alongside your message using this structure:

CODEBLOCK1

• - Outer array = rows of buttons
• Inner array = buttons per row (max 3 per row for readability)
• Prefix all callback_data with ls: to namespace this skill
• When user taps a button, you receive: INLINECODE3

---

State Awareness (CRITICAL)

This skill uses conversational state. Track where you are in the flow:

State	Meaning	Next user input should be treated as...
INLINECODE4	No active flow	Normal message — respond normally
INLINECODE5

Asked user to drop/specify a file to send | The file to send — do NOT comment on it, describe it, or react to it. Immediately use it as the send payload. |
| awaiting_text | Asked user to type text to send | The text payload — send it, don't discuss it |
| awaiting_confirm | Waiting for send confirmation | Expect ls:confirm-send or ls:menu |
| receiving | Receiver is active | Monitor for incoming files |

RULES:

• - When in awaiting_file state and user sends an image/file/path → treat it as the file to send. Show confirmation buttons immediately.
• When in awaiting_text state and user types anything → treat it as the text to send.
• NEVER comment on, describe, or react to a file/image when you're in awaiting_file state.
• State resets to idle when user taps ls:menu or the flow completes.

---

On Trigger: Main Menu

When the user types /localsend or mentions sending/receiving files locally, send this message with real inline buttons:

Message:
CODEBLOCK2

Buttons:
CODEBLOCK3

Do NOT run any commands yet. Wait for the button tap.

---

Flow: Scan Devices

Trigger: callback_data: ls:devices or user says "scan", "discover", "find devices"

1. 1. Run:

CODEBLOCK4

1. 2. Devices found — create one button per device, plus Refresh and Back:

Message:
CODEBLOCK5

Buttons (one device per row):
CODEBLOCK6

1. 3. No devices found:

Message:
CODEBLOCK7

Buttons:
CODEBLOCK8

1. 4. User taps a device (callback_data: ls:dev:DEVICENAME) — store it as the selected target. Show action menu:

Message:
CODEBLOCK9

Buttons:

   buttons: [
     [
       { "text": "📄 Send File", "callback_data": "ls:sendfile" },
       { "text": "📝 Send Text", "callback_data": "ls:sendtext" }
     ],
     [
       { "text": "📦 Send Multiple", "callback_data": "ls:sendmulti" },
       { "text": "⬅️ Back", "callback_data": "ls:devices" }
     ]
   ]
   

---

Flow: Send

Trigger: INLINECODE19

Step 1 — Pick target device (if not already selected)

Run discover and show device picker (see Scan Devices flow above).

Step 2 — Choose what to send

Message:
CODEBLOCK11

Buttons:
CODEBLOCK12

Send File (callback_data: ls:sendfile)

1. 1. Ask: INLINECODE21
2. User provides file path or sends a file via chat
3. Get file size with stat or INLINECODE23
4. Confirm with buttons:

Message:
CODEBLOCK13

Buttons:
CODEBLOCK14

1. 5. On confirm, run:

CODEBLOCK15

1. 6. Report result:

Message:
CODEBLOCK16

Buttons:
CODEBLOCK17

Send Text (callback_data: ls:sendtext)

1. 1. Ask: INLINECODE25
2. User types their message
3. Write text to temp file, send:

   echo "user's text" > /tmp/localsend-text.txt
   localsend-cli send --to "Fast Potato" /tmp/localsend-text.txt
   rm /tmp/localsend-text.txt
   

1. 4. Confirm:

Message:
CODEBLOCK19

Buttons:
CODEBLOCK20

Send Multiple (callback_data: ls:sendmulti)

1. 1. Ask: INLINECODE27
2. User provides paths or pattern
3. Expand glob, list files with sizes:

Message:
CODEBLOCK21

Buttons:
CODEBLOCK22

1. 4. On confirm, run:

CODEBLOCK23

1. 5. Report:

Message:
CODEBLOCK24

Buttons:

   buttons: [
     [
       { "text": "📤 Send More", "callback_data": "ls:send" },
       { "text": "⬅️ Menu", "callback_data": "ls:menu" }
     ]
   ]
   

---

Flow: Receive

Trigger: callback_data: ls:receive or user says "receive", "start receiving", "listen"

Step 1 — Snapshot current files

CODEBLOCK26

Step 2 — Start receiver in background

CODEBLOCK27

Run with run_in_background: true. Store the task ID.

CRITICAL: --alias MUST come BEFORE receive (global flag).

Step 3 — Confirm ready with buttons

Message:
CODEBLOCK28

Buttons:
CODEBLOCK29

Step 4 — Monitor for incoming files

Poll every 3 seconds for new files:
CODEBLOCK30

Step 5 — Post-receive confirmation (MANDATORY)

When file(s) arrive, immediately present in chat with inline buttons.

Single file:

Message:
CODEBLOCK31

Buttons (contextual by file type):
CODEBLOCK32

Image file — show inline preview:

Message:

✅ Received from Fast Potato:
🖼️ screenshot.png — 2.1 MB

Include MEDIA:~/incoming/screenshot.png for inline preview.

Buttons:
CODEBLOCK34

Multiple files:

Message:
CODEBLOCK35

Buttons:
CODEBLOCK36

Contextual button rules by file type:

• - .zip, .tar.gz → add 📂 Extract button
• INLINECODE36, .jpg, .gif, .webp → show MEDIA: inline + INLINECODE40
• INLINECODE41 → add 📱 Install button
• INLINECODE43, .js, .py → add 👁️ Preview button
• website archives → add 🚀 Deploy button

Step 6 — Stop receiver

Trigger: INLINECODE48

1. 1. Kill the background task using stored task ID
2. Confirm:

Message:
CODEBLOCK37

Buttons:

   buttons: [
     [
       { "text": "📡 Restart", "callback_data": "ls:receive" },
       { "text": "⬅️ Menu", "callback_data": "ls:menu" }
     ]
   ]
   

---

Flow: Status Check

Trigger: INLINECODE49

Check if receiver is running and count new files:
CODEBLOCK39

Message:
CODEBLOCK40

Buttons:

buttons: [
  [
    { "text": "🛑 Stop", "callback_data": "ls:stop" },
    { "text": "📂 Show Files", "callback_data": "ls:showall" }
  ]
]

---

Callback Data Reference

callback_data	Action
INLINECODE50	Show main menu
INLINECODE51

Start send flow |
| ls:receive | Start receive flow |
| ls:devices | Discover devices |
| ls:dev:DEVICENAME | Select a specific device |
| ls:sendfile | Send single file |
| ls:sendtext | Send text message |
| ls:sendmulti | Send multiple files |
| ls:confirm-send | Confirm and execute send |
| ls:stop | Stop receiver |
| ls:status | Check receiver status |
| ls:extract | Extract received archive |
| ls:deploy | Deploy received website |
| ls:openfolder | Open save directory |
| ls:showall | List all received files |

---

CLI Reference

Command	Usage
Discover	INLINECODE65
Send

localsend-cli send --to "DEVICE" file1 file2 ... |
| Receive | localsend-cli --alias NAME receive --save-dir DIR -y |

Flag	Scope	Description
INLINECODE68	Global (before subcommand)	Device name to advertise
INLINECODE69

send | Target device (case-insensitive substring) |
| -t N | discover | Scan duration in seconds (use 2 for speed) |
| --json | discover | Machine-readable output |
| --save-dir DIR | receive | Save location (default: ~/Downloads) |
| -y | receive | Auto-accept transfers |

Troubleshooting

Problem	Fix
INLINECODE74	Move --alias BEFORE the subcommand
No devices found

Open LocalSend on target, same WiFi, screen on | | Port 53317 in use | Normal — CLI auto-falls back to 53318/53319 | | Transfer declined (403) | Use -y on receiver side | | Transfer hangs | Large file on slow WiFi — be patient |

Reference

• - CLI repo & docs: https://github.com/Chordlini/localsend-cli
• LocalSend protocol: references/protocol.md or https://github.com/localsend/protocol