Export a Grok Bot to a BDK project

bdk init --from-grokbot turns a Grok Bot recipe into a project you can review, run locally, and keep in source control. It carries over the bot's profile, selected skills and routines, memory, and connectors where BDK has a matching project surface.

Preview the export

Start with --dry-run. The command resolves the same defaults as a real export and shows every planned file, warning, secret name, and follow-up without creating the target directory or installing packages.

bdk init ./launch-desk \  --from-grokbot ./launch-desk.recipe.json \  --dry-run

Selected lines from the example recipe's non-interactive preview look like this:

Dry run: "Launch Desk" → ./launch-desk (nothing written)  bot/agent.ts                                   profile  bot/channels/slack.ts                          routines/launch-questions, routines/blocker-watch, routines/ship-it  bot/instructions.md                            profile, gettingStarted, routines/launch-questions, routines/blocker-watch, routines/ship-it, memory  bot/mcp-connections/linear.ts                  plugins/linear  bot/schedules/morning-launch-brief.md          routines/morning-launch-brief  bot/skills/release-checklist/SKILL.md          skills/release-checklist  SECRETS.md                                     answers  ...Defaulted without asking:  - name  - description  - model  ...Not carried over:  - profile.avatar: BDK agents have no avatar; kept in grokbot-export.json for the Slack app icon.Secrets to set (names only; see SECRETS.md):  - LAUNCH_DESK_SLACK_APP_TOKEN  - LAUNCH_DESK_SLACK_BOT_TOKEN

Each file row names the recipe parts that produced it. The remaining sections list defaults, answers the recipe ignored, excluded items, unmapped behavior, routine placeholders, fresh connector sign-ins, warnings, and setup steps.

Add --json when a script needs the preview:

bdk init ./launch-desk \  --from-grokbot ./launch-desk.recipe.json \  --dry-run \  --json

The core JSON shape is:

{  "ok": true,  "dryRun": true,  "directory": "/work/launch-desk",  "preview": {    "files": [],    "defaulted": [],    "ignored": [],    "excluded": [],    "unmapped": [],    "fillIns": [],    "secrets": { "names": [], "reauth": [] },    "warnings": [],    "setupSteps": []  }}

See bdk init for the complete preview fields and flag behavior.

Choose an answers file or the terminal interview

Run the command in a terminal when you want to review each choice once. Press Enter to accept a default.

bdk init ./launch-desk \  --from-grokbot ./launch-desk.recipe.json

Use --answers for a repeatable export or a non-interactive environment. This minimal file validates against the published schema and accepts every recipe default:

{  "$schema": "./node_modules/@cursor/bdk/schemas/grokbot-answers.schema.json",  "version": 1}

Save it as grokbot-answers.json, then run:

bdk init ./launch-desk \  --from-grokbot ./launch-desk.recipe.json \  --answers ./grokbot-answers.json

The $schema property is an optional editor hint. Add only the choices you want to override; any answer present in the file is not asked again. A positional directory such as ./launch-desk overrides location in the answers file.

When stdin or stdout is not a TTY, the command never prompts. --json also uses this non-interactive path. Missing fields take their defaults and appear under Defaulted without asking or preview.defaulted. If a required conditional answer has no default, such as the time for a scheduled decision, the command stops and names the field to add to the answers file.

Write and check the project

Remove --dry-run after the preview matches your intent. The command writes the project, installs its npm dependencies, and prints the next commands. Export into a fresh directory; a project previously created with bdk init --template is rejected.

bdk init ./launch-desk \  --from-grokbot ./launch-desk.recipe.json \  --answers ./grokbot-answers.jsoncd ./launch-deskbdk validatebdk dev

Open the playground from bdk dev and try the routines you plan to keep before connecting live channels.

Review what maps where

