package kiapi.common.commands

Get desktop application:
View/edit binary Protocol Buffers messages

Inserts a new row into the given library table. Returns LibraryCommandStatus Since: 11.0

• optional types.LibraryTableEntry entry = 1

• types.LibraryTableScope scope = 2

  Which table to modify. LTS_BOTH is invalid here.

Adds the given items to the selection. Returns SelectionResponse

• optional types.ItemHeader header = 1

• repeated types.KIID items = 2

  The items to select

Adds a variant to the registry. Errors with AS_BAD_REQUEST when the name already exists (case-insensitive).

• optional types.DocumentSpecifier document = 1

• string name = 2

• optional string description = 3

Begins a staged set of changes. Any modifications made to a document through the API after this call will be saved to a pending commit, and will not appear in KiCad until a matching call to END_COMMIT.

• optional types.ItemHeader header = 1

  Specifies which document to associate the commit with

• optional types.KIID id = 1

  Opaque identifier tracking a commit

Used in: GetBoundingBox

• BBM_UNKNOWN = 0

• BBM_ITEM_ONLY = 1

• BBM_ITEM_AND_CHILD_TEXT = 2

Removes all items from selection

• optional types.ItemHeader header = 1

Closes all open documents (currently only supported in CLI api-server mode)

• bool force = 1

  If set, will close documents even if they have been modified and not saved

• optional types.DocumentSpecifier document = 1

Used in: EndCommit

• CMA_UNKNOWN = 0

• CMA_COMMIT = 1

  Commit the changes to the design

• CMA_DROP = 2

  Cancel this commit

Copies an existing variant to a new variant, including copying all item overrides in the existing variant (that is, does a deep copy)

• optional types.DocumentSpecifier document = 1

• string old_name = 2

• string new_name = 3

• optional string new_description = 4

Creates a new document (in memory; does not save to disk) Currently board and schematic files can be created. A project will be created for the document if it doesn't already exist. Will return an error if the current document is unsaved: save or revert first Returns OpenDocumentResponse Since: 11.0

• types.DocumentType type = 1

• string path = 2

Creates new items on a given document

• optional types.ItemHeader header = 1

  Specifies which document to create on, which fields are included, etc.

• repeated google.protobuf.Any items = 2

  List of items to create

• optional types.KIID container = 3

  Items may be created on a top-level document (sheet, board, etc) or inside a container (symbol, footprint). If this field is not empty, it holds the ID of a symbol or footprint that the items should be added to. This ID must be an existing symbol (for schematic documents) or footprint (for board documents). If the given container does not exist or is not the correct item type, the CreateItems call will fail.

• optional types.ItemHeader header = 1

  Specifies which document was modified, which fields are included in created_items, etc.

• types.ItemRequestStatus status = 2

  Status of the overall request; may return IRS_OK even if no items were created

• repeated ItemCreationResult created_items = 3

  Status of each item to be created

Internal KiCad API; may be removed without notice. When running in standalone, the first frame to start will get the well-known API socket path. Others can use this to set up a bidirectional link. Since we don't plan to keep standalone mode around for the long-term, this is a temporary workaround that doesn't change the whole paradigm of the API away from client-server.

• types.FrameType frame_type = 1

• string socket_path = 2

• string api_token = 3

Internal KiCad API; may be removed without notice.

• CrossProbeStatus status = 1

• string message = 2

Used in: CrossProbeAnnounceResponse, FocusOnItemResponse, HighlightNetsResponse, SyncSelectionResponse

• CPS_UNSPECIFIED = 0

• CPS_OK = 1

• CPS_NOT_FOUND = 2

• CPS_INVALID = 3

• CPS_DISABLED = 4

• optional string name = 1

  Will be omitted if the current variant is the default variant

Deletes items in a given document

• optional types.ItemHeader header = 1

  Specifies which document to modify

• repeated types.KIID item_ids = 2

  List of item KIIDs to delete

• optional types.ItemHeader header = 1

  Specifies which document was modified, etc.

• types.ItemRequestStatus status = 2

  Status of the overall request; may return IRS_OK even if no items were deleted

• repeated ItemDeletionResult deleted_items = 3

  Status of each item requested to be deleted

Deletes a row from the given library table by nickname. Returns LibraryCommandStatus Since: 11.0

