The CLI
Everything ships through the typecad-pcb binary that comes with @typecad/pcb. Every command takes --json for machine-readable output, --help for usage, and --version. Flags accept --flag=value or --flag value.
commands
The full command list. Click through the sections below for the flags that matter per group.
Example first
| Command | What it does |
|---|---|
| create | Scaffold a new project (interactive, or scripted with flags) |
| build | Run the entry file and generate the KiCAD outputs into ./build/ |
| add component | Generate a component .ts file from KiCAD, a local file, or JLCPCB |
| add package | Scaffold a reusable, publishable typeCAD package |
| search | Fuzzy-search the KiCAD symbol libraries |
| import | Convert an existing .kicad_pcb into typeCAD TypeScript |
| diff | Visually diff two boards — files or git revisions |
| doc | Render Markdown + a board into an HTML document |
| validate | Type-check and run the entry file without a full build |
| erc / drc | Run the built-in electrical and design rule checks — --kicad for KiCad's own |
| check | Build + unconnected pins + ERC + DRC in one pass, one report |
| diagnostics | Board report: power tree, BOM, ERC/DRC summary |
| query | Ask a built board questions — nets, components, power |
| edit | Small edits to a built board — connect, move, route |
| export gerbers / drill | Fabrication outputs — typeCAD's own writer, no KiCAD needed |
| skills | AI-assistant skill packs for coding with typeCAD |
| package | Browse and install typeCAD packages from npm |
| doctor | Verify the environment; --fix attempts automatic fixes |
| clean | Remove generated build output |
create / build
Project creation and the build loop. Build writes .kicad_pcb, .kicad_sch, .net, and the BOM .csv into ./build/.
Example first
| create flag | Meaning |
|---|---|
| --name=<name> | Project name |
| --hal=<true|false> | Also scaffold a typeCAD/hal firmware project (default false) |
| --git=<true|false> | Initialize a git repository (default false) |
| --yes | Accept defaults — needs --name for fully non-interactive use |
build flags
| Flag | Meaning |
|---|---|
| [entry] | Optional entry file override |
| --watch, -w | Rebuild on file changes |
| --outDir <dir> | Output directory (default ./build/) |
| --skip-erc / --skip-drc | With --diagnostics: leave one check out of the report |
| --diagnostics | Write a Markdown board report (--out=<file.md> names it) |
| --verbose | Chatty output |
add component / search
Finding parts and generating their class files. Passives never need this — they're built in. See Passives.
Example first
| add component flag | Meaning |
|---|---|
| --symbol_source=<kicad|local|jlcpcb> | Where the symbol comes from |
| --footprint_source=<kicad|local|jlcpcb> | Where the footprint comes from — can differ from the symbol source |
| --symbol= / --footprint= | KiCAD library paths for --kicad |
| --c=<C###> | JLCPCB part number for --jlcpcb |
| --folder=<path> | Output directory (default: current directory) |
search
| Flag | Meaning |
|---|---|
| <query> | Fuzzy match against the KiCAD symbol libraries |
| --footprint | Search the installed footprint libraries instead — results show library:footprint and pad numbers |
| --format=<detailed|compact|table|json> | Output style (default detailed) |
| --sort=<score|id|manufacturer|package> | Result ordering (default score) |
| --limit=<n> | Result count (default 5, footprints 10) |
checks
Validation at every level: type-check the source, run the electrical and design rule checks, or produce a full board report. The JSON shapes are stable — checks are CI-friendly.
Example first
| Command | Behavior |
|---|---|
| erc / drc [path] | One check; the board/schematic is auto-detected from ./build/ |
| erc/drc --json | { passed, errors, warnings, ... } — exit code 1 on any failure |
| check [entry] | build → unconnected → ERC → DRC, one report, non-zero exit on failure |
| diagnostics [entry | .kicad_pcb] | Board report to --out=<file.md> (--skip-build, --skip-erc, --skip-drc) |
| doctor | Environment check — Node, config, kicad-cli, libraries, Git; --fix repairs, --json for CI |
| validate [entry] | Type-check and execute the entry without generating files |
terminal
typecad-pcb drc --json
typecad-pcb query unconnected --jsonquery / edit / export / skills
Working with built boards: read them, nudge them, fabricate them, and hand AI assistants the manuals.
Example first
| Command | Behavior |
|---|---|
| query summary|nets|net <name>|components|component <ref>|unconnected|power | Read a built board — --json for machines |
| edit connect <a> <b> [...] | Add a connection — pins as R1.1, nets by name |
| edit move <ref> --to x,y | --left-of <ref> [--gap mm] | Move a part — relative placement included |
| edit route <from> <to> [--width mm] [--layers F.Cu,B.Cu] | Route a pair; --dry-run previews, --file targets a source file |
| export gerbers | export drill -o <dir> | Fabrication outputs (default ./build/gerbers/) |
| skills list | get <name> | search <query> | export | AI skill packs — --out defaults to .claude/skills |