# Visual UI editing with Gemini CLI

> Use Google's Gemini CLI as a visual UI editor on your running app. Set it up with a Gemini API key, the model GUIJam uses, and what to expect.

GUIJam gives Gemini CLI a visual front end. Circle an element on your running app, describe the change, and Gemini CLI proposes live UI variants you preview in the page before anything is written.

[Gemini CLI](https://github.com/google-gemini/gemini-cli) is verified live with a Gemini API key and `gemini-3-flash-preview`.

## Set up

### Install it

```bash
npm install -g @google/gemini-cli
```

### Get an API key

Create a key in [Google AI Studio](https://aistudio.google.com/apikey), and set it where you start your dev server:

```bash
export GEMINI_API_KEY=<your key>
```

Vertex AI works too.

### Choose the key in Gemini CLI

Run `gemini`, type `/auth` and choose **Use Gemini API Key**. Gemini CLI keeps using a saved Google login even when `GEMINI_API_KEY` is set, so this step matters.

### Choose it in GUIJam

```bash
npx guijam provider use gemini-cli
```

> **Personal Google logins no longer work**
>
> Google no longer lets Gemini CLI use a personal Google login. If Gemini CLI still uses one, the widget shows "Gemini CLI was refused: Google no longer lets Gemini CLI use a personal Google login (IneligibleTierError)…" and tells you to set `GEMINI_API_KEY` and choose it with `/auth`.

## The model GUIJam uses

GUIJam asks Gemini CLI for `gemini-3-flash-preview` on every request, because it answers quickly. Gemini CLI's own automatic choice can pick newer Flash models that, on the free tier, answer 503 "high demand" and keep retrying past GUIJam's [time limit](https://guijam.francistinao.com/docs/guides/draw#time-limits). The 2.5 models aren't available to new users.

To use another model:

```bash
npx guijam provider use gemini-cli --model <model>
```

## Login status

Gemini CLI has no login-status command, so GUIJam shows its status as unknown until a request runs.

To find out for sure, `init` offers to send Gemini CLI one short test request. It spends a few tokens. Run the same check any time:

```bash
npx guijam doctor --probe
```

## When Gemini CLI refuses a request

The widget repeats what Gemini CLI said, and tells you what to change:

| Message                                                                                                       | What to do                                                                                                                   |
| ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| "Gemini CLI was refused: Google no longer lets Gemini CLI use a personal Google login (IneligibleTierError)…" | Set `GEMINI_API_KEY` where your dev server starts, choose it in Gemini CLI with `/auth`, restart the dev server, then retry. |
| "Gemini CLI was refused: `<what Gemini CLI said>`." For example, an invalid API key or no auth method set.    | Fix the key, or run `gemini` and choose `/auth`. Then retry.                                                                 |

If Gemini CLI stops before answering, the widget shows the last line it printed: "Gemini CLI stopped before answering: `<last line>`." Every failed run is also logged in `.guijam/logs/gjd.log`, with the Gemini CLI version and the model.

## Limits

- Gemini CLI can't read images in GUIJam, so [sketches](https://guijam.francistinao.com/docs/guides/sketch) and attached images need another tool.
- GUIJam runs it with a deny-all policy for quick requests and plan mode for larger ones, and loads none of your MCP servers or extensions, so it can't change files.
