feat(client): add ClearSelection API and CLI command

README.md

@@ -50,11 +50,11 @@ Legend:
 | Section | Proto Commands | Implemented | Coverage |
 | --- | ---: | ---: | ---: |
 | Common (base) | 6 | 4 | 67% |
-| Common editor/document | 23 | 12 | 52% |
+| Common editor/document | 23 | 13 | 57% |
 | Project manager | 5 | 3 | 60% |
 | Board editor (PCB) | 22 | 20 | 91% |
 | Schematic editor (dedicated proto commands) | 0 | 0 | n/a |
-| **Total** | **56** | **39** | **70%** |
+| **Total** | **56** | **40** | **71%** |
 
 ### Common (base)
 
@@ -88,7 +88,7 @@ Legend:
 | `GetSelection` | Implemented | `KiCadClient::get_selection_raw`, `KiCadClient::get_selection`, `KiCadClient::get_selection_summary`, `KiCadClient::get_selection_details` |
 | `AddToSelection` | Not yet | - |
 | `RemoveFromSelection` | Not yet | - |
-| `ClearSelection` | Not yet | - |
+| `ClearSelection` | Implemented | `KiCadClient::clear_selection_raw`, `KiCadClient::clear_selection` |
 | `HitTest` | Implemented | `KiCadClient::hit_test_item` |
 | `GetTitleBlockInfo` | Implemented | `KiCadClient::get_title_block_info` |
 | `SaveDocumentToString` | Implemented | `KiCadClient::get_board_as_string` |

docs/TEST_CLI.md

@@ -169,6 +169,12 @@ Show raw protobuf payload bytes for selected items:
 cargo run --bin kicad-ipc-cli -- selection-raw
 ```
 
+Clear current selection:
+
+```bash
+cargo run --bin kicad-ipc-cli -- clear-selection
+```
+
 Show pad-level netlist entries (footprint/pad/net):
 
 ```bash

src/client.rs

@@ -68,6 +68,7 @@ const CMD_CHECK_PADSTACK_PRESENCE_ON_LAYERS: &str =
     "kiapi.board.commands.CheckPadstackPresenceOnLayers";
 const CMD_INJECT_DRC_ERROR: &str = "kiapi.board.commands.InjectDrcError";
 const CMD_GET_SELECTION: &str = "kiapi.common.commands.GetSelection";
+const CMD_CLEAR_SELECTION: &str = "kiapi.common.commands.ClearSelection";
 const CMD_BEGIN_COMMIT: &str = "kiapi.common.commands.BeginCommit";
 const CMD_END_COMMIT: &str = "kiapi.common.commands.EndCommit";
 const CMD_GET_ITEMS: &str = "kiapi.common.commands.GetItems";
@@ -729,6 +730,33 @@ impl KiCadClient {
         decode_pcb_items(items)
     }
 
+    pub async fn clear_selection_raw(&self) -> Result<Vec<prost_types::Any>, KiCadError> {
+        let command = common_commands::ClearSelection {
+            header: Some(self.current_board_item_header().await?),
+        };
+
+        let response = self
+            .send_command(envelope::pack_any(&command, CMD_CLEAR_SELECTION))
+            .await?;
+
+        match envelope::unpack_any::<common_commands::SelectionResponse>(
+            &response,
+            RES_SELECTION_RESPONSE,
+        ) {
+            Ok(payload) => Ok(payload.items),
+            Err(KiCadError::UnexpectedPayloadType {
+                expected_type_url: _,
+                actual_type_url,
+            }) if actual_type_url == envelope::type_url(RES_PROTOBUF_EMPTY) => Ok(Vec::new()),
+            Err(err) => Err(err),
+        }
+    }
+
+    pub async fn clear_selection(&self) -> Result<SelectionSummary, KiCadError> {
+        let items = self.clear_selection_raw().await?;
+        Ok(summarize_selection(items))
+    }
+
     pub async fn get_pad_netlist(&self) -> Result<Vec<PadNetEntry>, KiCadError> {
         let footprint_items = self
             .get_items_raw(vec![common_types::KiCadObjectType::KotPcbFootprint as i32])

test-scripts/kicad-ipc-cli.rs

@@ -84,6 +84,7 @@ enum Command {
         action: CommitAction,
         message: String,
     },
+    ClearSelection,
     SelectionSummary,
     SelectionDetails,
     SelectionRaw,
@@ -418,6 +419,10 @@ async fn run() -> Result<(), KiCadError> {
                 .await?;
             println!("end_commit=ok action={}", action);
         }
+        Command::ClearSelection => {
+            let summary = client.clear_selection().await?;
+            println!("selection_total={}", summary.total_items);
+        }
         Command::SelectionSummary => {
             let summary = client.get_selection_summary().await?;
             println!("selection_total={}", summary.total_items);
@@ -1172,6 +1177,7 @@ fn parse_args_from(mut args: Vec<String>) -> Result<(CliConfig, Command), KiCadE
                 message,
             }
         }
