---
name: hwpod-cli
description: Use HWLAB HWPOD from a code agent runner for hardware-development tasks. The hwpod-cli skill resolves an HWPOD by hwpod-id through the HWLAB runtime service, submits hwpod-node-ops through hwlab-api, and waits for hwpod-node results.
---

# hwpod-cli

This skill follows Skill(cli-spec). It is the standard task entry for operating an HWPOD from the HWLAB v0.2 Code Agent workspace.

## Standard Path

```text
hwpod from PATH
  -> tools/hwpod-cli.ts
    -> runtime HWPOD registry by hwpod-id
    -> compiler-backed hwpod-node-ops plan
      -> /v1/hwpod-node-ops on hwlab-api
        -> hwpod-node on the host side
```

The HWPOD definition is runtime service state. The standard runner contract is `--hwpod-id <id>` plus `--workspace-path <run-worktree>` when the task is bound to a run-local workspace. A task may provide the complete `hwpodWorkspaceArgs` string; reuse it exactly. `--spec <path>` is only an explicit debug/import path for a local exported YAML, not the default runner contract.

## Commands

- Inspect the HWPOD path: `hwpod inspect --hwpod-id d601-f103-v2 --workspace-path <run-worktree>`.
- Workspace search/read/edit: use `hwpod workspace ls|cat|read|rg|grep|search|apply-patch --hwpod-id d601-f103-v2 --workspace-path <run-worktree>`. `read` is an alias for `cat`; `grep` and `search` are aliases for `rg`; `--file` and `--remote-path` are accepted as path aliases for file-oriented commands.
- For symbol lookup or ARM-2D header hunting, prefer `hwpod workspace rg <pattern> [path] --context 3 --hwpod-id d601-f103-v2 --workspace-path <run-worktree>` instead of `cat | grep`.
- Build/download/reset: use `hwpod build`, `hwpod download`, and `hwpod reset`; the compiler must translate these through existing file ops and `cmd.run` where possible.
- Keil async status: after build/download returns a job id, use separate short `hwpod job status <jobId> --hwpod-id d601-f103-v2 --workspace-path <run-worktree>` calls instead of shell polling wrappers such as `sleep &&`, `timeout`, `watch`, `head`, pipes, or loops.
- UART read: use `hwpod uart read --hwpod-id d601-f103-v2 --workspace-path <run-worktree> --port uart1`; the compiler runs the configured serial-monitor CLI through `cmd.run`.

## Boundaries

- Do not pass manual API URLs in locked AgentRun runtimes. Let `HWLAB_RUNTIME_API_URL` / `HWLAB_RUNTIME_NAMESPACE` select the current lane.
- Do not put full `hwpod-spec` on `hwpod-node`. The node only accepts `hwpod-node-ops`.
- Do not create, copy, restore, or repair runner-local `.hwlab/hwpod-spec.yaml` as a workaround. Use `hwpod-id` through the runtime service.
- Do not use deprecated workspace mutation commands (`workspace write`, `replace`, or `insert-after`) for normal source edits. Use `workspace apply-patch`.
- Treat `cmd.run` as the full-capability host execution op. Do not request new hwpod-node ops for build, download, job status, UART, PowerShell/cmd passthrough, or tool maintenance; improve `hwpod-compiler-cli` / `hwpod-cli` combinations first.
- Use workspace file operations for subject text edits. Do not use PowerShell/cmd heredocs for normal source edits unless debugging `cmd.run` itself.
- For multi-line edits, prefer `hwpod workspace apply-patch` with a Codex/UniDesk apply_patch v2 envelope from stdin or `--patch-content`. Put file paths in `*** Update File:` / `*** Add File:` / `*** Delete File:` headers. Do not pass raw unified diff (`---`, `+++`, `@@ -N`) as the whole patch; HWPOD deliberately rejects that format with a clear hint.
- If HWPOD returns a blocker, report and fix that blocker in this path.