kicad-ipc-rs

MIT-licensed Rust client library for the KiCad IPC API.

Maintainer workflow: see CONTRIBUTIONS.md.

Status

Alpha. v0.3.0 released.

• Async API (default): implemented and usable.
• Sync/blocking wrapper API (feature = "blocking"): implemented with full async parity.
• Real-world user testing: still limited.
• Issues and PRs welcome.

Guide Site (mdBook)

Book-style guide source lives under docs/book/ and is deployed via GitHub Pages:

• Source: docs/book/src/
• Build config: docs/book/book.toml
• CI workflow: .github/workflows/mdbook.yml
• Published URL: https://milind220.github.io/kicad-ipc-rs/

Usage

Async API (Default)

Cargo.toml:

[dependencies]
kicad-ipc-rs = "0.3.0"
tokio = { version = "1", features = ["macros", "rt"] }

use kicad_ipc_rs::KiCadClient;

#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<(), kicad_ipc_rs::KiCadError> {
    let client = KiCadClient::connect().await?;
    client.ping().await?;
    let version = client.get_version().await?;
    println!("KiCad: {}", version.full_version);
    Ok(())
}

Sync API (Blocking)

Enable the blocking feature and use KiCadClientBlocking for synchronous callers:

Cargo.toml:

[dependencies]
kicad-ipc-rs = { version = "0.3.0", features = ["blocking"] }

use kicad_ipc_rs::KiCadClientBlocking;

fn main() -> Result<(), kicad_ipc_rs::KiCadError> {
    let client = KiCadClientBlocking::builder().connect()?;
    client.ping()?;
    let version = client.get_version()?;
    println!("KiCad: {}", version.full_version);
    Ok(())
}

Implementation notes:

• Blocking calls run through a dedicated Tokio runtime thread.
• Requests are serialized through a bounded queue.
• Runtime teardown is graceful: in-flight work drains before worker exit.

Protobuf Source

This crate ships checked-in Rust protobuf output under src/proto/generated/.

• Consumers do not need KiCad source checkout or git submodules.
• Maintainers regenerate bindings from KiCad upstream via the kicad git submodule.
• Current proto pin: KiCad 10.0.0-rc1.1 (KICAD_API_VERSION = 10.0.0-rc1.1-0-gc7c84125).

Maintainer refresh flow:

git submodule update --init --recursive
./scripts/regenerate-protos.sh

The regeneration tool also stamps KICAD_API_VERSION from the KiCad submodule git revision.

Local Testing

• CLI runbook: /Users/milindsharma/Developer/kicad-oss/kicad-ipc-rs/docs/TEST_CLI.md
• CLI help: cargo run --features blocking --bin kicad-ipc-cli -- help

Runtime Compatibility Notes

• KiCad version (kicad-ipc-cli version): 10.0.0 (10.0.0-rc1)

Commands wrapped in this crate but currently unhandled/unsupported by this KiCad build:

Command	Runtime status	Notes
RefreshEditor	AS_UNHANDLED	KiCad responds no handler available for request of type kiapi.common.commands.RefreshEditor.

Runtime-verified operations include:

• CreateItems
• UpdateItems
• DeleteItems

KiCad v10 RC1.1 API Completion Matrix

Legend:

• Implemented = wrapped in current Rust client (src/client.rs).
• Not yet = exists in proto, not wrapped yet.
• Command messages only (request payloads); helper/response messages excluded.

Section Coverage

Section	Proto Commands	Implemented	Coverage
Common (base)	6	6	100%
Common editor/document	23	23	100%
Project manager	5	5	100%
Board editor (PCB)	22	22	100%
Schematic editor (dedicated proto commands)	0	0	n/a
Total	56	56	100%

Common (base)

KiCad Command	Status	Rust API
Ping	Implemented	KiCadClient::ping
GetVersion	Implemented	KiCadClient::get_version
GetKiCadBinaryPath	Implemented	KiCadClient::get_kicad_binary_path_raw, KiCadClient::get_kicad_binary_path
GetTextExtents	Implemented	KiCadClient::get_text_extents_raw, KiCadClient::get_text_extents
GetTextAsShapes	Implemented	KiCadClient::get_text_as_shapes_raw, KiCadClient::get_text_as_shapes
GetPluginSettingsPath	Implemented	KiCadClient::get_plugin_settings_path_raw, KiCadClient::get_plugin_settings_path

Common editor/document

