kicad-ipc-rs/docs/TEST_CLI.md

Test CLI Runbook

CLI binary path:

• test-scripts/kicad-ipc-cli.rs

Run help:

cargo run --features blocking --bin kicad-ipc-cli -- help

The CLI uses KiCadClientBlocking and validates the sync wrapper end-to-end.

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:

cargo run --features blocking --bin kicad-ipc-cli -- ping

Version:

cargo run --features blocking --bin kicad-ipc-cli -- version

Resolve KiCad binary path (default kicad-cli):

cargo run --features blocking --bin kicad-ipc-cli -- kicad-binary-path --binary-name kicad-cli

Resolve plugin settings path (default identifier kicad-ipc-rust):

cargo run --features blocking --bin kicad-ipc-cli -- plugin-settings-path --identifier kicad-ipc-rust

List open PCB docs:

cargo run --features blocking --bin kicad-ipc-cli -- open-docs --type pcb

Check board open:

cargo run --features blocking --bin kicad-ipc-cli -- board-open

List nets:

cargo run --features blocking --bin kicad-ipc-cli -- nets

List vias with typed via kind and layer span:

cargo run --features blocking --bin kicad-ipc-cli -- vias

List project net classes:

cargo run --features blocking --bin kicad-ipc-cli -- net-classes

Write current net classes back with selected merge mode:

cargo run --features blocking --bin kicad-ipc-cli -- set-net-classes --merge-mode merge

List text variables for current board document:

cargo run --features blocking --bin kicad-ipc-cli -- text-variables

Set text variables:

cargo run --features blocking --bin kicad-ipc-cli -- set-text-variables --merge-mode merge --var REV=A

Expand text variables in one or more input strings:

cargo run --features blocking --bin kicad-ipc-cli -- expand-text-variables --text "${TITLE}" --text "${REVISION}"

Measure text extents:

cargo run --features blocking --bin kicad-ipc-cli -- text-extents --text "R1"

Convert text to shape primitives:

cargo run --features blocking --bin kicad-ipc-cli -- text-as-shapes --text "R1" --text "C5"

List enabled board layers:

cargo run --features blocking --bin kicad-ipc-cli -- enabled-layers

Set enabled board layers:

cargo run --features blocking --bin kicad-ipc-cli -- set-enabled-layers --copper-layer-count 2 --layer-id 47 --layer-id 52

Show active layer:

cargo run --features blocking --bin kicad-ipc-cli -- active-layer

Set active layer:

cargo run --features blocking --bin kicad-ipc-cli -- set-active-layer --layer-id 0

Show visible layers:

cargo run --features blocking --bin kicad-ipc-cli -- visible-layers

Set visible layers:

cargo run --features blocking --bin kicad-ipc-cli -- set-visible-layers --layer-id 0 --layer-id 31

Show board origin (grid origin by default):

cargo run --features blocking --bin kicad-ipc-cli -- board-origin

Show drill origin:

cargo run --features blocking --bin kicad-ipc-cli -- board-origin --type drill

Set board origin:

cargo run --features blocking --bin kicad-ipc-cli -- set-board-origin --type grid --x-nm 1000000 --y-nm 2000000

Refresh PCB editor:

cargo run --features blocking --bin kicad-ipc-cli -- refresh-editor --frame pcb

If your KiCad build does not expose this handler yet, this call may return AS_UNHANDLED.

Start a staged commit and print commit ID:

cargo run --features blocking --bin kicad-ipc-cli -- --client-name write-test begin-commit

End a staged commit:

cargo run --features blocking --bin kicad-ipc-cli -- --client-name write-test end-commit --id <commit-id> --action drop --message "cli test cleanup"

Save current board document:

cargo run --features blocking --bin kicad-ipc-cli -- save-doc

Save a copy of current board document:

cargo run --features blocking --bin kicad-ipc-cli -- save-copy --path /tmp/example.kicad_pcb --overwrite --include-project

Revert current board document from disk:

cargo run --features blocking --bin kicad-ipc-cli -- revert-doc

Run a raw KiCad tool action:

cargo run --features blocking --bin kicad-ipc-cli -- run-action --action pcbnew.InteractiveSelection.ClearSelection

Create raw Any item payload(s):

cargo run --features blocking --bin kicad-ipc-cli -- create-items --item type.googleapis.com/kiapi.board.types.Text=<hex_payload>

Update raw Any item payload(s):

cargo run --features blocking --bin kicad-ipc-cli -- update-items --item type.googleapis.com/kiapi.board.types.Text=<hex_payload>

Delete items by ID:

cargo run --features blocking --bin kicad-ipc-cli -- delete-items --id <uuid> --id <uuid>

Parse and create items from s-expression:

cargo run --features blocking --bin kicad-ipc-cli -- parse-create-items --contents "(kicad_pcb (version 20240108))"

Show summary of current PCB selection by item type:

