# @google/stitch

Generate UI screens in Google Stitch from a prompt, pull your running app's pages onto the Stitch canvas, and iterate on them from your terminal or coding agent.

```bash
npx @google/stitch generate screen \
  --new-project "Mobile Onboarding Flow" \
  --prompt "Sign-up step with email and phone verification" \
  --device MOBILE
```

This creates a Stitch project, generates one mobile screen into it, and prints the project and screen IDs.

### Bring an existing page into Stitch and redesign it

Capture a route from your local dev server as a self-contained HTML file, upload it as a screen, then edit it with a prompt:

```bash
stitch capture http://localhost:3000/checkout          # saves .stitch/captures/checkout.html
stitch upload screen .stitch/captures/checkout.html --route /checkout --title Checkout
stitch edit screen <screen-id> --project <project-id> --prompt "Use a two-column layout"
```

### Explore variants of a screen

```bash
stitch generate variants \
  --project <project-id> \
  --screen <screen-id> \
  --prompt "Try warmer colors and a denser layout" \
  --count 3 \
  --creative-range EXPLORE \
  --aspects LAYOUT,COLOR_SCHEME
```

### Preview a project's screens locally

```bash
stitch serve -p <project-id> --port 3000
```

### Use it from a coding agent

Every command accepts `--json` for structured output, `--json '{...}'` for raw input payloads, and `--schema` to print the JSON Schema of what it accepts. Agents can discover the API without reading docs:

```bash
stitch generate --schema                 # which resources can be generated
stitch generate screen --schema          # payload schema for one resource
stitch find projects --limit 10 --json
```

Or register the bundled MCP server with your editor:

```bash
stitch mcp install
```

---

## Install

```bash
npm install -g @google/stitch
```

Requires Node.js 20 or later. Installs two binaries: `stitch` and `stitch-mcp` (same as `stitch mcp start`).

## Authentication

```bash
stitch login     # Google OAuth in the browser; tokens are stored locally and refreshed automatically
stitch status    # shows which credentials are active
stitch logout    # removes stored OAuth credentials and saved API keys
```

Canvas commands (projects, screens, design systems) may require an API key in addition to OAuth. If a command fails with `MISSING_CANVAS_CREDENTIALS`, set one:

```bash
export STITCH_API_KEY=your-api-key
```

| Credential | Flag | Environment variable |
| :-- | :-- | :-- |
| API key | `--api-key` | `STITCH_API_KEY` |
| OAuth access token | `--access-token` | `STITCH_ACCESS_TOKEN` |

`stitch login` options: `--port` (loopback callback port, default `8085`), `--json`.
`stitch status` options: `--flow design|loop`, `--token` (print a valid bearer token), `--json`.

## Configuration

Per-repository defaults live in `.stitch.json`:

```bash
stitch config set project 1234567890
stitch config get project
stitch config list      # resolved values from flags, env, and config files
stitch config unset project
```

| Setting | Flag | Environment variable |
| :-- | :-- | :-- |
| Project | `-p, --project` | `STITCH_PROJECT_ID` |
| Workspace | `-w, --workspace` | `STITCH_WORKSPACE` |
| API base URL | `--base-url` | `STITCH_BASE_URL` |

## Global flags

| Flag | Description |
| :-- | :-- |
| `--format json\|ndjson\|table\|markdown` | Output format. Defaults to `table` in a terminal. |
| `--json [payload]` | Output in JSON format. On dual-mode commands (`create`, `edit`, `get`, `find`, `api`), also accepts a raw JSON input payload. |
| `--schema` | Print the JSON Schema (Draft 2020-12) for the command or resource. |
| `--dry-run` | On mutating commands, validate and preview without calling the backend. |

## Commands

### `generate`

Generate screens or variants with Gemini.

```bash
stitch generate screen --project <project-id> --prompt "Analytics dashboard with revenue chart" --device DESKTOP
```

