Getting Started

Get started with the pcb CLI

Use this guide to install pcb, create a board repository, validate its Zener source, and generate a KiCad layout.

Requirements

• macOS or Linux. Windows support is experimental; use WSL2 for the most stable Windows environment.
• Git, which pcb new board uses to initialize a repository.
• KiCad 10.x for layout generation and editing. pcb build does not require KiCad.

1. Install pcb

Run the installer for your platform:

bash

curl -fsSL https://raw.githubusercontent.com/diodeinc/pcb/main/install.sh | bash

Default install directories are $HOME/.local/bin on Unix and %USERPROFILE%\.pcb\bin on Windows; override with PCB_INSTALL_DIR.

The installer adds pcb to your user PATH when necessary. Verify installation:

pcb --version

For source builds, see the repository README.

2. Create a board repository

Replace the example repository URL with the project repository URL:

pcb new board Blinky github.com/your-org/blinky
cd Blinky

The generated design is empty but valid. See Packages for repository structure.

3. Build the board

Validate the board source and generate its netlist:

pcb build Blinky.zen

4. Generate the layout

Generate the KiCad files without opening KiCad:

pcb layout --no-open Blinky.zen

This command writes the generated board under layout/.

Toolchains

pcb manages the compiler, stdlib, and sidecars as one toolchain. Workspace commands use pcb-version; pcb auth uses latest stable instead. An explicit pcb +<version> <command> overrides either selection.

pcb toolchain show              # Active and available versions; --offline avoids network
pcb toolchain install latest    # Also accepts nightly, a lane (0.4), or an exact version
pcb toolchain repair latest     # Validate and restore a toolchain
pcb toolchain prune --dry-run   # Preview cleanup; omit --dry-run to remove files
pcb self update                # Update the shim and managed channels

Pruning removes downloads and superseded patches, preserving the newest patch per lane, the active version, prereleases, nightly, and local toolchains.

Service accounts and CI

Run pcb auth login --service-account interactively, or import JSON containing client_id and client_secret:

pcb auth login --service-account --stdin < credentials.json

For CI, supply DIODE_API_URL, DIODE_CLIENT_ID, and DIODE_CLIENT_SECRET through the CI secret store. PCB renews access tokens automatically.

Geometry accuracy

Use the global --accuracy-um option before or after a built-in subcommand to set the accumulated geometry approximation budget in whole micrometres:

pcb --accuracy-um 30 ipc2581 gerber board.xml --output gerbers
pcb gerber normalize top.gbr --accuracy-um 5 --output top-normalized.gbr

The default is 10 µm. The accepted range is 1–100 µm: the lower bound avoids zero and sub-micrometre subdivision costs; the upper bound limits coarse approximation to 0.1 mm rather than millimetres. Smaller budgets can require more time and larger files. This is an approximation bound, not a guarantee that a coarse budget preserves every small feature. Geometry operations still fail if they cannot meet the requested budget.

The option applies to IPC-2581 geometry preparation (info, assembly, CPL, ICT, rendering, HTML, outline/DXF, warpage, board arrays, fabrication panels, and manufacturing export), Gerber normalize/compare/render, and the HTML generated by board releases. It does not change feature-significance or Gerber comparison tolerances. Exceptions:

• pcb dfm and pcb ipc2581 dfm always use 10 µm to keep findings stable.
• Copper balancing always uses its 50 µm profile budget; surrounding panel geometry uses the requested budget.
• KiCad exports, interposer generation, and external commands are not controlled by this option. Release Gerbers are KiCad exports; only release HTML uses it.
• The WebAssembly API keeps its existing defaults; this is a CLI option only.

Troubleshooting

• If the shell cannot find pcb after installation, restart the shell or source the environment file printed by the installer.
• If pcb layout cannot find KiCad, install kicad-cli and pcbnew. Set KICAD_CLI or KICAD_PCBNEW if either executable is outside its default platform path.
• Installers register diode:// links for opening registry layouts in KiCad. If opening fails, check ~/.pcb/pcb-launcher.log (Windows: %USERPROFILE%\.pcb\pcb-launcher.log). ./install.sh --local registers the local toolchain; release installation or pcb self update restores latest.
• Run pcb help or pcb help <command> for the complete CLI reference.