# bim-sketchup

> SketchUp automation via a Ruby extension. Evaluates Ruby against the live SketchUp model and controls the session from a terminal.

## How the connection works

bim-sketchup communicates with a Ruby extension (`bim_bridge.rb`) over a local TCP socket on port 15700. The extension is loaded by SketchUp at startup and runs inside the SketchUp process, evaluating requests on the main thread.

**SketchUp must be running with the extension loaded.** Check with `bim sketchup status` or `bim sketchup doctor`. If the bridge is not loaded, run `bim sketchup install` then restart SketchUp (or use `bim sketchup launch`, which starts SketchUp and waits for the bridge).

## Requirements

- Windows 10/11
- SketchUp installed. `bim sketchup setup` installs Make 2017 (free, ~148 MB from archive.org, no account). SketchUp Pro / 2026 works with `--year` or a `--url` override but requires a Trimble subscription.
- bim_bridge extension installed via `bim sketchup install` (takes effect on next launch)

## First-time setup

```
bim sketchup setup      # download + silently install SketchUp Make 2017 (one UAC step)
bim sketchup install    # write bim_bridge.rb into the Plugins directory
bim sketchup launch     # start SketchUp and wait for the bridge (~13s cold start)
bim sketchup status     # confirm version + extension state
```

## Verb reference

### Session control
- `bim sketchup launch [--path FILE] [--timeout 120]` — start SketchUp and wait for the bridge to be ready; opens `--path` if given. No-ops if already running.
- `bim sketchup close` — quit SketchUp gracefully via `Sketchup.quit`, falling back to a process kill
- `bim sketchup status` — SketchUp version, active model path/name, extension state
- `bim sketchup open --path FILE` — open a `.skp` in the active instance

### Code execution
- `bim sketchup exec --code "Ruby snippet"` — evaluate inline Ruby against the live model; returns the inspected result as JSON
- `bim sketchup exec --file script.rb` — run a `.rb` file

### Export
- `bim sketchup export --output FILE [--path SRC]` — export the active model (or the `--path` source, which is opened first) to the format implied by the output extension: `.pdf`, `.dwg`, `.png`, `.obj`, and others SketchUp supports

### Install / setup
- `bim sketchup setup [--url URL]` — download and silently install SketchUp; defaults to Make 2017. Pass a `download.sketchup.com` URL for Pro. No-ops if already installed.
- `bim sketchup install [--year YYYY]` — write `bim_bridge.rb` into the SketchUp Plugins directory; defaults to the newest installed year
- `bim sketchup doctor` — check that SketchUp is installed and the bridge is loaded

## exec context

`exec` evaluates Ruby with no pre-injected locals — reach the model through the SketchUp Ruby API. The active model is `Sketchup.active_model`.

**Read model info:**
```
bim sketchup exec --code "Sketchup.active_model.name"
bim sketchup exec --code "Sketchup.version"
```

**Count entities:**
```
bim sketchup exec --code "Sketchup.active_model.entities.length"
```

**Add geometry (wrap edits in an operation for undo support):**
```
bim sketchup exec --code "m = Sketchup.active_model; m.start_operation('add', true); m.entities.add_line([0,0,0],[10,10,0]); m.commit_operation"
```

## Gotchas

- The extension must be installed with `bim sketchup install` before first use, and SketchUp must be restarted after install for the bridge to load (`bim sketchup launch` handles the restart-and-wait).
- Make 2017 is the free default target; Pro and 2026 require a Trimble subscription.
- `exec` returns `result.inspect` — the Ruby string representation of the last expression, not a structured object. Build a Hash/Array and return it if you need parseable data.
- Edits that should be undoable must be wrapped in `model.start_operation` / `model.commit_operation`.
- Long-running `exec` calls block the SketchUp UI while they run.

## Related pages
- https://bimcli.com/llms.txt — full bim-cli reference
- https://bimcli.com/revit/llms.txt — bim-revit docs (Revit automation)
- https://bimcli.com/rhino/llms.txt — bim-rhino docs (Rhino automation)