Back to Details

pikvm

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

PiKVM Remote Control

PiKVM远程控制

Control remote computers via PiKVM REST API with mouse, keyboard, and power management.
通过PiKVM REST API实现远程计算机的鼠标、键盘及电源管理控制。

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
  • 对远程机器进行截图
  • 移动鼠标并点击
  • 输入文本或按下键盘按键
  • 执行快捷键操作（如Cmd+Space、Ctrl+Alt+Del等）
  • 电源控制（开机/关机/重启）
  • 自动化远程桌面操作

Prerequisites

前置条件

bash
export PIKVM_URL=https://pikvm.example.com
export PIKVM_AUTH=admin:admin
bash
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.
  1. 访问你的PiKVM网页界面
  2. 默认凭证：
    admin:admin
注意： 当在包含管道的命令中使用
$VAR
时，请将包含
$VAR
的命令用
bash -c '...'
包裹。由于Claude Code的一个bug，直接使用管道时环境变量会被静默清除。

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)
鼠标坐标以屏幕中心为原点(0,0):
  • X轴负值=向左，正值=向右
  • Y轴负值=向上，正值=向下
对于1920x1080分辨率的屏幕：
  • 左上角：
    (-960, -540)
  • 中心：
    (0, 0)
  • 右下角：
    (960, 540)

Usage

使用方法

Take Screenshot

截图

bash
bash -c 'curl -k -s -o /tmp/screenshot.jpg -u "$PIKVM_AUTH" "${PIKVM_URL}/api/streamer/snapshot"'
bash
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
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"'
文本必须以原始正文形式发送，且设置
Content-Type: text/plain
:
bash
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
bash -c 'curl -k -s -X POST \
  -u "$PIKVM_AUTH" \
  "${PIKVM_URL}/api/hid/events/send_mouse_move?to_x=-500&to_y=-300"'
移动到绝对位置（0,0为屏幕中心）:
bash
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

鼠标点击

bash
undefined
bash
undefined

Press

按下

bash -c 'curl -k -s -X POST
-u "$PIKVM_AUTH"
"${PIKVM_URL}/api/hid/events/send_mouse_button?button=left&state=true"'
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"'
undefined
bash -c 'curl -k -s -X POST
-u "$PIKVM_AUTH"
"${PIKVM_URL}/api/hid/events/send_mouse_button?button=left&state=false"'
undefined

Press Key

按键操作

Press and release with 
state=true
then 
state=false
:
bash
undefined
通过先设置
state=true
再设置
state=false
来实现按下和释放：
bash
undefined

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"'
undefined
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"'
undefined

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

组合键操作（如Cmd+Space打开Spotlight）

Press all keys in order, then release in reverse:
bash
undefined
按顺序按下所有按键，然后反向释放：
bash
undefined

Press Cmd

按下Cmd

bash -c 'curl -k -s -X POST -u "$PIKVM_AUTH" "${PIKVM_URL}/api/hid/events/send_key?key=MetaLeft&state=true"'
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"'
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"'
bash -c 'curl -k -s -X POST -u "$PIKVM_AUTH" "${PIKVM_URL}/api/hid/events/send_key?key=Space&state=false"'

Release Cmd

释放Cmd

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

Mouse Scroll

鼠标滚动

bash
bash -c 'curl -k -s -X POST \
  -u "$PIKVM_AUTH" \
  "${PIKVM_URL}/api/hid/events/send_mouse_wheel?delta_x=0&delta_y=-50"'
bash
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
bash -c 'curl -k -s \
  -u "$PIKVM_AUTH" \
  "${PIKVM_URL}/api/info"' | jq .
bash
bash -c 'curl -k -s \
  -u "$PIKVM_AUTH" \
  "${PIKVM_URL}/api/info"' | jq .

ATX Power Control

ATX电源控制

bash
undefined
bash
undefined

Power on

开机

bash -c 'curl -k -s -X POST
-u "$PIKVM_AUTH"
"${PIKVM_URL}/api/atx/power?action=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"'
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"'

---
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 (-)
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端点参考

EndpointMethodDescription
/api/streamer/snapshot
GETScreenshot (JPEG)
/api/hid/print
POSTType text (body: raw text)
/api/hid/events/send_mouse_move
POSTMove mouse (
to_x
, 
to_y
)
/api/hid/events/send_mouse_button
POSTClick (
button
, 
state
)
/api/hid/events/send_mouse_wheel
POSTScroll (
delta_x
, 
delta_y
)
/api/hid/events/send_key
POSTKey press (
key
, 
state
)
/api/atx/power
POSTPower control (
action
)
/api/info
GETDevice info
/api/atx
GETATX status
端点请求方法描述
/api/streamer/snapshot
GET截图（JPEG格式）
/api/hid/print
POST输入文本（正文：原始文本）
/api/hid/events/send_mouse_move
POST移动鼠标（参数：
to_x
, 
to_y
）
/api/hid/events/send_mouse_button
POST鼠标点击（参数：
button
, 
state
）
/api/hid/events/send_mouse_wheel
POST鼠标滚动（参数：
delta_x
, 
delta_y
）
/api/hid/events/send_key
POST按键操作（参数：
key
, 
state
）
/api/atx/power
POST电源控制（参数：
action
）
/api/info
GET获取设备信息
/api/atx
GET获取ATX状态

API Reference

API参考