Grok Bot recipe part	BDK project result
Profile or persona	The name and description become `bot/agent.ts` and the opening of `bot/instructions.md`.
Skills	Each selected skill becomes `bot/skills/<slug>/SKILL.md`. An enabled, valid skill schedule also becomes `bot/schedules/<slug>.md` when the schedule channel is on.
Getting-started skill	`bot/instructions.md` tells the agent to use this skill for a new conversation.
Cron routines	A selected routine with a valid, enabled cron trigger becomes `bot/schedules/<slug>.md` when the schedule channel is on.
Slack routines	When the Slack channel is on, the routine text becomes a section in `bot/instructions.md`; mentions, channel watches, keywords, and reactions are wired in `bot/channels/slack.ts`. Missing trigger values remain as warnings or TODOs.
GitHub or webhook routines	When the corresponding channel is on, the preview adds a setup step to wire the trigger. A routine with no other wired trigger also becomes an on-request skill.
Other routines	A routine without a wired trigger becomes an on-request skill. The preview explains which trigger still needs work.
Memory	The default is `bot/skills/knowledge/SKILL.md`. Choose `memory: "kv"` for `bot/lib/memory-seed.json`, or `memory: "drop"` to leave it out.
Plugins and connectors	Each selected plugin becomes `bot/mcp-connections/<slug>.ts` using Cursor-account auth, OAuth, or a named bearer-token secret.
Routine placeholders	Values under `fillIns.<routine-slug>` replace placeholders such as `{slack_channel}`. Unfilled placeholders remain visible and produce warnings.
Export decisions	Resolved answers and recipe metadata are recorded in `grokbot-export.json`.

The generated project also includes the standard package, TypeScript, eval, memory-hook, and ignore files needed to run it.

Resolve what does not map

The preview separates choices you made from behavior the converter could not carry over:

Preview result	What it means	What to do
Left out	An answer excluded a skill, routine, plugin, or memory.	Change the matching `include` or `exclude` answer, or change `memory` from `"drop"`, then rerun; otherwise leave the item behind.
`BDK agents have no avatar`	The profile avatar is not an agent setting. Its metadata remains in `grokbot-export.json`.	Set an icon separately if the destination needs one.
`Unknown recipe field; ignored.`	The recipe contains a field this BDK version does not map.	Inspect the field and add its behavior to the generated project when needed.
`Paused schedule ...`	A paused cron trigger does not produce a schedule file.	Leave it paused, or add a schedule under `bot/schedules/`.
`trigger dropped: the ... channel is off.`	The answers disabled the channel used by a trigger.	Enable the channel in the answers or add the trigger manually after export.
`trigger has no BDK channel.`	The trigger type has no direct BDK channel mapping.	Add a supported channel or custom wake; use the generated on-request skill when one is present.
`is not a five-field cron expression.`	The source cron cannot become a BDK schedule.	Correct the expression and add the schedule before enabling it.
`placeholders ... are unfilled`	A routine still contains values such as `{slack_channel}`.	Set `fillIns.<routine-slug>` in the answers or edit the generated text.
`BDK has no built-in KV seed`	`memory: "kv"` writes data but does not load it into hosted KV.	Add your own `ctx.host.kv` seeding code, or use `memory: "skill"`.

Treat setup steps and warnings as the checklist for restoring the source behavior. A generated project is ready for review, not automatically ready for live traffic.

Set secrets and reconnect OAuth

The export carries secret names only, never values. SECRETS.md lists each name, where it is read, and every connector that needs a fresh sign-in.

Set local values in the environment where you run bdk dev. For a hosted deployment, let bdk prompt for each value:

bdk secrets set launch-desk LINEAR_API_KEY

OAuth tokens do not move with the recipe. Sign in to each OAuth connector again:

bdk mcp oauth notion

Add --store when the sign-in is for a hosted deployment.

Check cron schedules in UTC

BDK evaluates cron schedules in UTC. A recipe routine that asks for a timezone produces a warning like:

routines/morning-launch-brief: BDK runs `0 8 * * 1-5` in UTC, not America/Los_Angeles; adjust the cron in bot/schedules/morning-launch-brief.md if the time matters.

The timezone answer documents the source intent; it does not rewrite the cron. Check each generated file under bot/schedules/ and translate local wall-clock times to UTC. For locations that observe daylight saving time, also decide how you will handle the offset change.

Use the handoff files

