:author: The KiCad Team
:doctype: book
:toc:
:ascii-ids:
:experimental:

= KiCad Command-Line Interface

_Reference manual_

NOTE: This manual is in the process of being revised to cover the latest stable
      release version of KiCad.  It contains some sections that have not yet
      been completed.  We ask for your patience while our volunteer technical
      writers work on this task, and we welcome new contributors who would like
      to help make KiCad's documentation better than ever.

[[copyright]]
*Copyright*

This document is Copyright (C) 2023 by its contributors as listed
below. You may distribute it and/or modify it under the terms of either
the GNU General Public License (http://www.gnu.org/licenses/gpl.html),
version 3 or later, or the Creative Commons Attribution License
(http://creativecommons.org/licenses/by/3.0/), version 3.0 or later.

All trademarks within this guide belong to their legitimate owners.

[[contributors]]
*Contributors*

Graham Keeth

[[feedback]]
*Feedback*

The KiCad project welcomes feedback, bug reports, and suggestions related to the software or its
documentation. For more information on how to sumbit feedback or report an issue, please see the
instructions at https://www.kicad.org/help/report-an-issue/

== Introduction to the KiCad Command-Line Interface

KiCad provides a command-line interface, which is available by running the
`kicad-cli` binary. With the command-line interface, you can perform a number of
actions on schematics, PCBs, symbols, and footprints in an automated fashion,
such as plotting Gerber files from a PCB design or upgrading a symbol library
from a legacy file format to a modern format.

NOTE: On macOS, the `kicad-cli` executable is located at
      `/Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli`.

== `kicad-cli` commands

The `kicad-cli` command has 5 subcommands: `fp`, `pcb`, `sch`, `sym`, and
`version`. Each subcommand may have its own subcommands and arguments. For
example, to export Gerber files from a PCB you could run
`kicad-cli pcb export gerbers example.kicad_pcb`.

You can add the `--help` or `-h` flag to see information about each
subcommand. For example, running `kicad-cli pcb -h` prints usage information
about the `pcb` subcommand, and `kicad-cli pcb export gerbers -h` prints usage
information specifically for the `pcb export gerbers` subcommand.

=== Footprint

The `fp` subcommand exports footprints to another format or upgrades the
footprint libraries to the current version of the KiCad footprint file format.

==== Footprint export

The `fp export svg` command exports one or more footprints from the specified
library into SVG files.

Usage: `kicad-cli fp export svg [-h] [--output VAR] [--layers VAR] [--theme VAR] 
[--footprint VAR] [--black-and-white] input`

Positional arguments:

[width="100%",cols="30%,70%"]
|====
| `input`
    | Footprint library to export (`.pretty`).
|====

Optional arguments:

[width="100%",cols="30%,70%"]
|====
| `-h`, `--help`
    | Show help for the footprint SVG export command.
| `-o <output dir>`, `--output <output dir>`
    | The output directory for the exported files. When this argument is not
      used, the files are exported to the current directory.
| `-l <layer list>`, `--layers <layer list>`
    | A comma-separated list of layer names to export from the footprint, such
      as `F.Cu,B.Cu`. If no layers are given, all layers are exported.
| `-t <theme name>`, `--theme <theme name>`
    | The name of the theme to use for export. If no theme is given, the
      footprint editor's currently selected theme is used.
| `--fp <footprint>`, `--footprint <footprint>`
    | The specific footprint to export from the library. When this argument is
      not used, all footprints in the library are exported.
| `--black-and-white`
    | Export footprints in black and white.
|====

==== Footprint upgrade

The `fp upgrade` command upgrades the the specified footprint library from a
legacy footprint format to the native format for the current version of KiCad.
If the input library is already in the current file format, no action is taken.

Usage: `kicad-cli fp upgrade [-h] [--output VAR] [--force] input`

Positional arguments:

[width="100%",cols="30%,70%"]
|====
| `input`
    | Footprint library to upgrade (`.pretty`).
|====

Optional arguments:

[width="100%",cols="30%,70%"]
|====
| `-h`, `--help`
    | Show help for the footprint upgrade command.
| `-o <output dir>`, `--output <output dir>`
    | The output directory for the upgraded footprints. When this argument is
      not used, the upgraded footprints are saved over the original footprints.
| `--force`
    | Re-save the input library even if it is already in the current file format.
|====

=== PCB

The `pcb export` command exports a board to various other file formats,
including fabrication and 3D files. Each file format has its own options.

==== PCB drill file export

The `pcb export drill` command exports a drill file from a board.

Usage: `kicad-cli pcb export drill [-h] [--output VAR] [--format VAR]
[--drill-origin VAR] [--excellon-zeros-format VAR] [--excellon-units VAR]
[--excellon-mirror-y] [--excellon-min-header] [--excellon-separate-th]
[--generate-map] [--map-format VAR] [--gerber-precision VAR] input`

Positional arguments:

[width="100%",cols="30%,70%"]
|====
| `input`
    | Board file to export.
|====

Optional arguments:

[width="100%",cols="30%,70%"]
|====
| `-h`, `--help`
    | Show help for the drill file export command.
| `-o <output dir>`, `--output <output dir>`
    | The output directory for the drill file. When this argument is not used,
      the drill file is saved in the current directory.
| `--format <format>`
    | The drill file format. Options are `excellon` (default) or `gerber`.
| `--drill-origin <origin>`
    | The coordinate origin for the drill file. Options are `absolute` (default)
      to use the board's absolute origin or `plot` to use the board's
      drill/placement origin.
| `--excellon-zeros-format <format>`
    | The zeros format for the drill file. Options are `decimal` (default),
      `suppressleading`, `suppresstrailing`, or `keep`. Only applies to Excellon
      format drill files.
| `-u <units>`, `--excellon-units <units>`
    | The units for the drill file. Options are `mm` (default) or `in`. Only
      applies to Excellon format drill files.
| `--excellon-mirror-y`
    | Mirror the drill file in the Y direction. Only applies to Excellon format
      drill files.
| `--excellon-min-header`
    | Use a minimal header in the drill file. Only applies to Excellon format
      drill files.
| `--excellon-separate-th`
    | Generate separate drill files for plated and non-plated through holes.
      Only applies to Excellon format drill files.
| `--excellon-oval-format <format>`
    | Control the oval holes drill mode. Options are `route` (default) and
      `alternate`. Only applies to Excellon format drill files.
| `--generate-map`
    | Generate a map file in addition to the drill file.
| `--map-format <format>`
    | The map file format. Options are `pdf` (default), `gerberx2`, `ps`, `dxf`,
      or `svg`.
| `--gerber-precision <precision>`
    | The precision (number of digits) for the drill file. Valid options are `5`
      or `6` (default).  Only applies to Gerber format drill files.
|====

==== PCB DXF export

The `pcb export dxf` command exports a board design to a DXF file.

Usage: `kicad-cli pcb export dxf [-h] [--output VAR] [--layers VAR]
[--exclude-refdes] [--exclude-value] [--use-contours] [--output-units VAR] input`

Positional arguments:

[width="100%",cols="30%,70%"]
|====
| `input`
    | Board file to export.
|====

Optional arguments:

[width="100%",cols="30%,70%"]
|====
| `-h`, `--help`
    | Show help for the DXF export command.
| `-o <output filename>`, `--output <output filename>`
    | The output filename. When this argument is not used, the output filename
      will be the same as the input file, with the `.dxf` file extension.
| `-l <layer list>`, `--layers <layer list>`
    | A comma-separated list of layer names to export from the footprint, such
      as `F.Cu,B.Cu`. At least one layer must be given.
| `--erd`, `--exclude-refdes`
    | Exclude footprint reference designators from plot.
| `--ev`, `--exclude-value`
    | Exclude footprint values from plot.
| `--uc`, `--use-contours`
    | Plot graphic items using their contours.
| `--ou <unit>`, `--output-units <unit>`
    | Output units. Options are `mm` or `in` (default).
|====

==== PCB Gerber export: one layer per file

The `pcb export gerbers` command exports a board design to Gerber files, with
one layer per file.

Usage: `kicad-cli pcb export gerbers [-h] [--output VAR] [--layers VAR]
[--exclude-refdes] [--exclude-value] [--include-border-title] [--no-x2]
[--no-netlist] [--subtract-soldermask] [--disable-aperture-macros]
[--use-drill-file-origin] [--precision VAR] [--no-protel-ext]
[--common-layers VAR] [--board-plot-params] input`

Positional arguments:

[width="100%",cols="30%,70%"]
|====
| `input`
    | Board file to export.
|====

Optional arguments:

[width="100%",cols="30%,70%"]
|====
| `-h`, `--help`
    | Show help for the Gerber export command.
| `-o <output dir>`, `--output <output dir>`
    | The output folder for the exported files. When this argument is not used,
      the files are exported to the current directory.
| `-l <layer list>`, `--layers <layer list>`
    | A comma-separated list of layer names to plot from the board, such as
      `F.Cu,B.Cu`. If this argument is not used, all layers will be plotted.
| `--erd`, `--exclude-refdes`
    | Exclude footprint reference designators from plot.
| `--ev`, `--exclude-value`
    | Exclude footprint values from plot.
| `--ibt`, `--include-border-title`
    | Include the sheet border and title block.
| `--no-x2`
    | Do not use the extended X2 format.
| `--no-netlist`
    | Do not include netlist attributes.
| `--subtract-soldermask`
    | Remove silkscreen from areas without soldermask.
| `--disable-aperture-macros`
    | Disable aperture macros.
| `--use-drill-file-origin`
    | Use drill/place file origin instead of absolute origin.
| `--precision <precision>`
    | The precision (number of digits) for the Gerber files. Valid options are
      `5` or `6` (default).
| `--no-protel-ext`
    | Use `.gbr` file extension instead of Protel file extensions (`.gbl`,
      `.gtl`, etc.).
| `--cl <layer list>`, `--common-layers <layer list>`
    | A comma-separated list of layer names to plot on all layers, such as
      `F.Cu,B.Cu`.
| `--board-plot-params`
    | Use the Gerber plot settings already configured in the board file.
|====

==== PCB Gerber export: multiple layers per file

The `pcb export gerber` command exports one or more board layers to a single
Gerber file.

Usage: `kicad-cli pcb export gerber [-h] [--output VAR] [--layers VAR]
[--exclude-refdes] [--exclude-value] [--include-border-title] [--no-x2]
[--no-netlist] [--subtract-soldermask] [--disable-aperture-macros]
[--use-drill-file-origin] [--precision VAR] [--no-protel-ext] input`

Positional arguments:

[width="100%",cols="30%,70%"]
|====
| `input`
    | Board file to export.
|====

Optional arguments:

[width="100%",cols="30%,70%"]
|====
| `-h`, `--help`
    | Show help for the Gerber export command.
| `-o <output filename>`, `--output <output filename>`
    | The output filename. When this argument is not used, the output filename
      will be the same as the input file, with the `.gbr` file extension.
| `-l <layer list>`, `--layers <layer list>`
    | A comma-separated list of layer names to plot from the board, such as
      `F.Cu,B.Cu`. All layers will be plotted in the output file. At least one
      layer must be given.
| `--erd`, `--exclude-refdes`
    | Exclude footprint reference designators from plot.
| `--ev`, `--exclude-value`
    | Exclude footprint values from plot.
| `--ibt`, `--include-border-title`
    | Include the sheet border and title block.
| `--no-x2`
    | Do not use the extended X2 format.
| `--no-netlist`
    | Do not include netlist attributes.
| `--subtract-soldermask`
    | Remove silkscreen from areas without soldermask.
| `--disable-aperture-macros`
    | Disable aperture macros.
| `--use-drill-file-origin`
    | Use drill/place file origin instead of absolute origin.
| `--precision <precision>`
    | The precision (number of digits) for the Gerber files. Valid options are
      `5` or `6` (default).
| `--no-protel-ext`
    | Use `.gbr` file extension instead of Protel file extensions (`.gbl`,
      `.gtl`, etc.).
|====

==== PCB PDF export

The `pcb export pdf` command exports a board design to a PDF file.

Usage: `kicad-cli pcb export pdf [-h] [--output VAR] [--layers VAR] [--mirror]
[--exclude-refdes] [--exclude-value] [--include-border-title] [--negative]
[--black-and-white] [--theme VAR] input`

Positional arguments:

[width="100%",cols="30%,70%"]
|====
| `input`
    | Board file to export.
|====

Optional arguments:

[width="100%",cols="30%,70%"]
|====
| `-h`, `--help`
    | Show help for the PDF export command.
| `-o <output filename>`, `--output <output filename>`
    | The output filename. When this argument is not used, the output filename
      will be the same as the input file, with the `.pdf` file extension.
| `-l <layer list>`, `--layers <layer list>`
    | A comma-separated list of layer names to export from the board, such as
      `F.Cu,B.Cu`. At least one layer must be given.
| `-m`, `--mirror`
    | Mirror the board. This can be useful for showing bottom layers.
| `--erd`, `--exclude-refdes`
    | Exclude footprint reference designators from plot.
| `--ev`, `--exclude-value`
    | Exclude footprint values from plot.
| `--ibt`, `--include-border-title`
    | Include the sheet border and title block.
| `-n`, `--negative`
    | Plot in negative.
| `--black-and-white`
    | Plot in black and white.
| `-t <theme name>`, `--theme <theme name>`
    | The name of the theme to use for export. If no theme is given, the
      board editor's currently selected theme is used.
|====

==== PCB position file export

The `pcb export pos` command exports a position file from a board design.

Usage: `kicad-cli pcb export pos [-h] [--output VAR] [--side VAR] [--format VAR]
[--units VAR] [--bottom-negate-x] [--use-drill-file-origin] [--smd-only]
[--exclude-fp-th] [--gerber-board-edge] input`

Positional arguments:

[width="100%",cols="30%,70%"]
|====
| `input`
    | Board file to export.
|====

Optional arguments:

[width="100%",cols="30%,70%"]
|====
| `-h`, `--help`
    | Show help for the position file export command.
| `-o <output filename>`, `--output <output filename>`
    | The output filename. When this argument is not used, the output filename
      will be the same as the input file, with the `.pos` file extension.
| `--side <side>`
    | The side of the board to export. Options are `front`, `back`, or `both`
      (default). Gerber format does not support `both`.
| `--format <format>`
    | The position file format. Options are `ascii` (default), `csv`, or
      `gerber`.
| `--units <unit>`
    | Units for position file. Options are `in` (default) or `mm`. This argument
      has no effect for Gerber format.
| `--bottom-negate-x`
    | Use negative X coordinates for footprints on the bottom layer. This
      argument has no effect for Gerber format.
| `--use-drill-file-origin`
    | Use drill/place file origin instead of absolute origin. This option has no
      effect for Gerber format.
| `--smd-only`
    | Include only surface-mount components. This option has no effect for
      Gerber format.
| `--exclude-fp-th`
    | Exclude all footprints with through-hole pads. This option has no effect
      for Gerber format.
| `--gerber-board-edge`
    | Include board edge layer in export (Gerber format only).
|====

==== PCB STEP export

The `pcb export step` command exports a board design to a STEP file.

Usage: `kicad-cli pcb export step [-h] [--drill-origin] [--grid-origin]
[--no-virtual] [--subst-models] [--force] [--board-only] [--min-distance VAR]
[--user-origin VAR] [--output VAR] input`

Positional arguments:

[width="100%",cols="30%,70%"]
|====
| `input`
    | Board file to export.
|====

Optional arguments:

[width="100%",cols="30%,70%"]
|====
| `-h`, `--help`
    | Show help for the STEP file export command.
| `--drill-origin`
    | Use drill origin as origin of output file.
| `--grid-origin`
    | Use grid origin as origin of output file.
| `--no-virtual`
    | Exclude 3D models of components with 'virtual' attribute.
| `--subst-models`
    | Replace VRML models in footprints with STEP models of the same name, if
      they exist.
| `-f`, `--force`
    | Overwrite output file.
| `--board-only`
    | Only include the board itself in the generated model; exclude all
      component models.
| `--min-distance <min distance>`
    | Tolerance for considering two points to be in the same location. Default:
      `0.01mm`.
| `--user-origin <output origin>`
    | Specify a custom origin for the output file, with X and Y coordinates. For
      example, `1x1in`, `1x1inch`, or `25.4x25.4mm`. The default unit is
      millimeters.
| `-o <output filename>`, `--output <output filename>`
    | The output filename. When this argument is not used, the output filename
      will be the same as the input file, with the `.step` file extension.
|====

==== PCB SVG export

The `pcb export svg` command exports a board design to an SVG file.

Usage: `kicad-cli pcb export svg [-h] [--output VAR] [--layers VAR] [--mirror]
[--theme VAR] [--negative] [--black-and-white] [--page-size-mode VAR]
[--exclude-drawing-sheet] input`

Positional arguments:

[width="100%",cols="30%,70%"]
|====
| `input`
    | Board file to export.
|====

Optional arguments:

[width="100%",cols="30%,70%"]
|====
| `-h`, `--help`
    | Show help for the SVG file export command.
| `-o <output filename>`, `--output <output filename>`
    | The output filename. When this argument is not used, the output filename
      will be the same as the input file, with the `.svg` file extension.
| `-l <layer list>`, `--layers <layer list>`
    | A comma-separated list of layer names to export from the board, such as
      `F.Cu,B.Cu`. At least one layer must be given.
| `-m`, `--mirror`
    | Mirror the board. This can be useful for showing bottom layers.
| `-t <theme name>`, `--theme <theme name>`
    | The name of the theme to use for export. If no theme is given, the
      board editor's currently selected theme is used.
| `-n`, `--negative`
    | Plot in negative.
| `--black-and-white`
    | Plot in black and white.
| `--page-size-mode <mode>`
    | Set page sizing mode. Options are `0` (default), `1`, or `2`. `0` sets the
      output page size to fit the entire sheet, including drawing sheet frame
      and title block. `1` sets the output page size to match the current page
      size. `2` sets the output page size to the size of the board itself.
| `--exclude-drawing-sheet`
    | Plot SVG without a drawing sheet.
|====

=== Schematic

The `sch export` command exports a schematic to various other file formats, or
exports a bill of materials or netlist. Each file format has its own options.

==== Schematic DXF export

The `sch export dxf` command exports a schematic to a DXF file. Each
sheet in the design is exported to its own file.

Usage: `kicad-cli sch export dxf [-h] [--output VAR] [--theme VAR]
[--black-and-white] [--exclude-drawing-sheet] [--no-background-color]
[--plot-one] input`

Positional arguments:

[width="100%",cols="30%,70%"]
|====
| `input`
    | Schematic file to export.
|====

Optional arguments:

[width="100%",cols="30%,70%"]
|====
| `-h`, `--help`
    | Show help for the DXF file export command.
| `-o <output dir>`, `--output <output dir>`
    | The output folder for the exported files. When this argument is not used,
      the files are exported to the current directory.
| `-t <theme name>`, `--theme <theme name>`
    | The name of the theme to use for export. If no theme is given, the
      schematic editor's currently selected theme is used.
| `-b`, `--black-and-white`
    | Export schematic in black and white.
| `-e`, `--exclude-drawing-sheet`
    | Plot DXF without a drawing sheet.
| `-n`, `--no-background-color`
    | Export schematic without a background color, regardless of theme.
| `-o`, `--plot-one`
    | Only export the input sheet; do not export any subsheets.
|====

==== Schematic HPGL export

The `sch export hpgl` command exports a schematic to an HPGL file for a pen
plotter. Each sheet in the design is exported to its own file.

Usage: `kicad-cli sch export hpgl [-h] [--output VAR] [--theme VAR]
[--black-and-white] [--exclude-drawing-sheet] [--no-background-color]
[--plot-one] [--pen-size VAR] [--origin VAR] input`

Positional arguments:

[width="100%",cols="30%,70%"]
|====
| `input`
    | Schematic file to export.
|====

Optional arguments:

[width="100%",cols="30%,70%"]
|====
| `-h`, `--help`
    | Show help for the HPGL file export command.
| `-o <output dir>`, `--output <output dir>`
    | The output folder for the exported files. When this argument is not used,
      the files are exported to the current directory.
| `-t <theme name>`, `--theme <theme name>`
    | The name of the theme to use for export. If no theme is given, the
      schematic editor's currently selected theme is used.
| `-b`, `--black-and-white`
    | Export schematic in black and white.
| `-e`, `--exclude-drawing-sheet`
    | Plot HPGL without a drawing sheet.
| `-n`, `--no-background-color`
    | Export schematic without a background color, regardless of theme.
| `-o`, `--plot-one`
    | Only export the input sheet; do not export any subsheets.
| `-p <pen size>`, `--pen-size <pen size>`
    | Set the pen width. The default pen size is 0.5 mm.
| `-r <origin>`, `--origin <origin>`
    | Set plotter origin and scale. Options are `0`, `1` (default), `2`, or `3`.
      `0` sets the origin to the bottom left and uses plotter units. `1` sets
      the origin to the center and uses plotter units. `2` scales to the page,
      and `3` scales to the content within the page.
|====

==== Schematic netlist export

The `sch export netlist` command exports a netlist in
xref:../eeschema_generating_outputs.adoc#netlist-formats[various formats] from
a schematic.

Usage: `kicad-cli sch export netlist [-h] [--output VAR] [--format VAR] input`

Positional arguments:

[width="100%",cols="30%,70%"]
|====
| `input`
    | Schematic file to export.
|====

Optional arguments:

[width="100%",cols="30%,70%"]
|====
| `-h`, `--help`
    | Show help for the netlist export command.
| `-o <output filename>`, `--output <output filename>`
    | The output filename. When this argument is not used, the output filename
      will be the same as the input file, with a `.net` file extension.
| `-f <format>`, `--format <format>`
    | The netlist output format. Options are `kicadsexpr` (default), `kicadxml`,
      `cadstar`, `orcadpcb2`, `spice`, or `spicemodel`.
|====

==== Schematic PDF export

The `sch export pdf` command exports a schematic to a PDF file. Each sheet in
the design is exported to its own page in the PDF file.

Usage: `kicad-cli sch export pdf [-h] [--output VAR] [--theme VAR]
[--black-and-white] [--exclude-drawing-sheet] [--no-background-color]
[--plot-one] input`

Positional arguments:

[width="100%",cols="30%,70%"]
|====
| `input`
    | Schematic file to export.
|====

Optional arguments:

[width="100%",cols="30%,70%"]
|====
| `-h`, `--help`
    | Show help for the PDF file export command.
| `-o <output filename>`, `--output <output filename>`
    | The output filename. When this argument is not used, the output filename
      will be the same as the input file, with a `.pdf` file extension.
| `-t <theme name>`, `--theme <theme name>`
    | The name of the theme to use for export. If no theme is given, the
      schematic editor's currently selected theme is used.
| `-b`, `--black-and-white`
    | Export schematic in black and white.
| `-e`, `--exclude-drawing-sheet`
    | Plot PDF without a drawing sheet.
| `-n`, `--no-background-color`
    | Export schematic without a background color, regardless of theme.
| `-o`, `--plot-one`
    | Only export the input sheet; do not export any subsheets.
|====

==== Schematic PostScript export

The `sch export ps` command exports a schematic to a PostScript file. Each
sheet in the design is exported to its own file.

Usage: `kicad-cli sch export ps [-h] [--output VAR] [--theme VAR]
[--black-and-white] [--exclude-drawing-sheet] [--no-background-color]
[--plot-one] input`

Positional arguments:

[width="100%",cols="30%,70%"]
|====
| `input`
    | Schematic file to export.
|====

Optional arguments:

[width="100%",cols="30%,70%"]
|====
| `-h`, `--help`
    | Show help for the PS file export command.
| `-o <output dir>`, `--output <output dir>`
    | The output folder for the exported files. When this argument is not used,
      the files are exported to the current directory.
| `-t <theme name>`, `--theme <theme name>`
    | The name of the theme to use for export. If no theme is given, the
      schematic editor's currently selected theme is used.
| `-b`, `--black-and-white`
    | Export schematic in black and white.
| `-e`, `--exclude-drawing-sheet`
    | Plot PS without a drawing sheet.
| `-n`, `--no-background-color`
    | Export schematic without a background color, regardless of theme.
| `-o`, `--plot-one`
    | Only export the input sheet; do not export any subsheets.
|====

==== Schematic bill of materials export

The `sch export python-bom` command exports an XML BOM file from a schematic.
The XML BOM file can then be processed into your desired BOM format using a
custom script or one of the scripts described in the
xref:../eeschema/eeschema_generating_outputs.adoc#bom-export[schematic BOM
export documentation].

Usage: `kicad-cli sch export python-bom [-h] [--output VAR] input`

Positional arguments:

[width="100%",cols="30%,70%"]
|====
| `input`
    | Schematic file to export.
|====

Optional arguments:

[width="100%",cols="30%,70%"]
|====
| `-h`, `--help`
    | Show help for the BOM export command.
| `-o <output filename>`, `--output <output filename>`
    | The output filename. When this argument is not used, the output filename
      will be the same as the input file, with a `-bom.xml` suffix and file
      extension.
|====

==== Schematic SVG export

The `sch export svg` command export a schematic to an SVG file. Each sheet in
the design is exported to its own file.

Usage: `kicad-cli sch export svg [-h] [--output VAR] [--theme VAR]
[--black-and-white] [--exclude-drawing-sheet] [--no-background-color]
[--plot-one] input`

Positional arguments:

[width="100%",cols="30%,70%"]
|====
| `input`
    | Schematic file to export.
|====

Optional arguments:

[width="100%",cols="30%,70%"]
|====
| `-h`, `--help`
    | Show help for the SVG file export command.
| `-o <output dir>`, `--output <output dir>`
    | The output folder for the exported files. When this argument is not used,
      the files are exported to the current directory.
| `-t <theme name>`, `--theme <theme name>`
    | The name of the theme to use for export. If no theme is given, the
      schematic editor's currently selected theme is used.
| `-b`, `--black-and-white`
    | Export schematic in black and white.
| `-e`, `--exclude-drawing-sheet`
    | Plot SVG without a drawing sheet.
| `-n`, `--no-background-color`
    | Export schematic without a background color, regardless of theme.
| `-o`, `--plot-one`
    | Only export the input sheet; do not export any subsheets.
|====

=== Symbol

The `sym` subcommand exports symbols to another format or upgrades symbol
libraries to the current version of the KiCad symbol file format.

==== Symbol export

The `sym export svg` command exports one or more symbols from the specified
library into SVG files.

Usage: `kicad-cli sym export svg [-h] [--output VAR] [--theme VAR]
[--symbol VAR] [--black-and-white] [--include-hidden-pins]
[--include-hidden-fields] input`

Positional arguments:

[width="100%",cols="30%,70%"]
|====
| `input`
    | Symbol library file to use for export.
|====

Optional arguments:

[width="100%",cols="30%,70%"]
|====
| `-h`, `--help`
    | Show help for the symbol SVG export command.
| `-o <output dir>`, `--output <output dir>`
    | The output folder for the exported files. When this argument is not used,
      the files are exported to the current directory.
| `-t <theme name>`, `--theme <theme name>`
    | The name of the theme to use for export. If no theme is given, the symbol
      editor's currently selected theme is used.
| `-s <symbol name>`, `--symbol <symbol name>`
    | The specific symbol to export from the library. When this argument is
      not used, all symbols in the library are exported.
| `--black-and-white`
    | Export symbols in black and white.
| `--include-hidden-pins`
    | Export hidden pins in the exported SVG.
| `--include-hidden-fields`
    | Export hidden symbol fields in the exported SVG.
|====

==== Symbol upgrade

The `sym upgrade` command upgrades the the specified symbol library from a
legacy symbol format to the native format for the current version of KiCad. If
the input library is already in the current file format, no action is taken.

Usage: `kicad-cli sym upgrade [-h] [--output VAR] [--force] input`

Positional arguments:

[width="100%",cols="30%,70%"]
|====
| `input`
    | Symbol library to upgrade.
|====

Optional arguments:

[width="100%",cols="30%,70%"]
|====
| `-h`, `--help`
    | Show help for the symbol upgrade command.
| `-o <output filename>`, `--output <output filename>`
    | The output filename for the upgraded symbol library. When this argument is
      not used, the upgraded symbol library is saved over the original library.
| `--force`
    | Re-save the input library even if it is already in the current file format.
|====

=== Version

The `version` subcommand prints the KiCad version. Without any arguments, it
simply prints the version number, for example `7.0.7`. You can print the version
in several other formats using the `--format` argument.

NOTE: Use `kicad-cli version --format about` for version information to include
      when submitting bug reports or feature requests on Gitlab.

Usage: `kicad-cli version [-h] [--format VAR]`

Optional arguments:

[width="100%",cols="30%,70%"]
|====
| `--format <format>`
    | Format of the version number. Options are `plain` (default), `commit`, or
      `about`. `plain` prints the version number (e.g. `7.0.7`), which is the
      default if the `--format` argument is not used. `commit` prints the hash
      of the git commit for the build of KiCad you are using. `about` prints the
      full version information, including library versions and basic system
      information. You can use the `about` version information in bug reports.
|====
