/plugin commands, showing the marketplace added and the confirmation that the flutterflow plugin is installed and enabled.
+.default})
+
+2. Under **Customize**, select **Plugins**.
+
+ .default})
+
+3. Select **Add**, then **Add marketplace**.
+
+ .default})
+
+4. In **URL**, enter `https://github.com/FlutterFlow/flutterflow-claude`, then select **Use "https://github.com/FlutterFlow/flutterflow-claude"**.
+
+ .default})
+
+5. In the plugin directory, select **Code**. Under the `flutterflow` marketplace, find the **FlutterFlow** plugin and select the **+** button on its card.
+
+ .default})
+
+6. Wait for the **FlutterFlow is installed and ready to use.** confirmation.
+
+ .default})
+
+7. Close Settings, open the **Code** tab, and start a new session. Choose **Local** as the environment, select the folder where you want to work, and describe the FlutterFlow outcome you want in the prompt box. The folder can be an existing FlutterFlow AI workspace or the parent folder where a new one should be created.
+
+:::note[Desktop app specifics]
+
+- Plugins are available in the desktop app's **Local** and **SSH** sessions, not in cloud or WSL sessions.
+- The desktop app reads your `PATH` when it launches. If Dart or the FlutterFlow CLI was installed while the app was open and a session can't find them, quit and reopen the app.
+:::
+
+## Set Up Your API Key
+
+The plugin authenticates with your FlutterFlow API key, and key setup works the same on both surfaces. Until a key is configured, the plugin prints a reminder when a session starts:
+
+```
+[flutterflow] No FlutterFlow API key configured.
+[flutterflow] 1) Copy an API key from https://app.flutterflow.io/account
+[flutterflow] 2) Come back and tell Claude: "I copied my FlutterFlow API key"
+```
+
+**Never paste the API key into the chat**, because conversations are logged and retained. Instead, hand the key over through your clipboard:
+
+1. Open your [FlutterFlow account page](https://app.flutterflow.io/account) and copy your API key. If you don't have one yet, see [generating an API token](../../../accounts-billing/account-management.md#how-do-i-generate-an-api-token).
+2. Come back to Claude Code and say: **"I copied my FlutterFlow API key"**.
+
+Claude runs a script bundled with the plugin that reads the clipboard once, validates the key, stores it in `~/.config/flutterflow/claude-env.sh` with owner-only permissions, and clears the clipboard. The key itself never enters the conversation. If validation fails (for example, you copied something else in the meantime), Claude asks you to copy the key again and retry.
+
+:::warning[Clipboard history managers]
+Tools like Raycast, Alfred, Windows clipboard history (Win + V), and Apple's Universal Clipboard keep their own copy of everything you copy, even after the system clipboard is cleared. If you use one, purge the key from its history after setup.
+:::
+
+Working over **SSH or in a headless environment**? The clipboard hand-off isn't available there, so Claude offers a one-line terminal command that prompts for the key with hidden input. Alternatively, run `flutterflow ai` in your own terminal and let its setup wizard prompt for the key.
+
+:::note
+Avoid entering the key through `/plugin configure` for now, because its input dialog has known issues in current Claude Code versions ([#73530](https://github.com/anthropics/claude-code/issues/73530), [#62442](https://github.com/anthropics/claude-code/issues/62442)). The clipboard hand-off above is the recommended path.
+:::
+
+## Build with FlutterFlow
+
+Start a new Claude Code session in your working folder: `claude` in the terminal, or a **Local** session in the desktop app. On the first session after setup, the plugin installs the FlutterFlow CLI automatically and prints a notice while it works:
+
+```
+[flutterflow] Installing the FlutterFlow CLIβ¦
+```
+
+After that, describe what you want to build. The build skill triggers on FlutterFlow tasks, or you can invoke it explicitly with `/flutterflow:build`:
+
+```
+> Create a FlutterFlow app for tracking daily habits
+> Add a profile page with an avatar, display name, and a settings list
+> Change the primary color to teal and update the home page title
+```
+
+Under the hood, the skill follows a disciplined workflow:
+
+1. **Workspace.** Ensures you have a FlutterFlow AI workspace (`flutterflow ai init`), bound either to a new app or to an existing project. If you're editing an existing project but don't have its ID handy, Claude lists your account's projects and asks which one to use.
+2. **Orient.** Reads the project before changing it, using commands like `status`, `inspect`, `resources`, and `search`.
+3. **Author β validate β apply.** Writes changes as declarative Dart files, checks them with `flutterflow ai validate` first, and only then applies them with `flutterflow ai run`.
+
+Each applied change lands as a commit in your FlutterFlow project. Open the project in the visual builder to verify the result, then keep refining, either visually or with follow-up prompts.
+
+:::note[MCP server approval]
+Workspaces created by `flutterflow ai init` also register the FlutterFlow AI MCP server with Claude Code via a project-scoped `.mcp.json`. If Claude Code asks to approve a new MCP server named `flutterflow_ai` when you open a session in the workspace, approve it; the build skill and the MCP server drive the same project state. See [Build with AI Agents](./flutterflow-mcp.md#launch-your-agent) for details.
+:::
+
+:::tip[Everything works from the terminal too]
+The plugin drives the standard `flutterflow ai` CLI, so the same commands work in any terminal, for example `flutterflow ai init my-app`, `flutterflow ai status`, `flutterflow ai validate`, and `flutterflow ai run`. See the [MCP tools reference](./flutterflow-mcp.md#mcp-tools) for the full command list.
+:::
+
+## Managing Your API Key
+
+**Rotate the key.** Create a new API key on your [account page](https://app.flutterflow.io/account), copy it, and tell Claude *"I copied my FlutterFlow API key"* again. The stored key is replaced and used for subsequent commands.
+
+**Remove the key entirely.** Delete the stored key file and clear the CLI's cached credentials:
+
+```bash
+rm -f ~/.config/flutterflow/claude-env.sh
+flutterflow ai logout --all
+```
+
+**If a key ever appears in the chat**, treat it as compromised: delete it on your [account page](https://app.flutterflow.io/account) and create a new one.
+
+## Update the Plugin
+
+Plugin installs track the latest version of the FlutterFlow marketplace. To update, run this from a terminal (or `/plugin marketplace update flutterflow` inside a terminal session), then start a new session. The update applies to the terminal and the desktop app alike:
+
+```bash
+claude plugin marketplace update flutterflow
+```
+
+## Troubleshooting
+
++The CLI installs to Dart's pub-cache, which may not be on your PATH. Add it to your shell profile and restart the session: + +```bash +echo 'export PATH="$HOME/.pub-cache/bin:$PATH"' >> ~/.zshrc +``` +
++The FlutterFlow CLI requires the Dart SDK, which ships with Flutter. Install Flutter (recommended) or Dart on its own, then start a new Claude Code session. The plugin retries the install automatically. +
+
+The desktop app reads your PATH once, when it launches. If Dart or the FlutterFlow CLI was installed while the app was open, quit and reopen the desktop app. On macOS, make sure your shell profile (for example ~/.zshrc) exports the path; on Windows, add it to your user PATH.
+
+The plugin's automatic setup runs as a bash script, so it needs a bash on your PATH. Install Git Bash or WSL. Alternatively, install the CLI manually with dart pub global activate flutterflow_cli and let flutterflow ai prompt for your API key the first time you run it.
+
+The key is invalid or was revoked. Copy a fresh key from your account page and tell Claude "I copied my FlutterFlow API key". Don't paste the key into the chat. +
+