Scaffold a Chat SDK bot app with a single command.
create-chat-sdk creates a minimal Next.js app for Chat SDK bots.
The CLI will generate your Chat configuration, webhook route, .env.example file, dependencies, and optional Web adapter route from the adapter catalog.
create-chat-sdk automatically detects when it is being run by Cursor, Claude Code, or another coding agent. In agent environments, pass at least one platform adapter with --adapter; the state adapter defaults to memory. The CLI runs non-interactively and uses my-bot when no project name is provided. Pass --interactive to force prompts.
Pass platform and state adapters with --adapter:
npm create chat-sdk@latest -- my-bot --adapter slack redis -yWith npm, the -- separator is required because npm consumes flags before it (-y is npm's own --yes) instead of forwarding them to the CLI. pnpm create and yarn create forward flags without it.
The interactive prompt lists official adapters by default. Pass --vendor to list only vendor-official adapters instead. Automation and coding agents can install any CLI-supported official or vendor adapter directly with --adapter.
Adapters that require a long-running process, including Matrix and Lark, cannot run on the webhook-only serverless runtime and are not available through the CLI. Add them to an existing project manually instead.
View available adapter slugs
Examples:
npm create chat-sdk@latest -- slack-bot --adapter slack memory -y --skip-install
npm create chat-sdk@latest -- gchat-bot --adapter gchat redis -y --pm pnpm
npm create chat-sdk@latest -- email-bot --adapter resend postgres -y --no-git
npm create chat-sdk@latest -- my-bot --adapter slack memory -y --forceThe scaffolded app is webhook-only. It does not include pages, layouts, or a client UI.
src/
lib/bot.ts Bot configuration and handlers
app/api/webhooks/[platform]/route.ts Dynamic platform webhook route
app/api/chat/route.ts Web adapter route, only when selected
app/api/discord/gateway/route.ts Discord Gateway listener, only when selected
.env.example Required environment variables
next.config.ts Next.js server config
vercel.json Cron schedules, only when needed
.chat-sdk.json Generated file ownership for safe reruns
package.json Adapter dependenciesWebhook endpoints use the selected adapter slug:
/api/webhooks/slack
/api/webhooks/gchat
/api/webhooks/discordWhen the Web adapter is selected, the CLI also creates /api/chat for browser chat requests and a small getUser auth stub. Replace the stub with your app's real authentication logic so each web conversation can be associated with the correct user.
When the Discord adapter is selected, the CLI also creates a Gateway listener at /api/discord/gateway and a vercel.json cron that calls it. Discord delivers slash commands and button clicks to the webhook route, but regular messages and reactions only arrive over the Gateway WebSocket, so the cron keeps that connection alive and forwards events to /api/webhooks/discord. Set a CRON_SECRET environment variable to authenticate the cron requests. The generated serverless Gateway cron requires Vercel Pro or Enterprise because it runs every nine minutes.
| Option | Description |
|---|---|
[name] | Name of the project. |
-d, --description <text> | Project description. |
--adapter <values...> | Platform or state adapters to include. |
--vendor | List only vendor-official adapters in the interactive prompt. |
--pm <manager> | Package manager to use: npm, yarn, pnpm, or bun. |
-y, --yes | Skip prompts and accept defaults. |
--interactive | Always prompt, even when a coding agent environment is detected. |
-f, --force | Overwrite generated files in an existing directory. |
-s, --skip-install | Skip dependency installation. |
--no-git | Skip git repository initialization. |
-q, --quiet | Suppress non-essential output. |
Color output follows the NO_COLOR standard — set NO_COLOR=1 to disable colors.
Most bot behavior lives in src/lib/bot.ts. Start there when you want to:
- Add or change handlers like
onNewMention,onSubscribedMessage,onNewMessage, reactions, actions, or slash commands. - Adjust adapter configuration, for example passing explicit credentials or platform-specific options instead of relying only on environment variables.
- If you selected the memory state adapter, switch to Redis, ioredis, or PostgreSQL before deploying to production.
The generated file includes starter handlers for mentions and subscribed thread replies.
After scaffolding:
cd my-bot
cp .env.example .env.local
npm run devFill in the generated environment variables, expose your local server, and configure each selected platform to call its /api/webhooks/{adapter} endpoint.
See guides, templates, and examples on the resources page.