From 5f37c40aec04f5b3e4a350d6cf225fb01826e12c Mon Sep 17 00:00:00 2001
From: Milind Sharma <milindsharma8@gmail.com>
Date: Wed, 18 Feb 2026 22:49:15 +0800
Subject: [PATCH] docs: add test CLI runbook

---
 README.md        |  4 +++
 docs/TEST_CLI.md | 80 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 84 insertions(+)
 create mode 100644 docs/TEST_CLI.md

diff --git a/README.md b/README.md
index 6222a35..0b20abe 100644
--- a/README.md
+++ b/README.md
@@ -13,3 +13,7 @@ Early scaffold phase. Core architecture + step-by-step implementation plan:
 1. Async-first layered client (`v0.1.0`)
 2. Full PCB read surface + trace write capability (`v0.1.0`)
 3. Blocking wrapper parity (`v0.2.0`)
+
+## Local Testing
+
+- CLI runbook: `/Users/milindsharma/Developer/kicad-oss/kicad-ipc-rust/docs/TEST_CLI.md`
diff --git a/docs/TEST_CLI.md b/docs/TEST_CLI.md
new file mode 100644
index 0000000..fccf6f4
--- /dev/null
+++ b/docs/TEST_CLI.md
@@ -0,0 +1,80 @@
+# Test CLI Runbook
+
+CLI binary path:
+- `test-scripts/kicad-ipc-cli.rs`
+
+Run help:
+
+```bash
+cargo run --bin kicad-ipc-cli -- help
+```
+
+## Prereqs
+
+1. KiCad running.
+2. API socket available (`KICAD_API_SOCKET` optional; auto-default works for typical setup).
+3. For board-specific checks: PCB Editor has a board open.
+
+## Commands
+
+Ping:
+
+```bash
+cargo run --bin kicad-ipc-cli -- ping
+```
+
+Version:
+
+```bash
+cargo run --bin kicad-ipc-cli -- version
+```
+
+List open PCB docs:
+
+```bash
+cargo run --bin kicad-ipc-cli -- open-docs --type pcb
+```
+
+Check board open:
+
+```bash
+cargo run --bin kicad-ipc-cli -- board-open
+```
+
+Get current project path (derived from open PCB docs):
+
+```bash
+cargo run --bin kicad-ipc-cli -- project-path
+```
+
+Smoke check:
+
+```bash
+cargo run --bin kicad-ipc-cli -- smoke
+```
+
+## Common Flags
+
+Custom socket:
+
+```bash
+cargo run --bin kicad-ipc-cli -- --socket ipc:///tmp/kicad/api.sock ping
+```
+
+Custom token:
+
+```bash
+cargo run --bin kicad-ipc-cli -- --token "$KICAD_API_TOKEN" version
+```
+
+Custom timeout:
+
+```bash
+cargo run --bin kicad-ipc-cli -- --timeout-ms 5000 ping
+```
+
+## Failure Hints
+
+- `Socket not available`: open KiCad + project/board; verify socket path.
+- `BoardNotOpen`: open a board in PCB Editor.
+- `AS_UNHANDLED`: command not enabled/handled in current KiCad build/config.