+        "clear-selection" => Command::ClearSelection,
         "selection-summary" => Command::SelectionSummary,
         "selection-details" => Command::SelectionDetails,
         "selection-raw" => Command::SelectionRaw,
@@ -1637,7 +1643,7 @@ fn default_config() -> CliConfig {
 
 fn print_help() {
     println!(
-        "kicad-ipc-cli\n\nUSAGE:\n  cargo run --bin kicad-ipc-cli -- [--socket URI] [--token TOKEN] [--client-name NAME] [--timeout-ms N] <command> [command options]\n\nCOMMANDS:\n  ping                         Check IPC connectivity\n  version                      Fetch KiCad version\n  open-docs [--type <type>]    List open docs (default type: pcb)\n  project-path                 Get current project path from open PCB docs\n  board-open                   Exit non-zero if no PCB doc is open\n  net-classes                  List project netclass definitions\n  text-variables               List text variables for current board document\n  expand-text-variables        Expand variables in provided text values\n                               Options: --text <value> (repeatable)\n  text-extents                 Measure text bounding box\n                               Options: --text <value>\n  text-as-shapes               Convert text to rendered shapes\n                               Options: --text <value> (repeatable)\n  nets                         List board nets (requires one open PCB)\n  netlist-pads                 Emit pad-level netlist data (with footprint context)\n  items-by-id --id <uuid> ...  Show parsed details for specific item IDs\n  item-bbox --id <uuid> ...    Show bounding boxes for item IDs\n  hit-test --id <uuid> --x-nm <x> --y-nm <y> [--tolerance-nm <n>]\n                               Hit-test one item at a point\n  types-pcb                    List PCB KiCad object type IDs from proto enum\n  items-raw --type-id <id> ... Dump raw Any payloads for requested item type IDs\n  items-raw-all-pcb [--debug]  Dump all PCB item payloads across all PCB object types\n  pad-shape-polygon --pad-id <uuid> ... --layer-id <i32> [--debug]\n                               Dump pad polygons on a target layer\n  padstack-presence --item-id <uuid> ... --layer-id <i32> ... [--debug]\n                               Check padstack shape presence matrix across layers\n  title-block                  Show title block fields\n  board-as-string              Dump board as KiCad s-expression text\n  selection-as-string          Dump current selection as KiCad s-expression text\n  stackup                      Show typed board stackup\n  graphics-defaults            Show typed graphics defaults\n  appearance                   Show typed editor appearance settings\n  set-appearance --inactive-layer-display <normal|dimmed|hidden>\n                 --net-color-display <all|ratsnest|off>\n                 --board-flip <normal|flipped-x>\n                 --ratsnest-display <all-layers|visible-layers>\n                               Set editor appearance settings\n  inject-drc-error --severity <s> --message <text> [--x-nm <i64> --y-nm <i64>] [--item-id <uuid> ...]\n                               Inject a DRC marker (severity: warning|error|exclusion|ignore|info|action|debug|undefined)\n  refill-zones [--zone-id <uuid> ...]\n                               Refill all zones or a provided subset\n  netclass                     Show typed netclass map for current board nets\n  proto-coverage-board-read    Print board-read command coverage vs proto\n  board-read-report [--out P]  Write markdown board reconstruction report\n  enabled-layers               List enabled board layers\n  set-enabled-layers --copper-layer-count <u32> [--layer-id <i32> ...]\n                               Set enabled board layer set\n  active-layer                 Show active board layer\n  set-active-layer --layer-id <i32>\n                               Set active board layer\n  visible-layers               Show currently visible board layers\n  set-visible-layers --layer-id <i32> ...\n                               Set visible board layers\n  board-origin [--type <t>]    Show board origin (`grid` default, or `drill`)\n  set-board-origin --type <t> --x-nm <i64> --y-nm <i64>\n                               Set board origin (`grid` or `drill`)\n  refresh-editor [--frame <f>] Refresh a specific editor frame (default: pcb)\n  begin-commit                 Start staged commit and print commit ID\n  end-commit --id <uuid> [--action <commit|drop>] [--message <text>]\n                               End staged commit with commit/drop action\n  selection-summary            Show current selection item type counts\n  selection-details            Show parsed details for selected items\n  selection-raw                Show raw Any payload bytes for selected items\n  smoke                        ping + version + board-open summary\n  help                         Show help\n\nTYPES:\n  schematic | symbol | pcb | footprint | drawing-sheet | project\n"
+        "kicad-ipc-cli\n\nUSAGE:\n  cargo run --bin kicad-ipc-cli -- [--socket URI] [--token TOKEN] [--client-name NAME] [--timeout-ms N] <command> [command options]\n\nCOMMANDS:\n  ping                         Check IPC connectivity\n  version                      Fetch KiCad version\n  open-docs [--type <type>]    List open docs (default type: pcb)\n  project-path                 Get current project path from open PCB docs\n  board-open                   Exit non-zero if no PCB doc is open\n  net-classes                  List project netclass definitions\n  text-variables               List text variables for current board document\n  expand-text-variables        Expand variables in provided text values\n                               Options: --text <value> (repeatable)\n  text-extents                 Measure text bounding box\n                               Options: --text <value>\n  text-as-shapes               Convert text to rendered shapes\n                               Options: --text <value> (repeatable)\n  nets                         List board nets (requires one open PCB)\n  netlist-pads                 Emit pad-level netlist data (with footprint context)\n  items-by-id --id <uuid> ...  Show parsed details for specific item IDs\n  item-bbox --id <uuid> ...    Show bounding boxes for item IDs\n  hit-test --id <uuid> --x-nm <x> --y-nm <y> [--tolerance-nm <n>]\n                               Hit-test one item at a point\n  types-pcb                    List PCB KiCad object type IDs from proto enum\n  items-raw --type-id <id> ... Dump raw Any payloads for requested item type IDs\n  items-raw-all-pcb [--debug]  Dump all PCB item payloads across all PCB object types\n  pad-shape-polygon --pad-id <uuid> ... --layer-id <i32> [--debug]\n                               Dump pad polygons on a target layer\n  padstack-presence --item-id <uuid> ... --layer-id <i32> ... [--debug]\n                               Check padstack shape presence matrix across layers\n  title-block                  Show title block fields\n  board-as-string              Dump board as KiCad s-expression text\n  selection-as-string          Dump current selection as KiCad s-expression text\n  stackup                      Show typed board stackup\n  graphics-defaults            Show typed graphics defaults\n  appearance                   Show typed editor appearance settings\n  set-appearance --inactive-layer-display <normal|dimmed|hidden>\n                 --net-color-display <all|ratsnest|off>\n                 --board-flip <normal|flipped-x>\n                 --ratsnest-display <all-layers|visible-layers>\n                               Set editor appearance settings\n  inject-drc-error --severity <s> --message <text> [--x-nm <i64> --y-nm <i64>] [--item-id <uuid> ...]\n                               Inject a DRC marker (severity: warning|error|exclusion|ignore|info|action|debug|undefined)\n  refill-zones [--zone-id <uuid> ...]\n                               Refill all zones or a provided subset\n  netclass                     Show typed netclass map for current board nets\n  proto-coverage-board-read    Print board-read command coverage vs proto\n  board-read-report [--out P]  Write markdown board reconstruction report\n  enabled-layers               List enabled board layers\n  set-enabled-layers --copper-layer-count <u32> [--layer-id <i32> ...]\n                               Set enabled board layer set\n  active-layer                 Show active board layer\n  set-active-layer --layer-id <i32>\n                               Set active board layer\n  visible-layers               Show currently visible board layers\n  set-visible-layers --layer-id <i32> ...\n                               Set visible board layers\n  board-origin [--type <t>]    Show board origin (`grid` default, or `drill`)\n  set-board-origin --type <t> --x-nm <i64> --y-nm <i64>\n                               Set board origin (`grid` or `drill`)\n  refresh-editor [--frame <f>] Refresh a specific editor frame (default: pcb)\n  begin-commit                 Start staged commit and print commit ID\n  end-commit --id <uuid> [--action <commit|drop>] [--message <text>]\n                               End staged commit with commit/drop action\n  clear-selection              Clear current item selection\n  selection-summary            Show current selection item type counts\n  selection-details            Show parsed details for selected items\n  selection-raw                Show raw Any payload bytes for selected items\n  smoke                        ping + version + board-open summary\n  help                         Show help\n\nTYPES:\n  schematic | symbol | pcb | footprint | drawing-sheet | project\n"
     );
 }
 
@@ -2252,6 +2258,13 @@ mod tests {
         }
     }
 
+    #[test]
+    fn parse_args_parses_clear_selection() {
+        let (_, command) = parse_args_from(vec!["clear-selection".to_string()])
+            .expect("clear-selection should parse");
+        assert!(matches!(command, Command::ClearSelection));
+    }
+
     #[test]
     fn parse_args_parses_set_active_layer() {
         let (_, command) = parse_args_from(vec![