---
name: agentmodel
description: Drive the AgentModel CLI (`agentmodel`) to create, iterate on, measure and share parametric CAD. Use when the user mentions agentmodel or AgentModel, asks for a parametric CAD model, an OpenSCAD model from the terminal, a printable part, an STL to send to a printer, or wants to tweak, render, measure or share a model they already made at model.brightmotion.io.
---

# agentmodel

A command-line client for AgentModel (model.brightmotion.io): describe a part
in words, get parametric OpenSCAD with a customizer, then turn the knobs,
render it, measure it and share it — all without a browser.

## Setup

If `agentmodel` is not installed or not signed in, run this for the user:

```
Set up the AgentModel CLI for me and connect it to my account.

1. Install: `curl -fsSL https://model.brightmotion.io/install.sh | sh`
   (needs Node 20+; re-running upgrades). Make sure ~/.local/bin is on PATH.
2. Run `agentmodel login`. It prints a URL and a short code — show me both
   and wait while I approve it in my browser. Never ask me for a password.
3. Verify: `agentmodel whoami`, then `agentmodel list --limit 5 --json`.
4. Install the skill so you know the commands:
   mkdir -p .claude/skills/agentmodel && curl -fsSL https://model.brightmotion.io/skill.md -o .claude/skills/agentmodel/SKILL.md
   (or the equivalent skills folder for your tool).
   Docs: https://model.brightmotion.io/docs · agent index: https://model.brightmotion.io/llms.txt