• types.LibraryType type = 1

  Which table type (symbol, footprint, design block) contains the row

• string nickname = 2

• types.LibraryTableScope scope = 3

  Which table to modify. LTS_BOTH is invalid here.

Deletes a variant and all its per-instance records Deleting the current variant resets the active variant to default.

• optional types.DocumentSpecifier document = 1

• string name = 2

Used in: GetDocumentModifiedStateResponse

• DMS_UNKNOWN = 0

• DMS_UNMODIFIED = 1

• DMS_MODIFIED = 2

• optional types.KIID id = 1

  The ID that was given by BeginCommit

• CommitAction action = 2

  What to do with this commit

• string message = 3

  Optional message describing this changeset

• optional types.ItemHeader header = 4

  Specifies which document to associate the commit with

(message has no fields)

• optional types.DocumentSpecifier document = 1

• repeated string text = 2

• bool expand_env_vars = 3

  If set, environment variables (such as ${KIPRJMOD} or user-defined variables) will be expanded in addition to the usual text variables, after the text variables are expanded. Since: 10.0.7

• repeated string text = 1

• optional SelectionSpec focus_item = 1

• CrossProbeStatus status = 1

• string message = 2

Ensures the given items are visible and zooms to fit them. The bounding box of all given items will be expanded by `margin` if present. Returns an error if any of the given `items` are not in `document`. Available only in interactive mode and when the editor in question is idle. Returns Empty

• optional types.DocumentSpecifier document = 1

  For schematics, a document with a sheet path focuses that sheet's placement of the items

• repeated types.KIID items = 2

  The items to fit in the view. Schematic items must all be on one sheet.

• optional types.Distance margin = 3

Used in: SelectionSpec

• string reference = 1

• optional types.ItemHeader header = 1

• repeated types.KIID items = 2

• BoundingBoxMode mode = 3

  Some item types can have independently-movable text as children (e.g. footprints) This mode controls whether or not these are included in the box

• repeated types.KIID items = 1

• repeated types.Box2 boxes = 2

• optional types.DocumentSpecifier document = 1

Checks whether a document currently open in an editor or headless context has unsaved changes

• optional types.DocumentSpecifier document = 1

• DocumentModifiedState state = 1

• optional types.ItemHeader header = 1

  Specifies which document to query, which fields to return, etc.

• repeated types.KiCadObjectType types = 2

  List of types of items to retrieve; if omitted, all types valid for the target document will be returned

• optional types.ItemHeader header = 1

  Specifies which document to query, which fields to return, etc.

• repeated types.KIID items = 2

Requests the full content of items contained in a library or set of libraries Returns GetItemsResponse Since: 11.0

• types.LibraryType type = 1

  The type of library to query (symbol, footprint, design block).

• optional types.DocumentSpecifier document = 2

  Which document context to use (to enable querying project-specific libraries)

• repeated types.LibraryIdentifier item_ids = 3

  The items to retrieve.

• optional types.ItemHeader header = 1

  Specifies which document was modified, which fields are included in items, etc.

• types.ItemRequestStatus status = 2

  Status of the overall request; may return IRS_OK even if no items were retrieved

• repeated google.protobuf.Any items = 3

Returns the full path to the given KiCad binary

• string binary_name = 1

  The short name of the binary, such as `kicad-cli` or `kicad-cli.exe`. If on Windows, an `.exe` extension will be assumed if not present.

Requests items contained in a library or set of libraries Returns LibraryItemsResponse Since: 11.0

• types.LibraryType type = 1

• repeated string nickname = 2

  The library or libraries to query.

Queries the load status of each library of the given type(s) Returns LibraryStatusResponse Since: 11.0

• repeated types.LibraryType types = 1

  Types to query; empty means all types

• types.LibraryTableScope scope = 2

  Which table scope(s) to query

Returns LibraryTableResponse Since: 11.0

• types.LibraryType type = 1

  Which type of table (symbol, footprint, design block) to query

• types.LibraryTableScope scope = 2

  Which table scope (global, project, or both)

• bool substituted = 3

  If true, return URIs with environment variables expanded

Returns NetClassAssignmentsResponse Since: 11.0

• optional types.ProjectSpecifier project = 1

  The project to query

• optional types.ProjectSpecifier project = 1

  Requests should include a project even though KiCad cannot have more than one project open at once yet. Requests without a project will be deprecated in a future version. Since: 11.0