File	Purpose
`AGENTS.md`	Gives a coding agent the project commands and points it to the export handoff.
`SECRETS.md`	Lists secret names and connector sign-ins, without values.
`SLACK.md`	When Slack is selected, holds the Slack app setup notes.
`.cursor/skills/finish-grokbot-export/SKILL.md`	Guides a coding agent through the remaining setup, warnings, validation, and local test.
`.cursor/environment.json`	Tells a Cursor cloud agent to install the project with `npm install`.

Server-side secret transfer, automatic moves of existing Slack apps, and self-deploy are not shipped, so this guide does not cover those flows.

bdk init: flags, JSON output, and failures
Project layout: generated project files
Schedules and reminders: cron behavior
MCP connections: connector auth choices

Export a Grok Bot to a BDK project

Preview the export

bdk init ./launch-desk \  --from-grokbot ./launch-desk.recipe.json \  --dry-run

Selected lines from the example recipe's non-interactive preview look like this:

Dry run: "Launch Desk" → ./launch-desk (nothing written)  bot/agent.ts                                   profile  bot/channels/slack.ts                          routines/launch-questions, routines/blocker-watch, routines/ship-it  bot/instructions.md                            profile, gettingStarted, routines/launch-questions, routines/blocker-watch, routines/ship-it, memory  bot/mcp-connections/linear.ts                  plugins/linear  bot/schedules/morning-launch-brief.md          routines/morning-launch-brief  bot/skills/release-checklist/SKILL.md          skills/release-checklist  SECRETS.md                                     answers  ...Defaulted without asking:  - name  - description  - model  ...Not carried over:  - profile.avatar: BDK agents have no avatar; kept in grokbot-export.json for the Slack app icon.Secrets to set (names only; see SECRETS.md):  - LAUNCH_DESK_SLACK_APP_TOKEN  - LAUNCH_DESK_SLACK_BOT_TOKEN

Add --json when a script needs the preview:

bdk init ./launch-desk \  --from-grokbot ./launch-desk.recipe.json \  --dry-run \  --json

The core JSON shape is:

{  "ok": true,  "dryRun": true,  "directory": "/work/launch-desk",  "preview": {    "files": [],    "defaulted": [],    "ignored": [],    "excluded": [],    "unmapped": [],    "fillIns": [],    "secrets": { "names": [], "reauth": [] },    "warnings": [],    "setupSteps": []  }}

See bdk init for the complete preview fields and flag behavior.

Choose an answers file or the terminal interview

Run the command in a terminal when you want to review each choice once. Press Enter to accept a default.

bdk init ./launch-desk \  --from-grokbot ./launch-desk.recipe.json

Use --answers for a repeatable export or a non-interactive environment. This minimal file validates against the published schema and accepts every recipe default:

{  "$schema": "./node_modules/@cursor/bdk/schemas/grokbot-answers.schema.json",  "version": 1}

Save it as grokbot-answers.json, then run:

bdk init ./launch-desk \  --from-grokbot ./launch-desk.recipe.json \  --answers ./grokbot-answers.json

Write and check the project

bdk init ./launch-desk \  --from-grokbot ./launch-desk.recipe.json \  --answers ./grokbot-answers.jsoncd ./launch-deskbdk validatebdk dev

Open the playground from bdk dev and try the routines you plan to keep before connecting live channels.

Review what maps where

