Public command

project

Create and manage KiCad projects. The project create subcommand scaffolds a new project from command flags, a JSONC config, or an interactive terminal form.

Usage

kicad-cruncher project create --name "My Board" --size D --dir ./projects
kicad-cruncher project create --name "My Board" --company "Wavenumber" --rev A
kicad-cruncher project create --name "My Board" --worksheet Magnitude.kicad_wks --with-pcb
kicad-cruncher project create --name "My Board" --symbol-lib WN=${KIPRJMOD}/WN.kicad_sym
kicad-cruncher project create --name "My Board" --text-var REV=A --text-var PROJECT="My Board"
kicad-cruncher project create --emit-config project-create.jsonc
kicad-cruncher project create --config project-create.jsonc
kicad-cruncher project create --tui

Arguments

Three front-ends converge on a single options object: command flags, a JSONC config file, and the interactive --tui form all populate kicad_monkey.KiCadProjectCreateOptions, which kicad_monkey.create_project consumes.

--name sets the project name and the .kicad_pro / .kicad_sch file stem. --size selects the schematic page size from KiCad's standard set (A4 A3 A2 A1 A0 | A B C D E | USLetter USLegal USLedger); the choice list and the default come from kicad_monkey. --dir selects the output directory, and --no-subdir writes into it directly instead of a <name>/ subfolder. --sheet-name sets the top-level sheet/title-block title (defaults to the project name).

--worksheet embeds a .wks drawing sheet into the schematic and references it from the project as kicad-embed://; --no-embed-worksheet references it by path instead. --with-pcb also creates a blank .kicad_pcb, and --no-lib-tables skips the empty sym-lib-table / fp-lib-table.

--company, --rev, --date, and repeatable --comment fill the schematic title block. Repeatable --text-var NAME=VALUE adds project text variables. Repeatable --symbol-lib NICK=URI and --footprint-lib NICK=URI seed the project library tables with references to existing libraries.

--config FILE.jsonc loads every option from a JSONC file (unknown keys are rejected). --emit-config [FILE] writes a commented template whose keys map one-to-one to the option schema, then exits. --tui opens an interactive terminal form covering the same fields.

Ownership

All project construction is owned by kicad-monkey: the blank .kicad_pro seed (KiCadProject.new), the typed option schema and assembly primitive (KiCadProjectCreateOptions, create_project), schematic page size and title-block metadata, worksheet embedding, library-table seeding, the optional blank PCB, text variables, and the standard page-size list and dimensions (KICAD_PAGE_SIZES, kicad_page_size_label).

kicad-cruncher owns only input gathering and ergonomics: flag parsing, the JSONC config load/emit format, the interactive --tui form, logging, and exit status. It does not define KiCad file formats, defaults, or construction logic itself.

Output

A new project directory (a <name>/ subfolder by default) containing:

<name>.kicad_pro: the project file, byte-faithful to KiCad's blank template, with any text variables and the worksheet reference.
<name>.kicad_sch: the top-level schematic at the requested page size, with the title block and any embedded worksheet.
sym-lib-table / fp-lib-table: empty by default, or seeded with the requested symbol/footprint library references.
<name>.kicad_pcb: an optional blank board when --with-pcb is used.

The generated schematic is accepted by KiCad's own CLI (kicad-cli sch erc).

Tests

L0 public CLI tests verify the command appears in root help, command help starts, and the manifest/design-doc inventory stays synchronized. Command-level tests cover flag-to-options mapping, the JSONC config emit/load round-trip, the interactive form submission, and end-to-end project scaffolding through create_project. The underlying KiCad construction (the KiCadProject aggregate, schematic, board, library tables, and worksheet embedding) is owned and covered by kicad-monkey's own test suite, including KiCad CLI validation of the generated schematic.

Interfaces

KiCadProjectCreateOptions

Rationale

The command has three front-ends (flags, JSONC config, and the interactive --tui form). A single typed options schema keeps them in lockstep: adding one field gives every front-end the same knob, and the config keys map one-to-one to it.

Purpose

KiCadProjectCreateOptions is the application-level options record for a new project — name, directory, page size, sheet/title-block metadata, worksheet embed/reference, optional PCB, library-table seeding, and text variables. It lives in kicad_cruncher because it encodes command ergonomics, not KiCad file structure.

Test Requirements

L0 verifies that flags map onto every field, that the command default page size is applied, that the JSONC config round-trips against the schema, and that the interactive form yields a valid options payload.

Working Definition

The interface is working when each front-end produces an equivalent KiCadProjectCreateOptions that create_project can consume without further interpretation.

KiCadProjectCreateResult

Rationale

Callers and the command's own logging need to report exactly which files a scaffold produced without re-deriving paths, so the assembly returns them explicitly.

Purpose

KiCadProjectCreateResult records the written paths — project directory, .kicad_pro, top-level .kicad_sch, optional worksheet, optional board, and the symbol/footprint library tables — produced by create_project.

Test Requirements

L0 scaffolds a project from flags (and from a JSONC config) and asserts the expected files exist on disk at the returned paths.

Working Definition

The interface is working when every non-null path on the result refers to a file that create_project actually wrote for the requested options.