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

1. Access your PiKVM web interface
2. 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 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

API Reference

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