Grok Bot recipe part	BDK project result
Profile or persona	The name and description become `bot/agent.ts` and the opening of `bot/instructions.md`.
Skills	Each selected skill becomes `bot/skills/<slug>/SKILL.md`. An enabled, valid skill schedule also becomes `bot/schedules/<slug>.md` when the schedule channel is on.
Getting-started skill	`bot/instructions.md` tells the agent to use this skill for a new conversation.
Cron routines	A selected routine with a valid, enabled cron trigger becomes `bot/schedules/<slug>.md` when the schedule channel is on.
Slack routines	When the Slack channel is on, the routine text becomes a section in `bot/instructions.md`; mentions, channel watches, keywords, and reactions are wired in `bot/channels/slack.ts`. Missing trigger values remain as warnings or TODOs.
GitHub or webhook routines	When the corresponding channel is on, the preview adds a setup step to wire the trigger. A routine with no other wired trigger also becomes an on-request skill.
Other routines	A routine without a wired trigger becomes an on-request skill. The preview explains which trigger still needs work.
Memory	The default is `bot/skills/knowledge/SKILL.md`. Choose `memory: "kv"` for `bot/lib/memory-seed.json`, or `memory: "drop"` to leave it out.
Plugins and connectors	Each selected plugin becomes `bot/mcp-connections/<slug>.ts` using Cursor-account auth, OAuth, or a named bearer-token secret.
Routine placeholders	Values under `fillIns.<routine-slug>` replace placeholders such as `{slack_channel}`. Unfilled placeholders remain visible and produce warnings.
Export decisions	Resolved answers and recipe metadata are recorded in `grokbot-export.json`.

The generated project also includes the standard package, TypeScript, eval, memory-hook, and ignore files needed to run it.

Resolve what does not map

The preview separates choices you made from behavior the converter could not carry over:

Preview result	What it means	What to do
Left out	An answer excluded a skill, routine, plugin, or memory.	Change the matching `include` or `exclude` answer, or change `memory` from `"drop"`, then rerun; otherwise leave the item behind.
`BDK agents have no avatar`	The profile avatar is not an agent setting. Its metadata remains in `grokbot-export.json`.	Set an icon separately if the destination needs one.
`Unknown recipe field; ignored.`	The recipe contains a field this BDK version does not map.	Inspect the field and add its behavior to the generated project when needed.
`Paused schedule ...`	A paused cron trigger does not produce a schedule file.	Leave it paused, or add a schedule under `bot/schedules/`.
`trigger dropped: the ... channel is off.`	The answers disabled the channel used by a trigger.	Enable the channel in the answers or add the trigger manually after export.
`trigger has no BDK channel.`	The trigger type has no direct BDK channel mapping.	Add a supported channel or custom wake; use the generated on-request skill when one is present.
`is not a five-field cron expression.`	The source cron cannot become a BDK schedule.	Correct the expression and add the schedule before enabling it.
`placeholders ... are unfilled`	A routine still contains values such as `{slack_channel}`.	Set `fillIns.<routine-slug>` in the answers or edit the generated text.
`BDK has no built-in KV seed`	`memory: "kv"` writes data but does not load it into hosted KV.	Add your own `ctx.host.kv` seeding code, or use `memory: "skill"`.

Treat setup steps and warnings as the checklist for restoring the source behavior. A generated project is ready for review, not automatically ready for live traffic.

Set secrets and reconnect OAuth

The export carries secret names only, never values. SECRETS.md lists each name, where it is read, and every connector that needs a fresh sign-in.

Set local values in the environment where you run bdk dev. For a hosted deployment, let bdk prompt for each value:

bdk secrets set launch-desk LINEAR_API_KEY

OAuth tokens do not move with the recipe. Sign in to each OAuth connector again:

bdk mcp oauth notion

Add --store when the sign-in is for a hosted deployment.

Check cron schedules in UTC

BDK evaluates cron schedules in UTC. A recipe routine that asks for a timezone produces a warning like:

routines/morning-launch-brief: BDK runs `0 8 * * 1-5` in UTC, not America/Los_Angeles; adjust the cron in bot/schedules/morning-launch-brief.md if the time matters.

Use the handoff files

File	Purpose
`AGENTS.md`	Gives a coding agent the project commands and points it to the export handoff.
`SECRETS.md`	Lists secret names and connector sign-ins, without values.
`SLACK.md`	When Slack is selected, holds the Slack app setup notes.
`.cursor/skills/finish-grokbot-export/SKILL.md`	Guides a coding agent through the remaining setup, warnings, validation, and local test.
`.cursor/environment.json`	Tells a Cursor cloud agent to install the project with `npm install`.

Server-side secret transfer, automatic moves of existing Slack apps, and self-deploy are not shipped, so this guide does not cover those flows.

bdk init: flags, JSON output, and failures
Project layout: generated project files
Schedules and reminders: cron behavior
MCP connections: connector auth choices