KiCad Command	Status	Rust API
RefreshEditor	Implemented	KiCadClient::refresh_editor
GetOpenDocuments	Implemented	KiCadClient::get_open_documents, KiCadClient::get_current_project_path, KiCadClient::has_open_board
SaveDocument	Implemented	KiCadClient::save_document_raw, KiCadClient::save_document
SaveCopyOfDocument	Implemented	KiCadClient::save_copy_of_document_raw, KiCadClient::save_copy_of_document
RevertDocument	Implemented	KiCadClient::revert_document_raw, KiCadClient::revert_document
RunAction	Implemented	KiCadClient::run_action_raw, KiCadClient::run_action
BeginCommit	Implemented	KiCadClient::begin_commit_raw, KiCadClient::begin_commit
EndCommit	Implemented	KiCadClient::end_commit_raw, KiCadClient::end_commit
CreateItems	Implemented	KiCadClient::create_items_raw, KiCadClient::create_items
GetItems	Implemented	KiCadClient::get_items_raw_by_type_codes, KiCadClient::get_items_by_type_codes, KiCadClient::get_items_details_by_type_codes, KiCadClient::get_all_pcb_items_raw, KiCadClient::get_all_pcb_items, KiCadClient::get_all_pcb_items_details, KiCadClient::get_pad_netlist
GetItemsById	Implemented	KiCadClient::get_items_by_id_raw, KiCadClient::get_items_by_id, KiCadClient::get_items_by_id_details
UpdateItems	Implemented	KiCadClient::update_items_raw, KiCadClient::update_items
DeleteItems	Implemented	KiCadClient::delete_items_raw, KiCadClient::delete_items
GetBoundingBox	Implemented	KiCadClient::get_item_bounding_boxes
GetSelection	Implemented	KiCadClient::get_selection_raw, KiCadClient::get_selection, KiCadClient::get_selection_summary, KiCadClient::get_selection_details
AddToSelection	Implemented	KiCadClient::add_to_selection_raw, KiCadClient::add_to_selection
RemoveFromSelection	Implemented	KiCadClient::remove_from_selection_raw, KiCadClient::remove_from_selection
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
SaveSelectionToString	Implemented	KiCadClient::get_selection_as_string
ParseAndCreateItemsFromString	Implemented	KiCadClient::parse_and_create_items_from_string_raw, KiCadClient::parse_and_create_items_from_string

Project manager

KiCad Command	Status	Rust API
GetNetClasses	Implemented	KiCadClient::get_net_classes_raw, KiCadClient::get_net_classes
SetNetClasses	Implemented	KiCadClient::set_net_classes_raw, KiCadClient::set_net_classes
ExpandTextVariables	Implemented	KiCadClient::expand_text_variables_raw, KiCadClient::expand_text_variables
GetTextVariables	Implemented	KiCadClient::get_text_variables_raw, KiCadClient::get_text_variables
SetTextVariables	Implemented	KiCadClient::set_text_variables_raw, KiCadClient::set_text_variables

Board editor (PCB)

KiCad Command	Status	Rust API
GetBoardStackup	Implemented	KiCadClient::get_board_stackup_raw, KiCadClient::get_board_stackup
UpdateBoardStackup	Implemented	KiCadClient::update_board_stackup_raw, KiCadClient::update_board_stackup
GetBoardEnabledLayers	Implemented	KiCadClient::get_board_enabled_layers
SetBoardEnabledLayers	Implemented	KiCadClient::set_board_enabled_layers
GetGraphicsDefaults	Implemented	KiCadClient::get_graphics_defaults_raw, KiCadClient::get_graphics_defaults
GetBoardOrigin	Implemented	KiCadClient::get_board_origin
SetBoardOrigin	Implemented	KiCadClient::set_board_origin
GetNets	Implemented	KiCadClient::get_nets
GetItemsByNet	Implemented	KiCadClient::get_items_by_net_raw, KiCadClient::get_items_by_net
GetItemsByNetClass	Implemented	KiCadClient::get_items_by_net_class_raw, KiCadClient::get_items_by_net_class
GetNetClassForNets	Implemented	KiCadClient::get_netclass_for_nets_raw, KiCadClient::get_netclass_for_nets
RefillZones	Implemented	KiCadClient::refill_zones
GetPadShapeAsPolygon	Implemented	KiCadClient::get_pad_shape_as_polygon_raw, KiCadClient::get_pad_shape_as_polygon
CheckPadstackPresenceOnLayers	Implemented	KiCadClient::check_padstack_presence_on_layers_raw, KiCadClient::check_padstack_presence_on_layers
InjectDrcError	Implemented	KiCadClient::inject_drc_error_raw, KiCadClient::inject_drc_error
GetVisibleLayers	Implemented	KiCadClient::get_visible_layers
SetVisibleLayers	Implemented	KiCadClient::set_visible_layers
GetActiveLayer	Implemented	KiCadClient::get_active_layer
SetActiveLayer	Implemented	KiCadClient::set_active_layer
GetBoardEditorAppearanceSettings	Implemented	KiCadClient::get_board_editor_appearance_settings_raw, KiCadClient::get_board_editor_appearance_settings
SetBoardEditorAppearanceSettings	Implemented	KiCadClient::set_board_editor_appearance_settings
InteractiveMoveItems	Implemented	KiCadClient::interactive_move_items_raw, KiCadClient::interactive_move_items

Schematic editor

Item	Value
Dedicated commands in kicad/api/proto/schematic/schematic_commands.proto	None in current proto snapshot
Coverage	n/a

Symbol editor

Item	Value
Dedicated symbol-editor command proto	None in current snapshot
Current path	Uses common editor/document commands via DocumentType::DOCTYPE_SYMBOL

Footprint editor

Item	Value
Dedicated footprint-editor command proto	None in current snapshot
Current path	Uses common editor/document commands via DocumentType::DOCTYPE_FOOTPRINT

Roadmap

v0.2.0 target:

• Expand runtime + integration testing coverage.
• Set up CI to run checks/tests on commits and PRs.
• Continue API hardening/docs/examples for stable 1.0 path.

Future Work: Public Surface + Docs

• This crate is still in alpha, and some lower-level modules currently remain public for advanced/debugging workflows.
• #![warn(missing_docs)] is enabled; high-impact user APIs are documented first, and remaining warnings are being burned down incrementally.
• As usage data accumulates, internal surfaces (commands, envelope, transport/proto-adjacent helpers) may be narrowed or made pub(crate) where possible without breaking user workflows.