Skip to main content
The Seam Wizard prepares an existing project for Seam. It detects your language and package tools, connects a Seam workspace, installs the SDK and Seam developer tools, and can optionally have Seam AI write a first integration for you.
Run the wizard from your project root. It reads the project there and makes changes there.

​
Quick start

You need Node.js 22.12 or newer and npm 10 or newer. These are the runtime requirements published with the wizard package. The wizard is an interactive terminal application. Run it in a terminal attached to your project; do not pipe it from a CI job or other non-interactive process. From an existing project directory, run:
Follow the prompts to choose a workspace, language, and integration path. When the wizard finishes, inspect the changes before you commit them:
The wizard can be run again later. It detects an existing setup and lets you continue from the current project state.
Already use the installed Seam CLI? Run seam wizard. The Seam CLI has additional installation options. The Homebrew Core package (brew install seam) includes the CLI but does not include the wizard; use npx seam@latest wizard for the wizard.

​
What the wizard does

The wizard takes you through these steps:
  1. Detects JavaScript/TypeScript, Python, Ruby, or PHP and recognizes the package manager or installer already in use.
  2. Connects the project to a Seam workspace.
  3. Installs the seam SDK using your project’s tool: npm, pnpm, yarn, or bun for JavaScript; pip, Poetry, or uv for Python; Bundler or RubyGems for Ruby; and Composer for PHP.
  4. Installs Seam integration skills and registers the authenticated Seam MCP for your coding agent when possible.
  5. Optionally analyzes the project, recommends Customer Portal or Full API, and asks Seam AI to write the integration as local file changes.
The SDK and developer tooling setup is useful even if you choose to continue coding yourself after the wizard finishes.

​
Connect or reuse a Seam key

The wizard never asks for your Seam password. If it finds SEAM_API_KEY in the process environment or in a project dotenv file, it verifies and reuses that key. It checks common files such as .env.local and .env. If no key is available, choose the browser connection flow. Seam Console creates a key and returns it to the local wizard through a localhost callback. You can also paste an existing key when prompted. The verified key is saved as SEAM_API_KEY in the project’s .env file. The wizard creates or updates .env.example with an empty SEAM_API_KEY entry and adds .env to .gitignore when the project is a Git repository. Keep .env out of source control. Your app uses this key for server-side Seam SDK requests.

​
Supported languages

The wizard offers JavaScript / TypeScript, Python, Ruby, and PHP. It detects the project from files such as package.json, pyproject.toml, requirements.txt, Gemfile, or composer.json, then uses the matching installer. You can select a different language when detection is ambiguous. The SDK install updates the project’s dependency manifest and lockfile when the selected package manager uses one. Typical commands are:

​
Choose your integration

After setup, you can stop and use the SDK and docs yourself, or choose one of the guided paths:
  • Customer Portal: use Seam-hosted UI and a small integration surface for syncing customer or reservation data.
  • Full API: build your own UI and control the complete flow, including Connect Webviews, spaces, user identities, and Access Grants.
The recommendation uses project signals and, when available, onboarding answers from Seam Console. You choose the final path before any integration-writing step begins.

​
What changes in your project

The setup portion may make these changes in the project root:
  • adds seam to the dependency manifest and updates its lockfile;
  • writes or updates SEAM_API_KEY in .env;
  • installs Seam skills under .claude/skills;
  • registers the authenticated Seam MCP in project-scoped .mcp.json for Claude Code, or prints a configuration snippet and locations for Cursor, Codex, and OpenCode.
When the guided integration runs, the Seam CLI also records the wizard plan and result in per-user local state (wizard.json under the CLI log directory). This state is not a project file. The optional integration agent writes code and configuration into your project. Review the resulting git diff and run your normal tests before accepting those changes.

​
Remote inference and local files

The wizard’s analysis and embedded integration agent use Seam-hosted inference. Analysis sends project signals such as the detected framework, dependency names, package metadata, and a README excerpt to Seam so it can recommend an integration. If you choose to generate code, the agent can read relevant project files through its tools and sends the resulting context through that hosted session while writing changes into the project directory you started from. Your API key remains in the local .env file and is not included in the project analysis payload. The embedded agent uses a separate scoped wizard session. Separately, if the wizard registers the authenticated Seam MCP for your own coding assistant, that assistant performs its own OAuth sign-in and permission flow; this is distinct from the wizard’s hosted integration session. Generated files are written locally, so review them before committing or sharing them.

​
Troubleshooting

​
npx cannot find the wizard

Use the canonical command exactly as shown:
Check that npm is 10 or newer and Node.js is 22.12 or newer. If you already have the Seam CLI installed, seam wizard uses the same wizard entry point.

​
The wizard cannot install the SDK

Make sure the project’s package manager or installer is installed and that you ran the command from the project root. The wizard prints the exact install command when an install fails, so you can run it yourself and resume with npx seam@latest wizard.

​
Browser authentication does not return to the terminal

Keep the original terminal open while the browser flow completes. If the localhost callback is blocked, choose the paste-a-key option and provide a key created in Seam Console. A key that starts with seam_ must be copied in full.

​
The coding agent is not connected

For Claude Code, confirm that the project has .mcp.json with the authenticated MCP URL, then restart or reload the agent. If Claude Code is unavailable, copy the snippet the wizard prints into the MCP configuration for your agent. The wizard also prints the setup commands when it cannot run the Claude CLI.

​
I only want setup

Choose Continue on my own after the SDK and developer tooling are installed. You can run the wizard again whenever you want Seam AI to plan or write the integration.

​
Next steps