This guide is written for AI agents that edit BenchUp projects through the benchup command line or its MCP server (see Over MCP for the differences). Agents read it with benchup guide (over MCP, the get_guide tool), and it always matches the installed version.
- Lengths are millimetres. Z is up. X runs left to right (width), Y is depth, and the front of a piece faces -Y: the BenchUp front view looks from -Y, so a wall behind a piece is on its +Y side.
create_boardtakes the minimum corner (origin_mm) and the size along X, Y and Z (size_mm). Prefer it to drawing.- Set the grain along a board's longest side: Z for sides and legs, X for shelves, tops and rails.
- Common thicknesses: 16, 18 or 19 mm for panels, 12 to 15 mm for drawer sides, 6 mm (3 to 9 mm) for backs and drawer bottoms. Legs are 40 to 80 mm square.
- Read the model first with
get_scene(benchup scene). It lists the project name, objects with their sizes, joints, dimensions, texts, loose geometry and stock materials. On a big project, filter it:depth0 lists only top-level objects,idslists those objects and what is inside them,fieldskeeps only some object fields (["name", "size_mm"]), andsectionskeeps only some parts (["objects"]). - Plan the whole change. For anything with repeated parts, write a small script that computes the positions and prints a batch file.
- Apply it as one batch: one undo step, and all-or-nothing.
- Verify:
check_modelfinds boards that pass through others, overlaps without a joint, joints that cannot be cut or look reversed, boards thicker or thinner than their material, and loose geometry. It also counts the joints that cut. Readpassed(no errors or warnings);okonly says the check ran.get_objecton a joint shows its settings and status.get_cut_listlists the boards to cut;get_estimategives the time to build them.benchup render file.bup --view front(over MCP,render_view) draws the model as a PNG, joints and profiles cut, with dimensions and text notes (in capitals, without accents). Its output lists dimensions whose labels overlap and the notes with their position. It shows the whole model; details of a few millimetres need--size 2400x1800.
- With the CLI,
benchup open file.bupshows the result in the desktop app. The CLI edits the file, not the open window, but BenchUp versions after 0.7.1 reload the file by themselves about a second after each change (with older versions, runopenagain). If the project has unsaved changes in the app, BenchUp asks the user first: tell them to choose "Reload from disk" to see your edit, because keeping their changes and saving overwrites it.
- Every call that changes the model returns
created,modifiedanderasedids. Some return more:joint_id(add_joint,set_joint),material_id(create_stock_material),face_id(draw_polylineandpush_pull),faces(split_face),edges(add_profile) andmembers(group).benchup tools <name>describes each tool. - Ids are not consecutive, so always take them from results. In a batch,
"$N.field"is a value from call N's result, counting from 1. Any field works, including nested ones:"$1.created[0]","$3.joint_id","$2.material_id","$4.members[0].id","$5.created[-1]". A reference may stand in for any argument, even where the schema says integer or uuid. A reference to a list of ids inside a list is spliced in, so"ids": ["$1.created", "$2.created"]joins both; other lists, such as a point inpoints_mm, stay one item. Text that is not exactly a reference, such as"$12.50 hardware", is kept as written. - With the CLI,
--dry-runreports every result without changing the file; ids made in a dry run differ from the real run. End a dry-run batch withcheck_modelto validate the change before applying it.check_modelwith"only_new": truereports only the problems the batch introduced, leaving out those that were already in the project. Read tools inside a batch see the batch's earlier changes.--briefleaves out the object summaries of changing calls and keeps ids and bounds. - When a call in a batch fails, nothing is changed. The output names the failed call and shows
earlier_results, what the calls before it returned.
The tools are the same. What the CLI does with flags, MCP does with three extra tools:
run_batch {calls, dry_run}runs several calls as one undo step, all or nothing, with the same"$N.field"references as a batch file.dry_run: truereports every result and saves nothing; end it withcheck_model {"only_new": true}.undotakes back the last call or batch (redo: trueto redo it).render_viewreturns the image of a view.
Each other call is saved on its own, so prefer run_batch for any change of more than one call. The schemas are in the server's tool list; there is no --brief.
- Every board is a group. Editing tools (
move,resize_board,rename,tag,erase,add_joint,push_pull…) reach parts inside groups and components by themselves when all the ids in a call share one group. Ids from different groups need separate calls. - To create a part inside a group, open it with
enter_object(nested groups from the outside in). With the CLI, the opened group lasts only for that command, so putenter_objectand the creating calls in one--batchand finish withexit_to_root. groupwith several ids makes ONE group, or one component withcomponent: true. With one board andcomponent: true, it wraps that board in a new component. Grouping keeps existing joints. Two components with the same name are still different definitions; onlycreate_copymakes linked instances.- Components suit identical parts whose joints stay inside them, such as a drawer box. Build one completely, including its joints, make it a component, then
create_copyit to each position. Instances of one component share adefinitionid in the scene. - A joint can only be added between boards at the same level. A board inside a component instance cannot be joined to a board outside it. Making a board that already has joints into a component keeps those joints, but
create_copydoes not copy joints with boards outside the component, and they cannot be added to the copies. - When the user asks for housed parts to be one component (shelves in grooves in the sides), it cannot keep the grooves. By default keep them as separate identical boards, with the same name and tag, and say why. Offer the alternative: one component of shelves resting on pins or cleats, without joints to the sides.
- A tag on a group applies to the boards inside it (the scene shows the inherited tag). Tag boards directly when parts of one group need different tags.
- Erasing a board also removes its joints.
remove_jointdeletes a joint alone. Moving, resizing or rotating a board keeps its joints.
A joint joins two boards that overlap where they meet; the overlap is the joint's depth. Make the overlap first by placing one board partly inside the other, then call add_joint. Joints are cut when BenchUp evaluates the model, so the scene still shows plain boxes. get_object on the joint reports "status": "ok" or the reason it cannot be cut, and add_joint refuses joints that cannot be cut.
acarries the tenon, tongue, tails, fingers or lap: the board that goes into the other (shelf, apron, drawer side, back panel).breceives the mortise, groove or sockets (side, leg, drawer front).- Leave
depth_axis/width_axisout. BenchUp picks the woodworking orientation: depth is the directionagoes intob. Tongues, tenons and rabbets are spread acrossa's thickness; dovetails, fingers and laps across its broad side. The result reports the chosen orientation. - A joint with
aandbreversed would cut the tongue into the side and the groove into the shelf.check_modelreports it, andflip_jointswaps the roles while keeping the joint's settings. get_objecton a joint shows itsgeometry: the region cut (region_mm), the depth and the directionagoes intob, the tenon or tongue thickness, andcut_in_b, whether the groove or mortise runsthroughb, isstoppedat one end orclosedinside it, along each axis across the depth.set_jointchanges an existing joint's kind or params, keeping the rest. The joint must still cut.- Trimming excess: where a board runs past the other (a rail through a leg, a side past a top),
"trim": "a"(or"b") in the params cuts that board flush with the other board's outer face;keep_end(lowerorupper, alongtrim_axis, default the board's longest axis) says which end of it stays. - Settings by kind:
mortise_tenonuseswidth_ratio(tenon thickness as a share ofa's thickness) andheight_ratio;tongue_grooveandrabbetusewidth_ratio;dovetailusesdovetails,width_ratio(share of the width taken by tails) andtaper_degrees;fingerusesfingers. All useclearance_mm.
| Situation | Overlap | Joint |
|---|---|---|
| Shelf housed in a side | Shelf enters the side by about half the side's thickness (9 mm into 18) | tongue_groove, a = shelf, b = side |
| Apron into a leg | Apron enters the leg 25 to 35 mm, set back 5 to 10 mm from the leg's outer face | mortise_tenon, a = apron, b = leg, width_ratio about 0.33 (tenon one third of the apron's thickness), height_ratio about 0.75 |
| Back panel in a groove | Back (6 mm) enters each side by about half the side's thickness, 6 to 10 mm in from the back edge | tongue_groove, a = back, b = side |
| Back panel in a rabbet | Back enters each side by about half the side's thickness, flush with the back edge. Stop housed shelves 2 mm short of it (see below) | rabbet, a = back, b = side. This cuts both parts: a tongue on the back's edge (its front width_ratio share) in a slot in the side, leaving a lip of the side behind the back. For a classic open rabbet with the back left whole, rout it instead: add_profile rabbet on each side's back inner edge ([["+y", "+x"]] on the left side), as wide as the back is thick and half the side deep, with the back sitting in it and no joint |
| Drawer side into the front (half-blind dovetail) | Side enters the front from behind, leaving 4 to 6 mm of the front | dovetail, a = drawer side, b = front, dovetails 3 to 5 |
| Drawer bottom | Bottom (6 mm) enters the drawer sides by 6 mm and stops 1 to 2 mm behind the front, clear of the dovetails | tongue_groove, a = bottom, b = side |
| Drawer back | Back (12 to 15 mm) enters the drawer sides by half their thickness, standing on the bottom | tongue_groove (a dado), a = back, b = side. Sitting on the bottom is fine: its dado and the bottom's groove only touch along the bottom's face. If the joint is refused, raise the back 1 mm |
| Frame corners | Rails and stiles cross by their full width | half_lap, a = rail, b = stile |
| Box corners | Two panels overlap by the other's thickness | finger, a and b either way |
| Plinth between the sides | Plinth enters each side by about half the side's thickness | tongue_groove, a = plinth, b = side; or butt it without a joint |
| Top on the sides | Sides enter the top from below; the groove shows at the top's edges unless the sides stop short of them | tongue_groove, a = side, b = top; or rest the top on the sides and note the fixing |
Two joints cut into the same board must not cross, and must not meet face to face inside it. For example, a shelf's groove that ends exactly where the back's rabbet begins leaves a sliver of zero thickness. The joint is then refused with a "closed solid" or "valid solid geometry" error, and the error names the other joints on those boards that touch it. Joints that only share the board's outer face are fine, such as a back and a plinth both reaching the floor. Keep at least 1 to 2 mm of wood between joint regions inside a board:
- Shelves and a back: stop shelves, top and bottom 1 to 2 mm short of the back, not flush with it. Then a rabbet or a groove for the back both work.
- Drawer bottom: groove it into the drawer sides only, and stop it 1 to 2 mm behind the front. Where the sides already enter the front with dovetails, a groove in the front would meet them.
- The same error with no other joint nearby is a precision limit of the joint cutter, not a clash. On a shaped board it comes from many small faces or vertices very close to the joint's planes: change the number of segments of a curve (24 and 48 are known to work). On plain boards it can appear on the second joint of a board, for example a rail with a tenon at each end: change
height_ratioorwidth_ratioslightly (0.6 → 0.65), move one board by 0.5 to 1 mm, or add the joints in the other order (they are cut in the order they were added). Test in a--dry-run. - Two aprons meeting in one leg: their tenons must not meet inside the leg. With leg width P, apron setback s from the leg's outer face and apron thickness t, keep the tenon depth below P − s − t (70 − 10 − 22 = 38 mm, so use 30).
- A central divider: shelves on both sides at the same height would cut it through with two 9 mm grooves. Let them enter by a third of its thickness each, stagger the heights, or butt them against it without a joint.
- Carcass (cabinet, bookcase): two sides, a top and a bottom (between the sides, or the top over them), shelves, and a back in a groove. Stop everything inside 1 to 2 mm short of the back.
- Even shelves:
distributethe shelves along z between the inner bottom and the inner top (from_mm,to_mm; without a bottom or top, the floor and the top of the sides, as the original spacing shows); the gaps above, below and between are equal, (H - n·t)/(n + 1), and the result reportsgap_mm. Use"mode": "centers"for equal centre spacing. To change the number of shelves, erase or copy shelves, thendistributethem again; their joints follow. With several columns, distribute each column in its own call. Check the clear height between two shelves withmeasure_spaceat a point between them. - Plinth: a board 60 to 100 mm high between the sides, set back 20 to 50 mm from the front, usually under a bottom panel resting on it. A divider that reaches the floor splits it in two; butt each half against the divider.
- A back behind a central divider: stop the divider at the back's front face so one back runs behind both bays.
- Edge profiles:
add_profilerouts a chamfer, bevel, roundover, cove, rabbet, groove, ogee or bead along a board's edges with BenchUp's Router. Name an edge by the two faces it lies between:[["+z", "-y"]]is the top front edge,[["+z", "*"]]every edge of the top face,[["-y", "-x"]]the front vertical edge on the left (a corner seen from above); face ids fromget_objectwork too.width_mmis the width or radius. For a rabbet or groove, which face gets the width and which the depth depends on the edge: check it in a dry run (the part that should sit in the rabbet shows as an overlap incheck_modelif it went the wrong way) and passreverse: trueto swap them. The call fails when the profile cannot be cut (too big, or an edge next to a notch); try a smaller size or other edges.get_objectlists a board's profiles;remove_profiletakes them off. - A top with chamfered or rounded front corners over the sides: let the top overhang the sides at the front by at least the chamfer, or set the sides back, so their corners do not show under the cut.
- Table: legs 60 to 80 mm square; aprons 80 to 120 mm high and 20 to 25 mm thick, their tops flush with the legs, tenons as above; a top 25 to 40 mm thick resting on the frame with a 20 to 50 mm overhang. Ask whether the size given is the top or the frame, and whether the height includes the top.
- Drawer: build one drawer as a component (front, sides, back, bottom and their joints), then
create_copyit up by the front's height plus the gap. Inset fronts leave about 2 mm at each side and 3 to 4 mm between drawers. The box (sides, back and bottom) has sides 12 to 15 mm thick and 30 to 50 mm lower than the front, and is 10 to 20 mm shorter than the carcass's inner depth. The bottom is 6 mm, grooved into the sides about 10 mm above their lower edge, and the back sits on the bottom. With metal runners, make the box about 12.5 mm narrower on each side, or as the runner specifies; with wooden runners, about 2 mm. - Lengthening a piece:
resize_boardthe boards that run in that direction, choosing the end withanchor, andmovethe parts at that end.resize_boardstretches the whole board, notches included. For a board with notches or a shape,push_pullits end face by the extra length instead; that keeps the notches where they are. To push only part of a face,split_faceit first, by aline_mmacross it or where aplanecrosses it; the result lists the pieces with theircenter_mmand area. Afterwards,merge_faceson the board removes seams between flat faces in one plane, also around an opening such as a pocket's mouth. Do noteraseseam edges: erasing an edge removes the faces on it. A pocket or mortise cut by hand in the middle of a face is cleaner drawn than split:enter_objectthe board, draw the mouth as a closeddraw_polylineinside the face (not touching its edges), andpush_pullthat face in;split_faceplanes cross the whole face and leave seams to merge. A joint withadd_jointis better still when another board goes into it. - Before choosing which end to lengthen, look for walls and other parts in the way.
measure_spaceat a point gives the free distance along each axis to the nearest face and what it belongs to, walls made of plain faces included.find_surfaceslists large flat faces that are not boards, such as a room's walls and floor drawn as faces inside groups, with their plane (y = 400);include_solidsadds faces of closed parts, such as a solid floor. - Changing the stock thickness while keeping the outside size:
change_thicknessthe boards in one call, with the new material inmaterial_id. Boards on the outside of the given set keep their outer face, the others their centre; boards that go into a resized board with a joint are lengthened or shortened so the joint keeps the same share of the new thickness (half stays half), and boards that only butt against a resized board (shelves against a divider) follow its face.anchorapplies to every board of the call: call it twice for different anchors. Pass"anchor": "min"to keep whole millimetres on shelves when an odd change would give half millimetres. Recompute equal gaps only if asked (distribute).check_modelreports boards whose thickness does not match their material. For rotated boards, useresize_boardwithanchorinstead. - A leaning piece (ladder shelf): work out each upright's outline as it will stand: back edge leaning θ from vertical and touching the wall at the top, foot and top cut level. Rotate that outline by +θ about x around the foot of its back edge, which stands it upright, and draw it there (see shaped boards). Set its grain to z, then
rotateit by −θ about x around the same point, so its top leans towards the wall at +Y. An upright of constant width w (measured square to its edges) and height H has edges H/cos θ long and level cuts w/cos θ long, and the foot of its back edge sits H·tan θ from the wall. Uprights of constant width give every shelf the same depth. For shelves that get shallower towards the top, taper the uprights (wider at the foot), or let the shelves stick out in front of narrow uprights. Keep shelf edges a few millimetres away from the uprights' sloping faces; a near-coincident edge leaves slivers smaller than the model precision. In the scene, a rotated board's grain shows as a vector, and the cut list measures it unrotated. - Materials and cut list:
create_stock_material(name, thickness, width, length; the length along the grain), thenset_materialon the boards. The material's thickness should match the boards'.get_cut_listgroups boards by material and size;minimum_stock_pieces, an area lower bound, appears once boards have a material with sizes. To answer "how many sheets do I need" without changing the project, create and assign the material and callget_cut_listin one--dry-runbatch. - Finishes and time:
set_finishon boards or a whole group:sanding_grits([120, 180, 240]) and thepre_stain,stainandvarnishstages with their coats, drying hours and look (tint_rgb,sheen).get_estimate(all boards, orids) adds up finishing time per stage from each board's area, joint cutting by kind and router profiles by length, with BenchUp's default allowances, and lists the wood by material. Rates and prices edited in the app are not in the project, so it gives no costs. - Dimensions for the workshop: put overall height and width, and a chain of shelf gaps, in the front plane (y = 0) so they read in the front view; put the depth in the side plane (x = the width), offset upwards. A dimension measures the straight distance between its points. Pass
axisto measure only along x, y or z, so a slightly misplaced point cannot tilt it. Points exactly on a corner, edge or face attach to it and follow it. Nothing snaps, so use real corners: where a shelf enters a side, its visible corner is on the side's inner face.offset_mmpushes the line away from the piece: chain dimensions about 100 mm out, overall ones about 250 mm out, so they do not overlap.add_dimensionreturnslength_mm, andget_scenelists every dimension. Put the piece's name in a text above it. Ask whether shelf spacing means clear space or centre to centre.
For a chamfer or a rounded edge along a board, use add_profile (see the recipes); it keeps the board a simple box with a profile. For a board whose outline is shaped (a curved front, angled ends, a cut-out corner), use create_profile_board: the outline, its plane, the thickness, grain, name, material and tag in one call.
-
origin_mmis where the outline's (0, 0) is. A negativethickness_mmextrudes the other way. Each plane, seen from where u points right and v up:planeu v seen from extrudes along typical parts xyx y above +z tops, shelves, bottoms xzx z the front (-y) +y, away from you fronts, backs, rails yzy z the right (+x) +x, towards you sides "Counter-clockwise" and "to the right of travel" are as seen from there. A side's front edge (y = 0) curving inward, towards +y, is an arc with a negative sagitta when the outline runs counter-clockwise in
yz. -
Points are
[u, v]in mm. A point written{"at": [u, v], "sagitta_mm": s}or{"at": [u, v], "bulge": b}makes the segment from it to the next point an arc. The sagitta is how far the arc's middle is from the straight line between the two points; bulge = tan(angle/4), so 1 is a half circle and 0.414 a quarter. Positive values bulge to the right of the direction of travel, which is outward on a counter-clockwise outline (seen as in the table above). -
Arcs get 12 segments per quarter turn, 24 for a half circle, unless
segmentssays otherwise. 24 and 48 segments are known to work with joints; some other counts (32, 40) can make joints impossible to cut.
{"tool": "create_profile_board", "arguments": {"name": "Top", "plane": "xy", "origin_mm": [0, 0, 700], "thickness_mm": 20, "grain_axis": "x", "points": [{"at": [0, 0], "sagitta_mm": 40}, [800, 0], [800, 400], [0, 400]]}}This top is 800 × 400 with a front edge curving 40 mm forward (to y = -40), counter-clockwise from above. For a curved edge with chord c and depth s, the radius is R = (c²/4 + s²)/(2s). Parts behind a curved front (shelves, a bottom) must be set back far enough to stay behind the curve at their height.
The cut list measures a board along its grain, so draw a part in its natural orientation, set the grain, then rotate it into place. Joints work on shaped boards too. Check the result's bounds_mm; an outline that crosses itself or does not make a closed board is refused.
Drawing by hand still works when needed: one closed draw_polyline on the plane where the board starts, push_pull its face to the thickness, group everything the two calls created, then set_grain. A loose face's normal follows the order of its points: counter-clockwise seen from the side it faces.
Avoid cutting through a finished board with a negative push_pull of its full thickness. It currently leaves stray faces and edges, and check_model reports an open solid. Rebuild the part from its outline instead.
- A requested size does not fit, such as a shelf longer than its opening. Measure the free space from
bounds_mm: from one board's inner face to the next. A housed shelf is that gap plus both overlaps. Try the change in a--dry-runbatch ending withcheck_model, report what you measured, and ask instead of forcing it. - Ambiguous terms. Ask whether "two columns" means two bays, and whether shelf spacing is clear space or centre to centre. Ask whether "1000 mm from the floor" is the top or the bottom face. Ask whether a front is inset or overlaid, which end of a piece to lengthen, and whether a size is the top or the frame. "The sides" of a bay can include a divider.
- A request that conflicts with how the piece is built, such as housed shelves as one component. Keep the construction, do what can be done, and offer the alternative.
- Problems already in the model that the user did not mention, such as joints
check_modelreports as reversed. Report them and offer to fix them. If the change touches those joints anyway, fixing them is reasonable, also when you cannot ask: do it as a separate batch so it can be undone on its own; that does not count as departing from the request. Otherwise only report them. - In each case, propose an interpretation and say which one you used.
- When you cannot ask (no one to answer), do not apply a change that departs from the request. Leave the project as it was, save the tested alternative as a batch file, and report both.
- Joints are cut from the overlap when BenchUp evaluates the model. The tools show the boards before cutting; use the joint's
statusto confirm. - There is no fixing hardware (screws, dowels, metal runners). Leave a top resting on its frame, and note the fixing with
add_textif it matters. - The tools cannot read or set BenchUp's saved views and cameras; saved views are left as they were. To look at the model,
benchup render(over MCP,render_view) draws one of the standard views (iso, front, back, left, right, top, bottom), not a saved camera; ask the user to look in BenchUp when a particular view matters. - Some BenchUp features are not available through the tools yet: the Cutting Plan (stock layouts with saw kerf and grain), Workshop Labels and the PDF exports.
get_cut_listgives an area lower bound; for a real layout, the user can export the Cutting Plan from BenchUp's Tools menu.get_estimatecovers time with default allowances, not costs.