Retrieves a list of open documents of the given type

• types.DocumentType type = 1

  Which type of documents to query

• repeated types.DocumentSpecifier documents = 1

returns common.types.PageSettings

• optional types.DocumentSpecifier document = 1

Returns the set of well-known filesystem paths used by KiCad. These paths are not guaranteed to actually exist or be accessible to an API client. The meaning of these paths and their actual location are not API guarantees. Returns GetPathsResponse

(message has no fields)

• repeated PathEntry paths = 1

Return a writeable path that a plugin can use for storing persistent data such as configuration files, etc. This path may not yet exist; actual creation of the directory for a given plugin is up to the plugin itself. Files in this path will not be modified if the plugin is uninstalled or upgraded. Returns StringResponse

• string identifier = 1

  The identifier of the plugin

Retrieves a list of items. Returns SelectionResponse

• optional types.ItemHeader header = 1

  Specifies which document to query for selected items.

• repeated types.KiCadObjectType types = 2

  An optional list of types to filter on. If none are provided, all selected items will be returned.

Render the given text object(s) as shapes. Depending on whether the text is using the KiCad stroke font or a custom font, the response will be a compound shape containing a set of polygons or a set of segments.

• repeated TextOrTextBox text = 1

• repeated TextWithShapes text_with_shapes = 1

returns kiapi.common.types.Box2

• optional types.Text text = 1

  A temporary text item to calculate the bounding box for

returns kiapi.common.project.TextVariables

• optional types.DocumentSpecifier document = 1

returns common.types.TitleBlockInfo

• optional types.DocumentSpecifier document = 1

• optional types.DocumentSpecifier document = 1

  Within a project, variants can exist on the schematic and the board. They are not necessarily in sync (a user may create variants on the board that have no matching schematic variants, for example).

(message has no fields)

• optional types.KiCadVersion version = 1

• repeated string net_name = 1

• CrossProbeStatus status = 1

• string message = 2

Tests if a certain point falls within tolerance of an item's geometry

• optional types.ItemHeader header = 1

• optional types.KIID id = 2

• optional types.Vector2 position = 3

• int32 tolerance = 4

• HitTestResult result = 1

Used in: HitTestResponse

• HTR_UNKNOWN = 0

• HTR_NO_HIT = 1

• HTR_HIT = 2

Used in: CreateItemsResponse

• optional ItemStatus status = 1

• optional google.protobuf.Any item = 2

  The created version of the item, including an updated KIID as applicable

Used in: DeleteItemsResponse

• optional types.KIID id = 1

• ItemDeletionStatus status = 2

Used in: ItemDeletionResult

• IDS_UNKNOWN = 0

• IDS_OK = 1

• IDS_NONEXISTENT = 2

  The item did not exist in the given document

• IDS_IMMUTABLE = 3

  The item is not allowed to be modified by the API

Per-item status feedback for creation and update calls

Used in: board.commands.ItemFlipResult, ItemCreationResult, ItemUpdateResult

• ItemStatusCode code = 1

• string error_message = 2

Used in: ItemStatus

• ISC_UNKNOWN = 0

• ISC_OK = 1

  The item was created or updated

• ISC_INVALID_TYPE = 2

  The item's type is not valid for the given document

• ISC_EXISTING = 3

  The item to be created had a specified KIID and that KIID was already in use

• ISC_NONEXISTENT = 4

  The item to be updated did not exist in the given document

• ISC_IMMUTABLE = 5

  The item to be updated is not allowed to be modified by the API

• ISC_INVALID_DATA = 7

  The item to be created does not have valid data for the given document

Used in: UpdateItemsResponse

• optional ItemStatus status = 1

• optional google.protobuf.Any item = 2

  The update version of the item

Since: 11.0

• repeated types.LibraryIdentifier items = 1

  The identifiers of all content in the library

Since: 11.0

• repeated types.LibraryStatusEntry libraries = 1

Since: 11.0

• optional types.LibraryTable table = 1

  The table that was queried

• repeated types.LibraryTableEntry rows = 2

Starts a background load of all libraries of the given types that are listed in the library tables. If no types are given, all library types are loaded. The command returns immediately and the load proceeds asynchronously; progress can be monitored with GetLibraryStatuses. In GUI mode this command is a no-op, because the GUI preloads libraries on its own. Returns LibraryCommandStatus Since: 11.0