Rules: use `--json` when you read output. `new`, `say` and `generate` spend
money — tell me before running them. `set`, `push`, `pull`, `measure` and
`check` are free.
```

On a machine with no browser add `--no-browser` to `login` — the URL and code
are printed either way. In CI, skip `login` entirely and set `AGENTMODEL_TOKEN`
(or `AGENTMODEL_EMAIL` + `AGENTMODEL_PASSWORD`).

## The mental model

- **A conversation is a tree of messages.** Retries, edits and `--at` branch
  it. The **leaf** is the active tip — what the site shows and where a new
  message lands.
- **A generation is an assistant message carrying OpenSCAD.** That is what you
  preview, parameterise, pull and diff.
- **A `<ref>` names one:** `latest` (default), `v3` (third generation on the
  active branch), `~1` (one back), or a message-id prefix.
- **Reads never move anything** (`pull --at v2`, `params --at v2`, `diff`).
  **Writes at an old ref branch from it** (`set --at v2`, `say --at v2`,
  `push --at v2`) — the same as clicking an old version on the site and
  tweaking it. `focus <conv> <ref>` moves the leaf without creating anything.
- **`vN` follows the active branch.** After `focus` to an older ref, the
  newer generations are off-branch: they keep existing, lose their `vN`, and
  are addressed by id prefix. `history --all-branches` lists them, marked
  `(off-branch)`; nothing is lost.
- Every id — conversation **and folder** — accepts a **unique prefix**, and
  anywhere a conversation is expected you can paste a `/share/…` or
  `/editor/…` URL.
- Only real customizer parameters can be `set`: hidden (`/* [Hidden] */`),
  `$`-prefixed and computed values are refused with exit 2.

## Money — the one rule that matters

`new`, `say` and `generate` call a model and **cost the user money**. Say what
you are about to run and roughly why, and let them stop you. Everything else —
`params`, `set`, `diff`, `push`, `pull`, `measure`, `check`, `share`, `list` —
is free and deterministic. Prefer the free path: if the change is a dimension,
it is `set`, not another generation.

## The loops

**Tune what exists** (no LLM, nothing billed):

```
agentmodel params <conv> --json          # what knobs exist, with ranges
agentmodel set <conv> width=42 --json    # rewrite them in the source
agentmodel pull <conv> views             # 4 renders + a contact sheet
# look at the PNGs, then set again
```

**Bring your own OpenSCAD** — your code becomes a real version on the thread,
with the same preview, params panel and share links:

```
agentmodel push <conv> model.scad -m "why"
agentmodel pull <conv> views             # …then look at what you pushed
```

**See what was actually said and sent:**

```
agentmodel show <conv> --messages --json  # every message, text + files
```

Each message carries its text and its `attachments` records; an empty array
means nothing was attached to it. That is how you confirm a photo reached the
model — `new`/`say`/`generate --json` report the same records for the message
they just created.

**Check before printing:**

```
agentmodel measure <conv>                # bbox, volume, area, triangles
agentmodel check <conv> --strict         # exits 1 if the mesh is not manifold
```

Rendering (`stl`, `png`, `views`, `gif`, `mp4`, `measure`, `check`) happens
**locally** and needs OpenSCAD installed; `views`/`gif`/`mp4` also need ffmpeg.
The server stores source, not meshes.

## Output contract

Pass `--json` whenever you need to read the output: exactly one JSON object on
**stdout**, human tables on **stderr**. `--quiet` silences stderr entirely.

| Exit | Meaning               |
| ---- | --------------------- |
| 0    | ok                    |
| 1    | error                 |
| 2    | not found / bad usage |
| 3    | auth or approval      |
| 4    | quota / spend cap     |

## Cheat sheet

| Command                                          | Does                                        |
| ------------------------------------------------ | ------------------------------------------- |
| `login` / `logout` / `whoami`                    | connect (browser approval), disconnect, who |
| `list [--since 7d] [--limit 20]` (`ls`)          | the user's creations                        |
| `search <q> [--by <handle>]`                     | by title, or someone's public profile       |
| `show <conv> [--messages]`                       | summary; `--messages` = the transcript      |
| `history <conv> [--all-branches]`                | the version tree, `v1…vN`, leaf marked      |
| `new "<prompt>" [-a photo.jpg] [--model …]`      | **costs money** — create and generate       |
| `say <conv> "<message>" [--at <ref>]`            | **costs money** — iterate                   |
| `generate <conv> [--attempts 3]`                 | **costs money** — retry from the leaf       |
| `models`                                         | model picker with prices per 1M tokens      |
| `params <conv> [--at <ref>]`                     | the customizer parameters                   |
| `set <conv> w=42 d=6.5 [--at <ref>] [--check]`   | rewrite values, checkpoint a version        |
| `diff <conv> <ref1> <ref2> [--bbox]`             | parameter + source diff                     |
| `focus <conv> <ref>`                             | move the leaf, create nothing               |
| `push <conv> model.scad [-m "…"]`                | your OpenSCAD as a real version             |
| `push --new "<title>" model.scad`                | catalog a local model                       |
| `pull <conv> scad\|stl\|png\|views\|gif\|bundle` | source, or render locally (`-o <path>`)     |
| `measure` / `check [--strict]`                   | bbox, volume, manifold verdict              |
| `share link\|email\|list\|revoke <conv>`         | share URLs and per-recipient tokens         |
| `privacy <conv> private\|unlisted\|public`       | who can see it                              |
| `rename` / `move` (`mv`) / `folders`             | organize                                    |
| `fork <conv\|share-url>` / `note <conv> "…"`     | copy someone's model / annotate yours       |
| `delete <conv> [--yes]` (`rm`)                   | permanent, asks first — `--yes` for agents  |

`--model` aliases: `gemini-3.7-flash`, `gemini-3.8-flash`, `gemini-3.1-pro`,
`claude-fable-5`, `claude-sonnet-5`, `claude-opus-4.8`, `gpt-6-astra`,
`gpt-5.6-sol`, `glm-5.3`. Attachments (`-a`, repeatable, ≤ 4 per message):
images for any model, video only for Google models.

## Where the manual is

- <https://model.brightmotion.io/docs> — install, overview, full reference
- <https://model.brightmotion.io/docs.md> — the same manual as raw markdown
- <https://model.brightmotion.io/llms.txt> — the short index for agents
- `agentmodel --help` — every command, grouped
- `agentmodel <command> --help` — one command with its flags