Export a Grok Bot to a BDK project

Preview the export

bdk init ./launch-desk \  --from-grokbot ./launch-desk.recipe.json \  --dry-run

Selected lines from the example recipe's non-interactive preview look like this:

Dry run: "Launch Desk" → ./launch-desk (nothing written)  bot/agent.ts                                   profile  bot/channels/slack.ts                          routines/launch-questions, routines/blocker-watch, routines/ship-it  bot/instructions.md                            profile, gettingStarted, routines/launch-questions, routines/blocker-watch, routines/ship-it, memory  bot/mcp-connections/linear.ts                  plugins/linear  bot/schedules/morning-launch-brief.md          routines/morning-launch-brief  bot/skills/release-checklist/SKILL.md          skills/release-checklist  SECRETS.md                                     answers  ...Defaulted without asking:  - name  - description  - model  ...Not carried over:  - profile.avatar: BDK agents have no avatar; kept in grokbot-export.json for the Slack app icon.Secrets to set (names only; see SECRETS.md):  - LAUNCH_DESK_SLACK_APP_TOKEN  - LAUNCH_DESK_SLACK_BOT_TOKEN

Add --json when a script needs the preview:

bdk init ./launch-desk \  --from-grokbot ./launch-desk.recipe.json \  --dry-run \  --json

The core JSON shape is:

{  "ok": true,  "dryRun": true,  "directory": "/work/launch-desk",  "preview": {    "files": [],    "defaulted": [],    "ignored": [],    "excluded": [],    "unmapped": [],    "fillIns": [],    "secrets": { "names": [], "reauth": [] },    "warnings": [],    "setupSteps": []  }}

See bdk init for the complete preview fields and flag behavior.

Choose an answers file or the terminal interview

Run the command in a terminal when you want to review each choice once. Press Enter to accept a default.

bdk init ./launch-desk \  --from-grokbot ./launch-desk.recipe.json

Use --answers for a repeatable export or a non-interactive environment. This minimal file validates against the published schema and accepts every recipe default:

{  "$schema": "./node_modules/@cursor/bdk/schemas/grokbot-answers.schema.json",  "version": 1}

Save it as grokbot-answers.json, then run:

bdk init ./launch-desk \  --from-grokbot ./launch-desk.recipe.json \  --answers ./grokbot-answers.json

Write and check the project

bdk init ./launch-desk \  --from-grokbot ./launch-desk.recipe.json \  --answers ./grokbot-answers.jsoncd ./launch-deskbdk validatebdk dev

Open the playground from bdk dev and try the routines you plan to keep before connecting live channels.

Review what maps where

Grok Bot recipe part	BDK project result
Profile or persona	The name and description become `bot/agent.ts` and the opening of `bot/instructions.md`.
Skills	Each selected skill becomes `bot/skills/<slug>/SKILL.md`. An enabled, valid skill schedule also becomes `bot/schedules/<slug>.md` when the schedule channel is on.
Getting-started skill	`bot/instructions.md` tells the agent to use this skill for a new conversation.
Cron routines	A selected routine with a valid, enabled cron trigger becomes `bot/schedules/<slug>.md` when the schedule channel is on.
Slack routines	When the Slack channel is on, the routine text becomes a section in `bot/instructions.md`; mentions, channel watches, keywords, and reactions are wired in `bot/channels/slack.ts`. Missing trigger values remain as warnings or TODOs.
GitHub or webhook routines	When the corresponding channel is on, the preview adds a setup step to wire the trigger. A routine with no other wired trigger also becomes an on-request skill.
Other routines	A routine without a wired trigger becomes an on-request skill. The preview explains which trigger still needs work.
Memory	The default is `bot/skills/knowledge/SKILL.md`. Choose `memory: "kv"` for `bot/lib/memory-seed.json`, or `memory: "drop"` to leave it out.
Plugins and connectors	Each selected plugin becomes `bot/mcp-connections/<slug>.ts` using Cursor-account auth, OAuth, or a named bearer-token secret.
Routine placeholders	Values under `fillIns.<routine-slug>` replace placeholders such as `{slack_channel}`. Unfilled placeholders remain visible and produce warnings.
Export decisions	Resolved answers and recipe metadata are recorded in `grokbot-export.json`.

