--- name: trigger-dev-bootstrap description: Log in or sign up to Trigger.dev, create or choose an organization and project, add Trigger.dev to a JavaScript or TypeScript app, and run a first background task. Use when asked to get started with, set up, or bootstrap Trigger.dev, not for SDK migrations or production deployment. --- # Bootstrap a Trigger.dev project Guide the user from login to a successful local task run. Done means the app has the Trigger.dev SDK, a config with a real project ref, an example task, and a dev worker that has completed a test run visible in the dashboard. Finish with a short summary and offer to build the user's actual first task. If blocked, say what is complete and what remains. ## How to talk to the user The user may be new to Trigger.dev. Start with one or two sentences on what will happen: sign in, pick or create a project, add an example task, and run it locally, which usually takes a few minutes. Before any step that needs the user, say in one sentence what they need to do and why. Summarize command output instead of pasting it. Keep messages short and friendly, and celebrate the first successful run. ## 1. Inspect the app Before changing files, read the repo instructions, `package.json`, lockfile, workspace configuration, and any `trigger.config.ts` or `trigger.config.mjs`. Inspect existing task files and SDK versions. | Signal | Action | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Existing Trigger.dev config | Reuse its project ref, task directories, runtime, and package versions. Skip `init`; do not replace the config. If the SDK is declared but not installed, run the repo's install command. | | Multiple workspace apps | Use the app the user identified or the existing tasks package. Otherwise suggest the app with server code; ask if more than one is plausible. Do not restructure the monorepo. | | JavaScript app | Keep JavaScript and pass `--javascript` to `init`. | | No `package.json` | Ask whether to use an existing app or create a minimal standalone TypeScript project in a suggested directory. Do not scaffold a framework. | | SDK v3 or older | Do not silently upgrade. Explain that this onboarding flow targets v4; ask before switching to version-specific guidance or a migration. | Infer the project name from the app's package name (remove an npm scope), falling back to the directory name. Run the remaining commands from the selected app directory, not the monorepo root. Commands below use `npx trigger.dev@latest`. Match the repo's package manager: use `pnpm dlx`, `yarn dlx`, or `bunx` instead of `npx` where appropriate. Always use `@latest` for account commands (`whoami`, `login`, `orgs`, `projects`, `runs`), because older CLI versions lack some of them. For `init` and `dev` in an existing setup, use the CLI version matching the installed SDK rather than changing dependencies. Check `--help` when a command differs; never invent flags. Ask only for choices that cannot be inferred safely. Batch them into one message with concrete options and a recommended default. State inferred values so the user can correct them. Never guess between ambiguous accounts, organizations, projects, or apps. ## 2. Log in Run: ```sh npx trigger.dev@latest whoami ``` If authenticated, tell the user which account is active and continue unless they want a different account. Keep any existing CLI profile or self-hosted API URL consistent across commands. Otherwise, tell the user they will get a link to sign in or sign up and authorize the CLI. Do not ask for their email or name; the login page handles that. Run: ```sh npx trigger.dev@latest login --no-browser --no-wait ``` Send the printed URL to the user and wait for them to say they have authorized it. Do not automate the browser or retry while waiting. Then resume the saved login: ```sh npx trigger.dev@latest login --no-browser npx trigger.dev@latest whoami ``` ## 3. Choose or create the project **Existing config:** validate its ref with `npx trigger.dev@latest projects get `, then go to step 4. If access fails, resolve the account, profile, or project with the user; do not create a replacement project. **No config:** run these to see the user's organizations and projects: ```sh npx trigger.dev@latest orgs list npx trigger.dev@latest projects list ``` `orgs list` shows each organization's name, slug, and ID, including organizations without projects. `projects list` lists every accessible project with its organization and ref; its heading and runtime columns refer to Production deployments, which you can ignore. - If the user gave a project ref, use it. If a listed project matches the repo name, offer to link it or create a new one. Do not link an unrelated project just because it is the only one. - Use the only organization if there is one. If there are several, offer a numbered choice. - State the inferred project name before creating it. If a new organization is needed, suggest a name based on the repo and ask once. Organization names must be 3 to 50 characters. Never create an additional organization on an existing account without an explicit request. Then use one of these paths. ### Link an existing project ```sh npx trigger.dev@latest init --yes --project-ref "" --no-browser ``` ### New account with no organizations ```sh npx trigger.dev@latest init --yes --org-name "" --project-name "" --no-browser ``` This creates the organization, activates the Free plan if needed, and creates the project. ### Organization exists but has no projects yet If the account has exactly one organization and no projects, `init` uses that organization: ```sh npx trigger.dev@latest init --yes --project-name "" --no-browser ``` Otherwise use the next path. ### Any other case Create the project in the chosen organization by slug, then link it: ```sh npx trigger.dev@latest projects create --org "" --name "" npx trigger.dev@latest init --yes --project-ref "" --no-browser ``` If the user explicitly wants an additional organization, first run `npx trigger.dev@latest orgs create --name ""` and use the returned slug. `projects create` activates the Free plan for an organization that has no plan yet. Do not activate a paid plan or change billing to get past an error. `init` installs packages, writes the config, and generates `src/trigger/example.ts` (or `example.mjs` for JavaScript) with task ID `hello-world`. Use that task instead of writing a duplicate. Read the generated config and task to confirm the paths and ref. ## 4. Run and verify locally Check that the config ref matches the chosen project. For existing setups, use the configured task directory. If there is no harmless example task, read https://trigger.dev/docs/tasks/overview.md and add a minimal task with a unique ID and no external side effects. Do not trigger an existing business task to test setup. Use this harmless task's ID wherever `` appears below; it is `hello-world` only when that is the generated example. Tell the user you are starting the local worker, then run: ```sh npx trigger.dev@latest dev ``` Run it with your long-running process facility and keep its output accessible. If you have none, give the user the command and app directory to run in their own terminal. Reuse an already-running worker for this project rather than starting a duplicate. Wait for `Local worker ready` before testing. Trigger the test run: - If Trigger.dev MCP tools are already connected, you may call `trigger_task` for `` in the dev environment. - Otherwise, give the user the "Test tasks" link printed by `dev` (`/projects/v3//test?environment=dev`). Ask them to select ``, enter a payload that matches the task (for the generated example, `{"message": "Hello from my first task"}`), and press **Run test**. If the link does not work, they can open the task from the Tasks page and press **Test**. Confirm the run completed yourself rather than asking the user. The worker output shows each run finishing, or run: ```sh npx trigger.dev@latest runs list --env dev --task --limit 5 ``` The `--env dev` flag is required; `runs list` defaults to Production. Worker readiness alone is not a successful run. The CLI login is enough for this workflow; do not ask for `TRIGGER_SECRET_KEY`. App-side triggering can be set up later with a Development key stored locally, never pasted into chat or committed. ## 5. Summarize and help them build Keep the summary short: - The project name and dashboard link, and whether it was created or reused. - Where tasks live (the config's `dirs`) and the example task file. - Whether `dev` is still running, and how to start or stop it. If blocked, give the exact remaining action instead. If the user already described what they want to build, offer to implement it next. Otherwise ask "What would you like your first task to do?" and suggest one use case that fits their app. Before writing the next task, read the relevant docs: https://trigger.dev/docs/tasks/overview.md, https://trigger.dev/docs/triggering.md, or https://trigger.dev/docs/tasks/scheduled.md. Find other pages through https://trigger.dev/docs/llms.txt. Do not deploy as part of onboarding. ## Recovery and boundaries | Problem | Recovery | | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Pending or expired login | Resume the pending login after authorization. If expired, explain it and request a fresh link once; do not loop. | | `Projects already exist for this account` | Use an explicit ref, or create a project with `projects create` as above. | | `Multiple organizations are available` or duplicate names | Ask the user to choose from `orgs list`, then use its slug with `projects create`. Do not pick the first result. | | Existing config or task directory | Reuse the existing setup. If it is partial, read https://trigger.dev/docs/manual-setup.md and propose only the missing changes. Never use `--override-config` or delete files without consent. | | Invalid ref or permission denied | Check the account, profile, and ref. Ask the user to resolve access; do not create duplicates. | | Dependency or build failure | Fix only setup-related issues. Do not change package managers, bypass repo safeguards, or upgrade unrelated dependencies. | | Unknown failure, billing requirement, or unavailable command | Show the command and a redacted error, report progress so far, and ask for the required action. Check what was created before retrying. | Never read or print stored CLI credentials, ask for secrets in chat, commit environment files, deploy, touch production runs, or refactor application code beyond this setup.