> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pcb.new/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

<CodeGroup>
  ```bash bash theme={null}
  curl -fsSL https://raw.githubusercontent.com/diodeinc/pcb/main/install.sh | bash
  ```

  ```powershell powershell theme={null}
  powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/diodeinc/pcb/main/install.ps1 | iex"
  ```
</CodeGroup>

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:

```bash theme={null}
pcb --version
```

For source builds, see the [repository README](https://github.com/diodeinc/pcb#developing-from-source).

## 2. Create a board repository

Replace the example repository URL with the project repository URL:

```bash theme={null}
pcb new board Blinky github.com/your-org/blinky
cd Blinky
```

The generated design is empty but valid. See [Packages](/pages/packages#repository-structure)
for repository structure.

## 3. Build the board

Validate the board source and generate its netlist:

```bash theme={null}
pcb build Blinky.zen
```

## 4. Generate the layout

Generate the KiCad files without opening KiCad:

```bash theme={null}
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.

```bash theme={null}
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`:

```bash theme={null}
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:

```bash theme={null}
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.