@google/stitch

中文文档
0.12.2发布于 2026/11/10Apache-2.0TypeScriptES Module近 30 天下载 5841

Agent-first CLI and MCP server for Google Stitch

原始使用文档
文档目录30 节
  1. Bring an existing page into Stitch and redesign it
  2. Explore variants of a screen
  3. Preview a project's screens locally
  4. Use it from a coding agent
  5. Install
  6. Authentication
  7. Configuration
  8. Global flags
  9. Commands
  10. generate
  11. edit
  12. capture
  13. upload
  14. serve
  15. find
  16. get
  17. create
  18. delete
  19. open and url
  20. mcp
  21. agent-skills
  22. api
  23. privacy
  24. Experimental: Loop workspaces
  25. Workflow
  26. Concepts
  27. Loop commands
  28. Library
  29. Known limitations
  30. License

@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.

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:

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

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

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:

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:

stitch mcp install

Install

npm install -g @google/stitch

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

Authentication

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:

export STITCH_API_KEY=your-api-key
CredentialFlagEnvironment variable
API key--api-keySTITCH_API_KEY
OAuth access token--access-tokenSTITCH_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:

stitch config set project 1234567890
stitch config get project
stitch config list      # resolved values from flags, env, and config files
stitch config unset project
SettingFlagEnvironment variable
Project-p, --projectSTITCH_PROJECT_ID
Workspace-w, --workspaceSTITCH_WORKSPACE
API base URL--base-urlSTITCH_BASE_URL

Global flags

FlagDescription
--format json|ndjson|table|markdownOutput 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.
--schemaPrint the JSON Schema (Draft 2020-12) for the command or resource.
--dry-runOn mutating commands, validate and preview without calling the backend.

Commands

generate

Generate screens or variants with Gemini.

stitch generate screen --project <project-id> --prompt "Analytics dashboard with revenue chart" --device DESKTOP
OptionDescription
-p, --projectTarget project ID
--new-project [title]Create a new project instead
--promptArt-direction prompt
-d, --deviceDESKTOP or MOBILE
--modelGEMINI_3_8_FLASH or GEMINI_3_5_FLASH_LITE
--titleScreen title, best effort (names the project with --new-project)
--screenSource screen (variants)
--countNumber of variants, 1–5
--creative-rangeREFINE, EXPLORE, or REIMAGINE
--aspectsComma-separated: LAYOUT, COLOR_SCHEME, IMAGES, TEXT_FONT, TEXT_CONTENT
--dry-runPreview without generating

edit

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

stitch edit screen <screen-id> --project <project-id> --prompt "Add a dark mode toggle to the header"
OptionDescription
--promptArt-direction prompt
--deviceDESKTOP or MOBILE
--modelGeneration model
--design-systemDesign system ID to apply
--json '{...}'Raw patch payload (e.g. for design-system)
--dry-runPreview without changing anything

Resources: screen, design-system.

capture

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

stitch capture http://localhost:3000/library
OptionDescription
-o, --outputOutput path. Default .stitch/captures/<route>.html; - for stdout
--tab [id]Capture an open Chrome DevTools tab as-is, without reloading
--authPlaywright storageState JSON for sign-in-gated routes
--originWhen capturing a local file, the origin serving its root-relative assets
--allow-redirectSave 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.

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.

stitch serve -p <project-id>
OptionDescription
-p, --projectProject to preview
--portPort, default 3000
--dry-runCheck configuration and exit

find

List resources.

stitch find projects --limit 10
OptionDescription
--limitMaximum results
--page-size, --page-tokenPagination
--filterFilter expression

Resources: project, screen, design-system.

get

Fetch one resource by ID.

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.

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

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

delete

Delete a resource.

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.

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.

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.

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.

stitch api workspaces
stitch api workspaces/<id>/priorities --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 priorities, which are standing objectives such as "reduce checkout friction". Stitch reads the codebase against each priority 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

# 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 priority, either from a starter template or written from scratch
stitch create priority --templates
stitch create priority --objective "Reduce checkout friction"

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

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

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

Concepts

ResourceWhat it is
workspaceA repository paired with Stitch. It holds the priorities, insights, and context.
priorityAn objective that Stitch keeps working against.
insightA route-anchored opportunity found by mining the codebase against a priority.
solutionA proposed change answering an insight.
contextExternal material, such as docs or specs, attached so Stitch can reason beyond the code.
fileA file uploaded to a workspace.
skillInstructions that shape how Stitch agents read the workspace. These are separate from stitch agent-skills.
webhookAn HTTP callback fired on workspace events.
connectionAn 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.

Loop commands

generate insights: mine the codebase against one or more priorities.

OptionDescription
--priorityPriority ID, or comma-separated IDs
--watchBlock until the run ends. Exit code 0 means completed, 1 failed, 124 timed out
--notifyWith --watch, send a desktop notification when the run ends
--intervalPolling interval in ms (default 2000)
--timeoutSeconds to wait (default 3600)
--delayDelay insight generation execution

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

create priority: 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.

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>/priorities.

Turn Loop off with stitch disable loop.

Library

The package exports one module for configuring codebase ingestion:

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

版本与发布记录

@google/stitch 共发布 6 个版本,首次发布于 2026/10/01;过去 12 个月发布了 6 个版本。

版本发布日期距今
0.12.2latest2026/11/107 天前
0.12.1next2026/10/3018 天前
0.12.02026/10/2226 天前
0.12.0-rc.22026/10/2226 天前
0.11.12026/10/091 个月前
0.11.02026/10/011 个月前

关于 @google/stitch 的常见问题

@google/stitch 是什么?

Agent-first CLI and MCP server for Google Stitch

如何安装 @google/stitch?

在项目目录运行 npm install @google/stitch,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 stitch、stitch-mcp,可以用 npx stitch 直接运行。

@google/stitch 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@google/stitch 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@google/stitch 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=20。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@google/stitch 可以商用吗?

@google/stitch 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@google/stitch 的下载量有多少?

根据 npm 官方下载统计,@google/stitch 在 2026/10/17 – 2026/11/15 这 30 天内被下载 5,841 次,日均约 195 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@google/stitch 还在维护吗?

最新版本 0.12.2 发布于 2026/11/10(7 天前);至今共发布 6 个版本,其中过去 12 个月发布了 6 个;首次发布于 2026/10/01。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。