The generated project also includes the standard package, TypeScript, eval, memory-hook, and ignore files needed to run it.

Resolve what does not map

The preview separates choices you made from behavior the converter could not carry over:

Preview result	What it means	What to do
Left out	An answer excluded a skill, routine, plugin, or memory.	Change the matching `include` or `exclude` answer, or change `memory` from `"drop"`, then rerun; otherwise leave the item behind.
`BDK agents have no avatar`	The profile avatar is not an agent setting. Its metadata remains in `grokbot-export.json`.	Set an icon separately if the destination needs one.
`Unknown recipe field; ignored.`	The recipe contains a field this BDK version does not map.	Inspect the field and add its behavior to the generated project when needed.
`Paused schedule ...`	A paused cron trigger does not produce a schedule file.	Leave it paused, or add a schedule under `bot/schedules/`.
`trigger dropped: the ... channel is off.`	The answers disabled the channel used by a trigger.	Enable the channel in the answers or add the trigger manually after export.
`trigger has no BDK channel.`	The trigger type has no direct BDK channel mapping.	Add a supported channel or custom wake; use the generated on-request skill when one is present.
`is not a five-field cron expression.`	The source cron cannot become a BDK schedule.	Correct the expression and add the schedule before enabling it.
`placeholders ... are unfilled`	A routine still contains values such as `{slack_channel}`.	Set `fillIns.<routine-slug>` in the answers or edit the generated text.
`BDK has no built-in KV seed`	`memory: "kv"` writes data but does not load it into hosted KV.	Add your own `ctx.host.kv` seeding code, or use `memory: "skill"`.

Treat setup steps and warnings as the checklist for restoring the source behavior. A generated project is ready for review, not automatically ready for live traffic.

Set secrets and reconnect OAuth

The export carries secret names only, never values. SECRETS.md lists each name, where it is read, and every connector that needs a fresh sign-in.

Set local values in the environment where you run bdk dev. For a hosted deployment, let bdk prompt for each value:

bdk secrets set launch-desk LINEAR_API_KEY

OAuth tokens do not move with the recipe. Sign in to each OAuth connector again:

bdk mcp oauth notion

Add --store when the sign-in is for a hosted deployment.

Check cron schedules in UTC

BDK evaluates cron schedules in UTC. A recipe routine that asks for a timezone produces a warning like:

routines/morning-launch-brief: BDK runs `0 8 * * 1-5` in UTC, not America/Los_Angeles; adjust the cron in bot/schedules/morning-launch-brief.md if the time matters.

Use the handoff files

File	Purpose
`AGENTS.md`	Gives a coding agent the project commands and points it to the export handoff.
`SECRETS.md`	Lists secret names and connector sign-ins, without values.
`SLACK.md`	When Slack is selected, holds the Slack app setup notes.
`.cursor/skills/finish-grokbot-export/SKILL.md`	Guides a coding agent through the remaining setup, warnings, validation, and local test.
`.cursor/environment.json`	Tells a Cursor cloud agent to install the project with `npm install`.

Server-side secret transfer, automatic moves of existing Slack apps, and self-deploy are not shipped, so this guide does not cover those flows.

bdk init: flags, JSON output, and failures
Project layout: generated project files
Schedules and reminders: cron behavior
MCP connections: connector auth choices

Command Palette

Get Started

Agent

Grok Bot

Customize

Cloud Agents

Origin

Integrations

SDK

BDK

CLI

Teams & Enterprise

Export a Grok Bot to a BDK project

Command Palette

Get Started

Agent

Grok Bot

Customize

Cloud Agents

Origin

Integrations

SDK

BDK

CLI

Teams & Enterprise

Export a Grok Bot to a BDK project

Command Palette

Get Started

Agent

Grok Bot

Customize

Cloud Agents

Origin

Integrations

SDK

BDK

CLI

Teams & Enterprise

Export a Grok Bot to a BDK project