feat(cli): show the deploy environment, add --prod, and use the API key's environment

`trigger deploy` and `trigger promote` now say which environment they're
targeting and accept `--prod` as a shorthand for `--env prod`. When
`TRIGGER_ACCESS_TOKEN` holds an environment API key and you don't pass
`--env`, they use that key's environment instead of assuming prod.
Passing an `--env` that doesn't match the key is now an error.

Preview deploys now detect the branch on CI providers that check out a
detached HEAD, such as GitLab, Bitbucket, CircleCI, Buildkite, Travis
CI, Jenkins and Azure Pipelines. Test links after a preview deploy now
open the branch you deployed. The MCP `deploy` tool no longer defaults
to prod. The docs and the dashboard's deploy command now pass `--env
prod` explicitly.

Mono-RevId: 008decd79ebb1b7375e4dfa522a19fb3d97ff32d

Author: ericallam

.changeset/deploy-explicit-env.md

@@ -0,0 +1,10 @@
+---
+"trigger.dev": patch
+"@trigger.dev/core": patch
+---
+
+`trigger deploy` and `trigger promote` now say which environment they're targeting, and accept `--prod` as a shorthand for `--env prod`. When `TRIGGER_ACCESS_TOKEN` holds an environment API key and you don't pass `--env`, they now use that key's environment instead of assuming prod. Passing an `--env` that doesn't match the key is now an error, where before the deploy went to the key's environment.
+
+Preview deploys now detect the branch on CI providers that check out a detached HEAD, such as GitLab, Bitbucket, CircleCI, Buildkite, Travis CI, Jenkins and Azure Pipelines, instead of creating a branch called `HEAD`. Test links printed after a preview deploy now open the preview branch you deployed instead of staging.
+
+The MCP `deploy` tool no longer defaults to prod, so your AI assistant has to choose the environment.

apps/webapp/app/components/SetupCommands.tsx

@@ -235,7 +235,7 @@ export function TriggerDeployStep({
         return " --env preview";
       case "PRODUCTION":
       default:
-        return "";
+        return " --env prod";
     }
   };
 

apps/webapp/app/routes/projects.v3.$projectRef.test.ts

@@ -1,5 +1,6 @@
 import type { LoaderFunctionArgs } from "@remix-run/server-runtime";
 import { redirect } from "@remix-run/server-runtime";
+import { sanitizeBranchName } from "@trigger.dev/core/v3/utils/gitBranch";
 import { z } from "zod";
 import { prisma } from "~/db.server";
 import { requireUserId } from "~/services/session.server";
@@ -36,10 +37,28 @@ export async function loader({ params, request }: LoaderFunctionArgs) {
 
   const url = new URL(request.url);
   const environment = url.searchParams.get("environment");
+  const branch = sanitizeBranchName(url.searchParams.get("branch"));
 
   if (environment) {
+    // The CLI links preview deploys by branch name. Branch environments have their own slug.
+    const branchEnvironment = branch
+      ? await prisma.runtimeEnvironment.findFirst({
+          select: { slug: true },
+          where: {
+            projectId: project.id,
+            branchName: branch,
+            archivedAt: null,
+            parentEnvironment: { slug: environment, type: "PREVIEW" },
+          },
+        })
+      : null;
+
     return redirect(
-      v3TestPath({ slug: project.organization.slug }, { slug: project.slug }, { slug: environment })
+      v3TestPath(
+        { slug: project.organization.slug },
+        { slug: project.slug },
+        { slug: branchEnvironment?.slug ?? environment }
+      )
     );
   }
 

docs/apikeys.mdx

@@ -98,11 +98,11 @@ Set a key in `TRIGGER_ACCESS_TOKEN` to authenticate `trigger deploy` without log
 <CodeGroup>
 
 ```bash npm
-TRIGGER_ACCESS_TOKEN="tr_prod_sk_…" npx trigger.dev@latest deploy
+TRIGGER_ACCESS_TOKEN="tr_prod_sk_…" npx trigger.dev@latest deploy --env prod
 ```
 </CodeGroup>
 
-The key must belong to the target environment. Use a Production key for the default deployment, a Staging key with `--env staging`, or a key from the Preview environment with `--env preview`. A Preview deployment key can create and archive Preview branches and sync their environment variables.
+The key must belong to the target environment. Use a Production key with `--env prod`, a Staging key with `--env staging`, or a key from the Preview environment with `--env preview`. If you leave out `--env`, the CLI deploys to the key's environment, and a `--env` that doesn't match the key is an error. A Preview deployment key can create and archive Preview branches and sync their environment variables.
 
 <Note>
   The deploy CLI reads environment API keys from `TRIGGER_ACCESS_TOKEN`, not

docs/config/extensions/prismaExtension.mdx

@@ -189,7 +189,7 @@ prismaExtension({
   "scripts": {
     "prebuild": "prisma generate",
     "dev": "trigger dev",
-    "deploy": "trigger deploy"
+    "deploy": "trigger deploy --env prod"
   }
 }
 ```
@@ -331,7 +331,7 @@ steps:
   - name: Generate Prisma client
     run: npx prisma@6.19.0 generate
   - name: Deploy Trigger.dev