• repeated types.LibraryType type = 1

  Types of libraries to load; empty means all types

Since: 11.0

• repeated project.NetClassAssignment assignments = 1

• repeated project.NetClassPatternAssignment pattern_assignments = 2

• repeated project.NetClass net_classes = 1

Opens a document (currently only supported in CLI api-server mode) A document cannot be opened unless no project is currently loaded or it is part of a currently loaded project. To switch projects, use CloseDocument or CloseAllDocuments to close existing documents.

• types.DocumentType type = 1

• string path = 2

• optional types.DocumentSpecifier document = 1

Opens a specific item from a library by identifier

• types.DocumentType type = 1

• optional types.LibraryIdentifier identifier = 2

Used in: SelectionSpec

• string reference = 1

  Parent footprint

• string number = 2

Attempts to parse the given string as a s-expression formatted container with items, similar to how the Paste action inside the KiCad editor works. If the parse is successful, the items will be created and inserted into the editor. Returns CreateItemsResponse

• optional types.DocumentSpecifier document = 1

• string contents = 2

Used in: GetPathsResponse

• types.PathType type = 1

• string path = 2

  Absolute path in platform-native form; may not exist on disk

• string path = 1

A command to check if the connection to KiCad is OK

(message has no fields)

Since: 11.0

• optional types.ItemHeader header = 1

• optional google.protobuf.Any item = 2

  The newly-created item

Refreshes the given frame, if that frame is open

• types.FrameType frame = 1

Reloads library table row(s) from disk. This starts a reload process that operates asynchronously. The API command will return immediately but updated library content will not be available until the load has completed. Returns LibraryCommandStatus Since: 11.0

• types.LibraryType type = 1

  Type of library to reload

• types.LibraryTableScope scope = 2

  Which table to look up the library in. LTS_BOTH is invalid here.

• repeated string nickname = 3

  List of libraries to reload. If absent, all libraries matching type and scope will be reloaded.

Removes the given items to the selection. Returns SelectionResponse

• optional types.ItemHeader header = 1

• repeated types.KIID items = 2

  The items to deselect

• optional types.DocumentSpecifier document = 1

• string old_name = 2

• string new_name = 3

• optional types.DocumentSpecifier document = 1

Runs a TOOL_ACTION using the TOOL_MANAGER of a given frame. WARNING: The TOOL_ACTIONs are specifically *not* an API. Command names may change as code is refactored, and commands may disappear. This API method is provided for low-level prototyping purposes only.

• string action = 1

  Action name, like "eeschema.InteractiveSelection.ClearSelection"

NOTE: At the moment, RAS_FRAME_NOT_OPEN won't be returned as the handler is inside the frame.

• RunActionStatus status = 1

Used in: RunActionResponse

• RAS_UNKNOWN = 0

• RAS_OK = 1

  The action was submitted successfully.

• RAS_INVALID = 2

  The action was unknown for the targeted frame.

• RAS_FRAME_NOT_OPEN = 3

  The targeted frame was not open when the call was submitted.

Saves the given document to a new location and does not open the new copy

• optional types.DocumentSpecifier document = 1

• string path = 2

• optional SaveOptions options = 3

Saves the given document to its existing file path. Returns an error if the document is untitled (it has never been saved to disk); use SaveDocumentAs to save an untitled document to an explicit path.

• optional types.DocumentSpecifier document = 1

Saves the given document (and its project) to a new location and switches to the new project. Only available in headless mode; in GUI mode a project change may require closing other editor frames, which the API is not allowed to do. Since: 11.0

• optional types.DocumentSpecifier document = 1

• string path = 2

• optional types.DocumentSpecifier document = 1

Used in: SaveCopyOfDocument

• bool overwrite = 1

  Overwrite destination file(s) if they exist

• bool include_project = 2

  If the file being saved normally requires a project (for example, a board or schematic), this flag will cause a new project to be saved alongside the new file

(message has no fields)

• optional types.DocumentSpecifier document = 1

• string contents = 2

• repeated types.KIID ids = 1

• string contents = 2

Requests items matching a search query in the given library scopes Returns SearchLibrariesResponse Since: 11.0

• types.LibraryType type = 1