| Option | Description |
| :-- | :-- |
| `-p, --project` | Target project ID |
| `--new-project [title]` | Create a new project instead |
| `--prompt` | Art-direction prompt |
| `-d, --device` | `DESKTOP` or `MOBILE` |
| `--model` | `GEMINI_3_8_FLASH` or `GEMINI_3_5_FLASH_LITE` |
| `--title` | Screen title, best effort (names the project with `--new-project`) |
| `--screen` | Source screen (variants) |
| `--count` | Number of variants, 1–5 |
| `--creative-range` | `REFINE`, `EXPLORE`, or `REIMAGINE` |
| `--aspects` | Comma-separated: `LAYOUT`, `COLOR_SCHEME`, `IMAGES`, `TEXT_FONT`, `TEXT_CONTENT` |
| `--dry-run` | Preview without generating |

### `edit`

Change an existing resource. For screens, this re-generates with a prompt.

```bash
stitch edit screen <screen-id> --project <project-id> --prompt "Add a dark mode toggle to the header"
```

| Option | Description |
| :-- | :-- |
| `--prompt` | Art-direction prompt |
| `--device` | `DESKTOP` or `MOBILE` |
| `--model` | Generation model |
| `--design-system` | Design system ID to apply |
| `--json '{...}'` | Raw patch payload (e.g. for `design-system`) |
| `--dry-run` | Preview without changing anything |

Resources: `screen`, `design-system`.

### `capture`

Save a page as a single self-contained HTML file, ready to upload as a screen.

```bash
stitch capture http://localhost:3000/library
```

| Option | Description |
| :-- | :-- |
| `-o, --output` | Output path. Default `.stitch/captures/<route>.html`; `-` for stdout |
| `--tab [id]` | Capture an open Chrome DevTools tab as-is, without reloading |
| `--auth` | Playwright `storageState` JSON for sign-in-gated routes |
| `--origin` | When capturing a local file, the origin serving its root-relative assets |
| `--allow-redirect` | Save even if the page redirected to a different route |

Subcommands: `routes` (list routes found in the codebase), and `browser`, `port`, `file` for explicit capture modes.

### `upload`

Upload a screen or design file to a project.

```bash
stitch upload screen .stitch/checkout.html --route /checkout --title Checkout
stitch upload design DESIGN.md --project <project-id>
```

Subcommands: `screen` (HTML or image), `design` (DESIGN.md).

### `serve`

Run a local preview server for a project's screens.

```bash
stitch serve -p <project-id>
```

| Option | Description |
| :-- | :-- |
| `-p, --project` | Project to preview |
| `--port` | Port, default `3000` |
| `--dry-run` | Check configuration and exit |

### `find`

List resources.

```bash
stitch find projects --limit 10
```

| Option | Description |
| :-- | :-- |
| `--limit` | Maximum results |
| `--page-size`, `--page-token` | Pagination |
| `--filter` | Filter expression |

Resources: `project`, `screen`, `design-system`.

### `get`

Fetch one resource by ID.

```bash
stitch get project <project-id> --json
stitch get screen <screen-id> --project <project-id> --json
```

### `create`

Create a resource from flags or a JSON payload.

```bash
stitch create project --title "Customer Dashboard Redesign"
stitch create project --json '{"title":"Customer Dashboard Redesign"}'
```

Options: `--title`, `--json`, `--dry-run`.

### `delete`

Delete a resource.

```bash
stitch delete project --id <project-id> --dry-run
```

Options: `--id`, `--dry-run`, `-y, --yes` (skip confirmation).

### `open` and `url`

Open a project or screen on the Stitch canvas, or print its URL.

```bash
stitch open project <project-id>
stitch url screen <screen-id> --project <project-id>
```

`open --url` prints instead of launching a browser (also respects `STITCH_NO_BROWSER`).

### `mcp`

Run Stitch as an MCP server over stdio.

```bash
stitch mcp install   # register with your AI editor
stitch mcp start     # start the server (what the editor runs)
```

### `agent-skills`

Install a `SKILL.md` that teaches coding agents how to use this CLI.

```bash
stitch agent-skills add      # writes to .agents/skills
stitch agent-skills list
stitch agent-skills update   # resync after upgrading the CLI
```

### `api`

Call a Stitch REST endpoint directly.

```bash
stitch api workspaces
stitch api workspaces/<id>/loops --schema
```

Options: `-X, --method` (default `GET`), `--json`, `--schema`, `-y, --yes`.

### `privacy`

Show or accept the Stitch Privacy Notice and Terms of Service: `stitch privacy status | show | accept`.

## Experimental: Loop workspaces

