Command-line reference
For the usual workflow, run bgi FILE. It produces a complete manual bundle or a visual comparison with complete bundles for every automatic candidate. See Full example for a complete walkthrough. The commands below expose each step separately for scripts and detailed inspection.
FILE means your .bgi.yaml project. bgi FILE defaults to build/<project-id> and refreshes only its own output for that source file. Other output commands require a new directory. bgi --help shows usage and options, and bgi --version reports the installed version.
Design and make
Section titled “Design and make”| Command | What it does | Result |
|---|---|---|
bgi FILE or bgi run FILE | Search and build in one step, with rendered previews. | One manual bundle or a README gallery and complete automatic candidate bundles. |
bgi solve FILE --output DIRECTORY | Try automatic compartment layouts that satisfy your inputs. | report.md, report.json, and saved candidate-NNN.json files. |
bgi build FILE --solution SOLUTION.json --output DIRECTORY | Generate the selected automatic layout or saved tray arrangement. | A cutting bundle with parts, previews, and assembly guidance. |
bgi build FILE --output DIRECTORY | Generate the arrangement already described in a manual project. | The same kind of cutting bundle. |
bgi explore FILE --output DIRECTORY | Compare supported placements of two to four fully designed removable trays in a valid manual project. | README.md, report.json, candidate bundles, and saved recipes. |
bgi calibrate FILE --output DIRECTORY | Create a small test for measuring cut width and joint fit. | Calibration cutting SVG, guide SVG, and measurement notes. |
solve uses the project’s layout.search.budget and top_k. It saves recipes without building their drawings; use it when you deliberately want only the search result. explore accepts bounded budgets for two to four trays; its candidates already have complete bundles. The automatic layout guide and tray layout guide explain the different inputs and decisions.
build checks the selected design while generating it. For this explicit command, an automatic project needs a saved solution. The output guide identifies the cutting files and assembly instructions.
Inspect a project when something is wrong
Section titled “Inspect a project when something is wrong”These commands are optional tools for a specific question. Normal searching and building already check their inputs.
| Your question | Command | What to look for |
|---|---|---|
| Did I make an input or assignment error while editing? | bgi validate FILE | Field paths, missing references, and invalid dimensions. It creates no cutting bundle and does not replace a full build. |
| Why is a compartment larger than I expected? | bgi requirements FILE | Calculated clear-space requirements, split IDs, and size/orientation alternatives. Compare them with your measurements and allowances. |
| Which material value is being used? | bgi config FILE --resolved | Effective values and whether each came from the profile, project, or CLI. |
| Which material profiles are available? | bgi materials list | Bundled profile IDs and their initial settings. |
| Is a copied or received bundle missing files? | bgi bundle-check DIRECTORY | Whether the files listed in the manifest are present. It does not repeat geometric checks. |
For example, use requirements when a deck unexpectedly needs two spaces or a loose-token compartment seems too tall:
bgi requirements game.bgi.yamlCheck the resulting IDs and dimensions against split_counts, measured stack heights, allowed orientations, and handling allowances. Storage requirements and search explains the calculations; diagnostics explains reported failures.
Additional output options
Section titled “Additional output options”| Option | When it is useful |
|---|---|
build --bom-csv | Add a bom.csv parts list for a spreadsheet or fabrication handoff. |
build --render-preview | Add a rendered PNG to an explicit build: F3D with OpenSCAD when both are installed, otherwise the built-in renderer. bgi FILE requests a PNG by default. |
build --reuse-preview-from DIRECTORY | Reuse a compatible rendered preview from an earlier bundle. |
explore --anchor-tray ID | Keep a tray at its declared X/Y origin. Repeat for more fixed trays; incompatible arrangements are rejected, while layers remain flexible. |
explore --budget N | Limit checked arrangements. Two trays beside fixed containers default to 256 attempts and allow up to 1024; without containers the pair search defaults to six. |
--json | Request machine-readable command output for another tool. Available for run, validate, config, requirements, materials, inventory, solve, explore, build, and calibrate. |
For example, when a cutting service asks for a parts list, add it to your chosen layout’s bundle:
bgi build game.bgi.yaml --solution layouts/candidate-001.json --output fabrication-bundle --bom-csvMaterial overrides
Section titled “Material overrides”Project-reading commands accept --thickness N, --kerf N, --fit-clearance N, and repeatable --set material.PARAMETER=VALUE. Values are millimetres except non-length parameters such as compensation. The project file reference lists the parameters.
A profile provides defaults; project values replace them; command-line values take final precedence for that run. Keep the intended material settings in your YAML so future builds use them. Use a CLI override for a temporary comparison, and config --resolved if you need to confirm which value won. Prepare your material explains when a change needs a new search.
Research inventories
Section titled “Research inventories”bgi inventory FILE reports curated research facts, selected values, and measurement gaps from an inventory file. It creates no project geometry. This is useful when reconciling published component information before measuring a game; it is not a required step when you already have the box and pieces to measure.