pikvm-remote-control

name	pikvm-remote-control
description	Remote KVM control via PiKVM REST API. Use for controlling remote computers through PiKVM - taking screenshots, moving mouse, clicking, typing text, pressing keys, keyboard shortcuts, scrolling, or power management.

PiKVM Remote Control

Control remote computers via PiKVM REST API with mouse, keyboard, and power management.

When to Use

• Take screenshots of remote machine
• Move mouse and click
• Type text or press keyboard keys
• Execute keyboard shortcuts (Cmd+Space, Ctrl+Alt+Del, etc.)
• Power control (on/off/reset)
• Automate remote desktop operations

Prerequisites

export PIKVM_URL=https://pikvm.example.com
export PIKVM_AUTH=admin:admin

Get Credentials

• Access your PiKVM web interface.
• Default credentials: admin:admin.

Important: When using $VAR in a command that pipes to another command, wrap the command containing $VAR in bash -c '...'. Due to a Claude Code bug, environment variables are silently cleared when pipes are used directly.

Coordinate System

Mouse coordinates use screen center as origin (0,0):

• Negative X = left, Positive X = right
• Negative Y = up, Positive Y = down

For a 1920x1080 screen:

• Top-left: (-960, -540)
• Center: (0, 0)
• Bottom-right: (960, 540)

Usage

Take Screenshot

bash -c 'curl -k -s -o /tmp/screenshot.jpg -u "$PIKVM_AUTH" "${PIKVM_URL}/api/streamer/snapshot"'

Type Text

Text must be sent as raw body with Content-Type: text/plain:

bash -c 'curl -k -s -X POST \
  -H "Content-Type: text/plain" \
  -u "$PIKVM_AUTH" \
  -d "Hello World" \
  "${PIKVM_URL}/api/hid/print?limit=0"'

Move Mouse

Move to absolute position (0,0 = screen center):

bash -c 'curl -k -s -X POST \
  -u "$PIKVM_AUTH" \
  "${PIKVM_URL}/api/hid/events/send_mouse_move?to_x=-500&to_y=-300"'

Mouse Click

# Press
bash -c 'curl -k -s -X POST \
  -u "$PIKVM_AUTH" \
  "${PIKVM_URL}/api/hid/events/send_mouse_button?button=left&state=true"'

# Release
bash -c 'curl -k -s -X POST \
  -u "$PIKVM_AUTH" \
  "${PIKVM_URL}/api/hid/events/send_mouse_button?button=left&state=false"'

Press Key

Press and release with state=true then state=false:

# Press Enter
bash -c 'curl -k -s -X POST \
  -u "$PIKVM_AUTH" \
  "${PIKVM_URL}/api/hid/events/send_key?key=Enter&state=true"'

bash -c 'curl -k -s -X POST \
  -u "$PIKVM_AUTH" \
  "${PIKVM_URL}/api/hid/events/send_key?key=Enter&state=false"'

Key Combo (e.g., Cmd+Space for Spotlight)

Press all keys in order, then release in reverse:

# Press Cmd
bash -c 'curl -k -s -X POST -u "$PIKVM_AUTH" "${PIKVM_URL}/api/hid/events/send_key?key=MetaLeft&state=true"'

# Press Space
bash -c 'curl -k -s -X POST -u "$PIKVM_AUTH" "${PIKVM_URL}/api/hid/events/send_key?key=Space&state=true"'

# Release Space
bash -c 'curl -k -s -X POST -u "$PIKVM_AUTH" "${PIKVM_URL}/api/hid/events/send_key?key=Space&state=false"'

# Release Cmd
bash -c 'curl -k -s -X POST -u "$PIKVM_AUTH" "${PIKVM_URL}/api/hid/events/send_key?key=MetaLeft&state=false"'

Mouse Scroll

bash -c 'curl -k -s -X POST \
  -u "$PIKVM_AUTH" \
  "${PIKVM_URL}/api/hid/events/send_mouse_wheel?delta_x=0&delta_y=-50"'

Get Device Info

bash -c 'curl -k -s \
  -u "$PIKVM_AUTH" \
  "${PIKVM_URL}/api/info"' | jq .

ATX Power Control

# Power on
bash -c 'curl -k -s -X POST \
  -u "$PIKVM_AUTH" \
  "${PIKVM_URL}/api/atx/power?action=on"'

# Power off
bash -c 'curl -k -s -X POST -u "$PIKVM_AUTH" "${PIKVM_URL}/api/atx/power?action=off"'

# Hard reset
bash -c 'curl -k -s -X POST -u "$PIKVM_AUTH" "${PIKVM_URL}/api/atx/power?action=reset_hard"'

Common Key Names

• MetaLeft (Cmd), ControlLeft, AltLeft, ShiftLeft
• Enter, Space, Escape, Tab, Backspace, Delete
• ArrowUp, ArrowDown, ArrowLeft, ArrowRight
• KeyA-KeyZ, Digit0-Digit9, F1-F12
• PageUp, PageDown, Home, End
• Equal (+), Minus (-)

API Endpoints Reference

Endpoint	Method	Description
/api/streamer/snapshot	GET	Screenshot (JPEG)
/api/hid/print	POST	Type text (body: raw text)
/api/hid/events/send_mouse_move	POST	Move mouse (to_x, to_y)
/api/hid/events/send_mouse_button	POST	Click (button, state)
/api/hid/events/send_mouse_wheel	POST	Scroll (delta_x, delta_y)
/api/hid/events/send_key	POST	Key press (key, state)
/api/atx/power	POST	Power control (action)
/api/info	GET	Device info
/api/atx	GET	ATX status

API Reference

Official docs: https://docs.pikvm.org/api/