Loop pairs a GitHub repository with a Stitch **workspace**. You give the workspace **loops**, which are standing objectives such as "reduce checkout friction". Stitch reads the codebase against each loop and reports **insights**: specific opportunities tied to a route. For each insight it can propose **solutions**, which are concrete changes.

Loop is off by default. The commands and API may change between releases.

### Workflow

```bash
# 1. Turn Loop on and sign in to Google and GitHub
stitch enable loop
stitch login
stitch github login
stitch github configure          # grant the Stitch GitHub App access to your repositories
stitch github repos              # list repositories you can attach to a workspace

# 2. Create a workspace for a repository and make it this directory's default
stitch create workspace --name Storefront --json '{"repositories":["https://github.com/org/storefront"]}'
stitch find workspaces
stitch config set workspace <workspace-id>

# 3. Add a loop, either from a starter template or written from scratch
stitch create loop --templates
stitch create loop --objective "Reduce checkout friction"

# 4. Generate insights and wait for the run to finish
stitch generate insights --loop <loop-id> --watch --notify

# 5. Review the insights, then generate solutions or dismiss them
stitch find insights --loop <loop-id>
stitch generate solutions --insight <insight-id>
stitch find solutions --loop <loop-id>
stitch dismiss insights <insight-id>
```

`stitch status --flow loop` reports which onboarding step you're on and what to run next.

### Concepts

| Resource | What it is |
| :-- | :-- |
| `workspace` | A repository paired with Stitch. It holds the loops, insights, and context. |
| `loop` | An objective that Stitch keeps working against. |
| `insight` | A route-anchored opportunity found by mining the codebase against a loop. |
| `solution` | A proposed change answering an insight. |
| `context` | External material, such as docs or specs, attached so Stitch can reason beyond the code. |
| `file` | A file uploaded to a workspace. |
| `skill` | Instructions that shape how Stitch agents read the workspace. These are separate from `stitch agent-skills`. |
| `webhook` | An HTTP callback fired on workspace events. |
| `connection` | An integration with an external tool such as GitHub or Slack. |

All of these work with `find`, `get`, `create`, `edit`, and `delete`. Not every resource supports every verb; run `stitch <verb> --schema` to see which ones do.

Loops were previously called priorities; the old `priority`/`priorities` resource names and the `--priority` flag still work.

### Loop commands

**`generate insights`**: mine the codebase against one or more loops.

| Option | Description |
| :-- | :-- |
| `--loop` | Loop ID, or comma-separated IDs |
| `--watch` | Block until the run ends. Exit code `0` means completed, `1` failed, `124` timed out |
| `--notify` | With `--watch`, send a desktop notification when the run ends |
| `--interval` | Polling interval in ms (default `2000`) |
| `--timeout` | Seconds to wait (default `3600`) |
| `--delay` | Delay insight generation execution |

**`generate solutions`**: propose changes for insights. Options: `--insight` (ID or comma-separated IDs), `--replace-existing` (replace unassigned solutions).

**`create loop`**: options `--objective`, `--description`, `--templates` (list starter templates), `-t, --template <id|title|index>`, `-i, --interactive`.

**`dismiss insights <id>`**: hide insights from recommendations. Options: `--concurrency` (default `5`), `--dry-run`.

**`edit workspace <id>`**: options `--add-repo`, `--remove-repo` (URL, `owner/repo`, or ID).

**`upload code [dir]`** uploads a codebase archive (a `.zip` or a directory) to the workspace. **`upload file <path>`** uploads a single file.

**`connect [tool]`**: connect an integration through the provider's OAuth flow.

```bash
stitch connect --list
stitch connect slack --no-browser --timeout 180
```

Options: `-l, --list`, `-s, --search`, `--connected`, `--all`, `--no-browser`, `--timeout` (default `120`).

**`github`**: manage the GitHub connection. Subcommands: `login`, `configure`, `repos`, `status`.

**`api <path>`**: call workspace endpoints directly, for example `stitch api workspaces/<id>/loops`.

Turn Loop off with `stitch disable loop`.

## Library

The package exports one module for configuring codebase ingestion:

```ts
import { defineIngest } from '@google/stitch/ingest';
```

## Known limitations

- Some Canvas operations require `STITCH_API_KEY` even when signed in with OAuth.
- Loop is experimental. Its resources and flags may change without a major version bump.

## License

Apache-2.0