-    run: npx trigger.dev@4.1.1 deploy
+    run: npx trigger.dev@4.1.1 deploy --env prod
     env:
       TRIGGER_ACCESS_TOKEN: ${{ secrets.TRIGGER_ACCESS_TOKEN }}
 ```
@@ -902,7 +902,7 @@ datasource db {
   "scripts": {
     "generate": "prisma generate",
     "dev": "pnpm generate && trigger dev",
-    "deploy": "trigger deploy"
+    "deploy": "trigger deploy --env prod"
   }
 }
 ```
@@ -975,7 +975,7 @@ export default defineConfig({
   "scripts": {
     "generate": "prisma generate",
     "dev": "pnpm generate && trigger dev",
-    "deploy": "trigger deploy"
+    "deploy": "trigger deploy --env prod"
   }
 }
 ```

docs/deployment/atomic-deployment.mdx

@@ -60,7 +60,7 @@ The id is free-form and opaque to Trigger.dev — a commit SHA, a release tag, a
 <Step title="Deploy your tasks with an external id">
 
 ```bash
-npx trigger.dev@latest deploy --external-id "$(git rev-parse HEAD)"
+npx trigger.dev@latest deploy --env prod --external-id "$(git rev-parse HEAD)"
 ```
 
 </Step>
@@ -240,7 +240,7 @@ Read the commit in the place where it *is* available, and write it into both hal
 
 ```bash
 # 1. Deploy side — name the deployment after the commit.
-npx trigger.dev@latest deploy --external-id "$(git rev-parse HEAD)"
+npx trigger.dev@latest deploy --env prod --external-id "$(git rev-parse HEAD)"
 
 # 2. Application side — give the running app the same value.
 TRIGGER_EXTERNAL_DEPLOYMENT_ID=<the-same-commit-sha>
@@ -385,7 +385,7 @@ If you filter deploys by path, derive the id from the same filter on both sides
 
 ```bash
 TASK_ID=$(git log -1 --format=%H -- trigger/)
-npx trigger.dev@latest deploy --external-id "$TASK_ID"
+npx trigger.dev@latest deploy --env prod --external-id "$TASK_ID"
 ```
 
 Compute the same value where you set your app's variable. In GitHub Actions this needs `fetch-depth: 0` on `actions/checkout` — the default shallow clone can't see far enough back.

docs/deployment/overview.mdx

@@ -162,7 +162,7 @@ To keep your app and tasks in sync without coordinating promotion at all, see [a
 
 ## Staging deploys
 
-By default, the `deploy` command will deploy to the `prod` environment. If you want to deploy to a different environment, you can use the `--env` flag:
+Use the `--env` flag to choose the environment you deploy to. If you don't pass it, the `deploy` command deploys to the `prod` environment, unless `TRIGGER_ACCESS_TOKEN` holds an API key for another environment. To deploy to staging:
 
 ```bash
 npx trigger.dev deploy --env staging

docs/deployment/preview-branches.mdx

@@ -147,7 +147,7 @@ Creating and deploying a preview branch manually is easy:
 npx trigger.dev@latest deploy --env preview
 ```
 
-This will create and deploy a preview branch, automatically detecting the git branch. If for some reason the auto-detection doesn't work it will let you know and tell you do this:
+This will create and deploy a preview branch, automatically detecting the git branch. When your CI checks out a detached HEAD, the branch is read from the CI provider's branch variable instead (GitLab, Bitbucket, CircleCI, Buildkite, Travis CI, Jenkins and Azure Pipelines are supported). If for some reason the auto-detection doesn't work it will let you know and tell you do this:
 
 ```bash
 npx trigger.dev@latest deploy --env preview --branch your-branch-name

docs/github-actions.mdx

@@ -47,7 +47,7 @@ jobs:
         env:
           TRIGGER_ACCESS_TOKEN: ${{ secrets.TRIGGER_ACCESS_TOKEN }}
         run: |
-          npx trigger.dev@latest deploy --external-id ${{ github.sha }}
+          npx trigger.dev@latest deploy --env prod --external-id ${{ github.sha }}
 ```
 
 ```yaml .github/workflows/release-trigger-staging.yml
@@ -184,7 +184,7 @@ Tip: add the `trigger.dev` CLI to your `devDependencies` and the deploy command
 ```json
 {
   "scripts": {
-    "deploy:trigger-prod": "trigger deploy",
+    "deploy:trigger-prod": "trigger deploy --env prod",
     "deploy:trigger": "trigger deploy --env staging"
   },
   "devDependencies": {
@@ -254,7 +254,7 @@ jobs:
           TRIGGER_ACCESS_TOKEN: ${{ secrets.TRIGGER_ACCESS_TOKEN }}
           TRIGGER_API_URL: ${{ secrets.TRIGGER_API_URL }}
         run: |
-          npx trigger.dev@latest deploy
+          npx trigger.dev@latest deploy --env prod
 ```
 
 </CodeGroup>

docs/manual-setup.mdx

@@ -109,7 +109,7 @@ Then add scripts to your `package.json`:
 {
   "scripts": {
     "dev:trigger": "trigger dev",
-    "deploy:trigger": "trigger deploy"
+    "deploy:trigger": "trigger deploy --env prod"
   }
 }
 ```