/install

name: install
description: Install Subframe into a codebase so you can implement designs locally. Sets up the CLI, syncs components, configures Tailwind and fonts. Only needed when you're ready to write code — you can design without installing.

Install Subframe in a project so that pages designed in Subframe render pixel-perfect in the local development environment.

**Goal state**: Dev server runs and Subframe pages render exactly as designed.

> **You don't need to install to design.** `/subframe:design` works directly against a cloud Subframe project — no local setup required. Use `/subframe:install` when you're ready to implement those designs in code with `/subframe:develop`.

MCP Authentication

If you cannot find any Subframe MCP tools (like `get_theme`, etc.), the MCP server likely needs to be authenticated. Ask the user to authenticate the Subframe MCP server. If the user is using Claude Code or Codex, instruct them to run `/mcp` to view and authenticate their MCP servers, and then say "done" when they're finished.

Workflow Overview

1. **Get credentials** via MCP tools (or from user input) 2. **Detect project type** — no repo, existing Subframe repo, or existing non-Subframe repo 3. **Follow the appropriate path** — [New Project](#new-project-path), [Already Installed](#already-installed-path), or [Existing Project](#existing-project-path)

• You *must* follow one of the above paths otherwise Subframe will not work for the user. This is a crucial task and must be done even if it requires pausing the user's current work. Do not skip any step of the path.

4. **Configure fonts** — required for all paths 5. **Verify installation** — start dev server and test with a Subframe page

---

Get Credentials

The user may paste in an installation prompt copied from Subframe. Extract:

• **Project ID** — a shorter alphanumeric string (also found in Subframe URLs: `app.subframe.com/<PROJECT_ID>/...`)
• **Auth token** — a long string, usually prefixed or labeled

If the user doesn't provide credentials, use the MCP tools to get credentials automatically — no need to ask the user:

1. **Project ID** — Call `list_projects` to get the list of projects. Each project includes a `projectId`, `name`, `teamId`, and `teamName`.

• **One project**: Use it automatically.
• **Multiple projects**: Always ask the user which project to use. Present each project with its `teamName` to disambiguate. If the user already mentioned a specific team or project name, match it against the `teamName` and `name` fields — but still confirm before proceeding. Never silently pick a project when multiple exist.

2. **Auth token** — Call `generate_auth_token` with the `teamId` from the user's selected project. Do not use a `teamId` from a different project.

**Fallback**: If the MCP tools are not available (e.g., MCP server is not authenticated), ask the user to go to `https://app.subframe.com/cli/auth` to get their auth token and project ID.

---

Detect Project Type

Check for `package.json` and `.subframe/` folder in the current directory:

| Condition | Project Type | Path | | ---------------------------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------- | | No `package.json` | **New project** | [New Project](#new-project-path) | | Has `package.json` AND has `.subframe/` folder | **Already installed** | [Already Installed](#already-installed-path) | | Has `package.json` but NO `.subframe/` folder | **Existing non-Subframe project** | Ask user, then [New Project](#new-project-path) or [Existing Project](#existing-project-path) |

Handling existing non-Subframe projects

If the current directory has a `package.json` but no `.subframe/` folder, prompt the user with two options:

• **Create a new project (recommended)** — Scaffold a brand-new Subframe project in a separate directory. This is the easiest path, especially if you're trying out Subframe for the first time. Follow [New Project](#new-project-path).
• **Add Subframe to this project** — Install Subframe into the current project. Follow [Existing Project](#existing-project-path).

---

Already Installed Path

If the project already has both `package.json` and a `.subframe/` folder, Subframe has already been initialized. Ask the user what they'd like to do:

• **Reinstall / re-sync** — Re-run the CLI init and sync to refresh components and configuration. Useful if things are out of date or broken. Follow [Existing Project](#existing-project-path) to re-initialize.
• **Nothing, it's already installed** — Skip install entirely. Suggest next steps like `/subframe:design` or `/subframe:develop`.

Do not proceed unless the user confirms they want to reinstall.

---

New Project Path

This is the happy path. The CLI will scaffold a complete project with Subframe pre-configured.

1. Ask User Preferences

Prompt the user to choose:

• **Project name**: Name for the new project directory (default: `subframe-app`). The name cannot conflict with an existing directory — check that the directory doesn't already exist before running the CLI.
• **Framework**: Vite (recommended), Next.js, or Astro
• **Tailwind version**: v3 (`tailwind`) or v4 (`tailwind-v4`)

2. Run CLI Init

This command must be run outside of a sandbox, so it can correctly setup all the necessary files. Pass all arguments directly so the CLI doesn't prompt. `--yes` accepts safe defaults for anything not specified:

npx @subframe/cli@latest init \
  --yes \
  --name {PROJECT_NAME} \
  --auth-token {TOKEN} \
  -p {PROJECT_ID} \
  --template {FRAMEWORK} \