pikasTech-HWLAB/skills/device-pod-cli/SKILL.md

name, description, version

name	description	version
device-pod-cli	Use the HWLAB internal device-pod CLI from a HWLAB code agent runner to operate a profiled target workspace, debug probe, and I/O probe through hwlab-gateway and device-host-cli.	0.1.0-mvp

Device Pod CLI

Skill(cli-spec)

Scope: this skill is only for HWLAB-internal code agent runners inside the HWLAB runtime, such as /workspace/hwlab sessions running from the G14 DEV or PROD images. It does not apply to external UniDesk developer workspaces or third-party machines; those environments must not treat this skill as a general hardware control contract.

Use this skill when the task mentions device-pod-cli, device-pod, device-host-cli, HWLAB device-pod profile files, Keil build/download through a device pod, debug probe control, or I/O probe reads such as UART boot logs.

Runtime Contract

• The preinstalled CLI entrypoint is node /app/skills/device-pod-cli/scripts/device-pod-cli.mjs.
• The canonical implementation is /app/tools/device-pod-cli.mjs; the skill script is only a stable preinstalled wrapper for code agent runners.
• The packaged Windows host CLI asset is /app/skills/device-pod-cli/assets/device-host-cli.mjs. It is bundled with this skill so a runner can send the exact tested host-side CLI to a new Windows hardware PC before the first device-pod operation.
• Profiles are read from .device-pod/<devicePodId>.json in the current code agent workspace, or from DEVICE_POD_PROFILE when a task explicitly points to a profile file.
• The CLI calls HWLAB cloud-api hardware.invoke.shell, which dispatches to an outbound hwlab-gateway session and then to the user PC side device-host-cli. Do not call gateway, serial ports, Keil, pyOCD, DAPLink, or Windows shell directly when the profiled device-pod path is available.
• device-host-cli is expected to be self-contained on the user PC. Keil, serial-monitor, mklink, and other skills can be implementation references, but are not runtime dependencies of this HWLAB runner skill.

Windows Host CLI Bootstrap

Do not run a separate installer. To bring up a new Windows hardware PC, send the packaged asset to the target workspace through the existing cmd passthrough path, then start it through the same cmd passthrough path.

Target layout:

<windows-workspace>\tools\device-host-cli.mjs
<windows-workspace>\.device-pod\<devicePodId>.json

When the UniDesk Windows maintenance route is available, the file transfer may use the same remote channel that backs cmd passthrough. In HWLAB coder images, /app/tools/tran.mjs is the stable contract entrypoint; /app/tools/hwlab-gateway-tran.mjs is only the compatible explicit wrapper for the same transport. If the compatible wrapper exists but /app/tools/tran.mjs is missing, report a CI/CD preinstall gap instead of adding a device-pod workaround.

node /app/tools/tran.mjs <gatewaySessionId>:/d/Work/HWLAB-workspace upload /app/skills/device-pod-cli/assets/device-host-cli.mjs tools/device-host-cli.mjs
node /app/tools/tran.mjs <gatewaySessionId>:/d/Work/HWLAB-workspace cmd -- node tools\\device-host-cli.mjs health

When only HWLAB gateway hardware.invoke.shell is available, send the asset bytes as bounded base64 chunks through cmd/PowerShell into tools\device-host-cli.mjs, then verify with:

node tools\device-host-cli.mjs health

After that, device-pod-cli should use the profile's hostCli, normally node tools\device-host-cli.mjs, and should not depend on any Windows skill directory at runtime.

Commands

All commands emit JSON and must remain short-running. Use build start / build status and download start / download status style host jobs for long operations instead of holding one gateway request open.

node /app/skills/device-pod-cli/scripts/device-pod-cli.mjs health
node /app/skills/device-pod-cli/scripts/device-pod-cli.mjs device-pod-71-freq:workspace:/ ls
node /app/skills/device-pod-cli/scripts/device-pod-cli.mjs device-pod-71-freq:workspace:/ rg main
node /app/skills/device-pod-cli/scripts/device-pod-cli.mjs device-pod-71-freq:workspace:/ apply-patch --approved --reason "DEV edit" < patch.diff
node /app/skills/device-pod-cli/scripts/device-pod-cli.mjs device-pod-71-freq:workspace:/ build start
node /app/skills/device-pod-cli/scripts/device-pod-cli.mjs device-pod-71-freq:workspace:/ build status <jobId>
node /app/skills/device-pod-cli/scripts/device-pod-cli.mjs device-pod-71-freq:debug-probe chip-id
node /app/skills/device-pod-cli/scripts/device-pod-cli.mjs device-pod-71-freq:debug-probe download start --approved --reason "DEV smoke"
node /app/skills/device-pod-cli/scripts/device-pod-cli.mjs device-pod-71-freq:debug-probe download status <jobId>
node /app/skills/device-pod-cli/scripts/device-pod-cli.mjs device-pod-71-freq:io-probe:/uart/1 ports
node /app/skills/device-pod-cli/scripts/device-pod-cli.mjs device-pod-71-freq:io-probe:/uart/1 read

Safety

• Mutating operations such as workspace patching, download, reset, and I/O write require --approved --reason <text> before the CLI dispatches anything.
• io-probe:/inner/... is intentionally distinct from external physical I/O paths such as io-probe:/uart/1; do not use internal target state as evidence for external UART/GPIO observations.
• Keep the gateway as transport only. Do not add a generic cmd operation to device-pod-cli; add a named device-pod operation instead.
• If the CLI returns profile-missing, profile-invalid, or approval-required, fix that blocker first rather than guessing a default device or falling back to arbitrary shell commands.