• string query = 2

  Glob pattern or substring to match against item names. Follows the same logic of KiCad's library chooser filter

Since: 11.0

• repeated types.LibraryIdentifier items = 1

  The identifiers of matching content

The set of currently selected items

• repeated google.protobuf.Any items = 1

Used in: FocusOnItem, SyncSelection

• oneof spec

  • FootprintSelectionSpec footprint = 1

  • PadSelectionSpec pad = 2

  • types.SheetPath sheet_path = 3

Selects the active variant in the editor (absent or empty name selects the default variant).

• optional types.DocumentSpecifier document = 1

• optional string name = 2

Since: 11.0

• optional types.ProjectSpecifier project = 1

  The project to query

• types.MapMergeMode merge_mode = 2

  In MMM_MERGE mode, per-net assignments are replaced for each net present in the request (an empty netclasses list removes all assignments for that net), and pattern assignments are updated if they already exist. In MMM_REPLACE mode, any existing assignments or patterns not present in the request are erased.

• repeated project.NetClassAssignment assignments = 3

• repeated project.NetClassPatternAssignment pattern_assignments = 4

• repeated project.NetClass net_classes = 1

• types.MapMergeMode merge_mode = 3

  Whether to merge or replace the existing netclasses with the contents of this message Note that this only happens at the level of netclass name: for example, if merge_mode is set to MMM_MERGE, the design has netclasses ["Default", "HV"], and this message has netclasses ["Default", "LV"], the resulting set will be ["Default", "HV", "LV"] -- the Default netclass will have its properties replaced with those in this message, the "LV" netclass will be added, and the "HV" netclass will be left alone. If merge_mode is set to MMM_REPLACE, the "HV" class will be erased. Note that there must always be a "Default" netclass, so it will not be erased even if merge_mode is MMM_REPLACE and there is no "Default" class specified in this message.

• optional types.ProjectSpecifier project = 4

  Requests should include a project even though KiCad cannot have more than one project open at once yet. Requests without a project will be deprecated in a future version. Since: 11.0

• optional types.DocumentSpecifier document = 1

• optional types.PageSettings page_settings = 2

• optional types.DocumentSpecifier document = 1

• optional project.TextVariables variables = 2

• types.MapMergeMode merge_mode = 3

  Whether to merge or replace the existing text variables map with the contents of this message

• optional types.DocumentSpecifier document = 1

• optional types.TitleBlockInfo title_block = 2

• optional types.DocumentSpecifier document = 1

• string name = 2

• string description = 3

• string response = 1

• SyncSelectionContext context = 1

• SyncSelectionMode mode = 2

• optional SelectionSpec focus_item = 3

• repeated SelectionSpec items = 4

Used in: SyncSelection

• SSC_UNKNOWN = 0

• SSC_IMPLICIT = 1

  Implicit user action (e.g. just clicking on an item)

• SSC_EXPLICIT = 2

  Explicit user action (e.g. running a "select in other window" action)

Used in: SyncSelection

• SSM_UNKNOWN = 0

• SSM_ITEMS_ONLY = 1

• SSM_ITEMS_AND_NETS = 2

• CrossProbeStatus status = 1

• string message = 2

Used in: GetTextAsShapes, TextWithShapes

• oneof inner

  • types.Text text = 1

  • types.TextBox textbox = 2

Used in: GetTextAsShapesResponse

• optional TextOrTextBox text = 1

• optional types.CompoundShape shapes = 2

Updates items in a given document

• optional types.ItemHeader header = 1

  Specifies which document to modify, which fields are included, etc.

• repeated google.protobuf.Any items = 2

  List of items to modify

• optional types.ItemHeader header = 1

  Specifies which document was modified, which fields are included in updated_items, etc.

• types.ItemRequestStatus status = 2

  Status of the overall request; may return IRS_OK even if no items were modified

• repeated ItemUpdateResult updated_items = 3

  Status of each item to be created

Modifies an existing row, matched by entry.nickname (and scope). Returns LibraryCommandStatus Since: 11.0

• optional types.LibraryTableEntry entry = 1

• types.LibraryTableScope scope = 2

  Which table to modify. LTS_BOTH is invalid here.

• optional types.DocumentSpecifier document = 1

• repeated types.DesignVariant variants = 2

  All non-default variants for the given document