cargo run --features blocking --bin kicad-ipc-cli -- selection-summary

Show parsed details for currently selected items:

cargo run --features blocking --bin kicad-ipc-cli -- selection-details

Show raw protobuf payload bytes for selected items:

cargo run --features blocking --bin kicad-ipc-cli -- selection-raw

Add items to current selection:

cargo run --features blocking --bin kicad-ipc-cli -- add-to-selection --id <uuid> --id <uuid>

Remove items from current selection:

cargo run --features blocking --bin kicad-ipc-cli -- remove-from-selection --id <uuid> --id <uuid>

Clear current selection:

cargo run --features blocking --bin kicad-ipc-cli -- clear-selection

Show pad-level netlist entries (footprint/pad/net):

cargo run --features blocking --bin kicad-ipc-cli -- netlist-pads

Show parsed details for specific item IDs:

cargo run --features blocking --bin kicad-ipc-cli -- items-by-id --id <uuid> --id <uuid>

Show item bounding boxes:

cargo run --features blocking --bin kicad-ipc-cli -- item-bbox --id <uuid>

Include child text in the bounding box (for items such as footprints):

cargo run --features blocking --bin kicad-ipc-cli -- item-bbox --id <uuid> --include-text

Run hit-test on a specific item:

cargo run --features blocking --bin kicad-ipc-cli -- hit-test --id <uuid> --x-nm <x> --y-nm <y> --tolerance-nm 0

List all PCB object type IDs from the proto enum:

cargo run --features blocking --bin kicad-ipc-cli -- types-pcb

Dump raw item payloads for one or more PCB object type IDs:

cargo run --features blocking --bin kicad-ipc-cli -- items-raw --type-id 11 --type-id 13 --debug

Dump raw payloads for all PCB object classes:

cargo run --features blocking --bin kicad-ipc-cli -- items-raw-all-pcb --debug

Check whether pads/vias have flashed padstack shapes on specific layers:

cargo run --features blocking --bin kicad-ipc-cli -- padstack-presence --item-id <uuid> --layer-id 3 --layer-id 34 --debug

Get polygonized pad shape(s) on a specific layer:

cargo run --features blocking --bin kicad-ipc-cli -- pad-shape-polygon --pad-id <uuid> --layer-id 3 --debug

Dump board text (KiCad s-expression):

cargo run --features blocking --bin kicad-ipc-cli -- board-as-string

Dump selection text (KiCad s-expression):

cargo run --features blocking --bin kicad-ipc-cli -- selection-as-string

Dump title block fields:

cargo run --features blocking --bin kicad-ipc-cli -- title-block

Show typed stackup/graphics/appearance:

cargo run --features blocking --bin kicad-ipc-cli -- stackup
cargo run --features blocking --bin kicad-ipc-cli -- update-stackup
cargo run --features blocking --bin kicad-ipc-cli -- graphics-defaults
cargo run --features blocking --bin kicad-ipc-cli -- appearance

Set editor appearance:

cargo run --features blocking --bin kicad-ipc-cli -- set-appearance --inactive-layer-display hidden --net-color-display all --board-flip normal --ratsnest-display all-layers

Inject DRC marker:

cargo run --features blocking --bin kicad-ipc-cli -- inject-drc-error --severity error --message "API marker test" --x-nm 1000000 --y-nm 1000000

Refill all zones:

cargo run --features blocking --bin kicad-ipc-cli -- refill-zones

Start interactive move tool for one or more item IDs:

cargo run --features blocking --bin kicad-ipc-cli -- interactive-move --id <uuid> --id <uuid>

Show typed netclass map:

cargo run --features blocking --bin kicad-ipc-cli -- netclass

Print proto command coverage status (board read):

cargo run --features blocking --bin kicad-ipc-cli -- proto-coverage-board-read

Generate full board-read reconstruction markdown report:

cargo run --features blocking --bin kicad-ipc-cli -- --timeout-ms 60000 board-read-report --out docs/BOARD_READ_REPORT.md

Notes:

• Report output is intentionally capped for very large boards to avoid multi-GB files.
• For full raw payloads, use targeted commands such as items-raw --debug, pad-shape-polygon --debug, and padstack-presence --debug.

Get current project path (derived from open PCB docs):

cargo run --features blocking --bin kicad-ipc-cli -- project-path

Smoke check:

cargo run --features blocking --bin kicad-ipc-cli -- smoke

Common Flags

Custom socket:

cargo run --features blocking --bin kicad-ipc-cli -- --socket ipc:///tmp/kicad/api.sock ping

Custom token:

cargo run --features blocking --bin kicad-ipc-cli -- --token "$KICAD_API_TOKEN" version

Stable client name (needed when pairing begin-commit and end-commit across separate CLI runs):

cargo run --features blocking --bin kicad-ipc-cli -- --client-name write-test begin-commit

Custom timeout:

cargo run --features blocking --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.