@trigger.dev/sdk 4.7.3 → 4.7.5

package/docs/cli-runs-commands.mdx

@@ -7,7 +7,6 @@ description: "Use these commands to list, inspect, replay and cancel runs from y
 import CommonOptions from "/snippets/cli-options-common.mdx";
 import ConfigFileOptions from "/snippets/cli-options-config-file.mdx";
 import ProjectRefOptions from "/snippets/cli-options-project-ref.mdx";
-import BranchOptions from "/snippets/cli-options-branch.mdx";
 
 ## runs list
 
@@ -85,7 +84,9 @@ npx trigger.dev@latest runs cancel run_abc123
 
 <ConfigFileOptions />
 <ProjectRefOptions />
-<BranchOptions />
+<ParamField body="Branch" type="--branch | -b">
+  Required when using `--env preview`. Specify the branch, e.g. `--branch my-branch` or `-b my-branch`. With `--env dev`, it defaults to the same [dev branch](/deployment/dev-branches) as the dev command.
+</ParamField>
 
 ### Common options
 

package/docs/cli-tasks-commands.mdx

@@ -0,0 +1,95 @@
+---
+title: "CLI tasks commands"
+sidebarTitle: "tasks"
+description: "Use these commands to trigger tasks from your terminal."
+---
+
+import CommonOptions from "/snippets/cli-options-common.mdx";
+import ConfigFileOptions from "/snippets/cli-options-config-file.mdx";
+import ProjectRefOptions from "/snippets/cli-options-project-ref.mdx";
+
+## tasks trigger
+
+Triggers a task and prints the run ID and its dashboard URL. It runs in the `dev` environment unless you pass `--env`, so start the [dev command](/cli-dev-commands) first.
+
+<CodeGroup>
+
+```bash npm
+npx trigger.dev@latest tasks trigger hello-world --payload '{"name":"Ada"}'
+```
+
+```bash pnpm
+pnpm dlx trigger.dev@latest tasks trigger hello-world --payload '{"name":"Ada"}'
+```
+
+```bash yarn
+yarn dlx trigger.dev@latest tasks trigger hello-world --payload '{"name":"Ada"}'
+```
+
+</CodeGroup>
+
+Add `--wait` to wait for the run to finish. It prints the run's output, or its error and exits with code 1 if the run failed, which makes it useful in scripts and for coding agents testing a task:
+
+```bash
+npx trigger.dev@latest tasks trigger hello-world --payload '{"name":"Ada"}' --wait
+```
+
+The command fails without creating a run if the current version has no task with that ID. In `dev`, it warns you when the dev command isn't running, because the run waits in the queue until it starts.
+
+<ParamField body="Payload" type="--payload">
+  The payload as JSON, e.g. `--payload '{"name":"Ada"}'`. Without it, the task gets no payload.
+</ParamField>
+
+<ParamField body="Payload file" type="--payload-file">
+  Read the payload from a JSON file instead.
+</ParamField>
+
+<ParamField body="Wait" type="--wait">
+  Wait for the run to finish, then print its output or error.
+</ParamField>
+
+<ParamField body="Timeout" type="--timeout">
+  With `--wait`, stop waiting after this many seconds and exit with code 1.
+</ParamField>
+
+<ParamField body="Tag" type="--tag">
+  A tag to add to the run. Repeat it to add more than one, e.g. `--tag cli --tag test`.
+</ParamField>
+
+<ParamField body="Idempotency key" type="--idempotency-key">
+  If a run with this key already exists, return it instead of creating a new one. See [idempotency](/idempotency).
+</ParamField>
+
+<ParamField body="Delay" type="--delay">
+  Wait before running, e.g. `30s`, `5m` or an ISO 8601 date.
+</ParamField>
+
+<ParamField body="TTL" type="--ttl">
+  Expire the run if it hasn't started within this time, e.g. `10m`.
+</ParamField>
+
+<ParamField body="Queue" type="--queue">
+  The queue to run in, instead of the queue set on the task.
+</ParamField>
+
+<ParamField body="Machine" type="--machine">
+  The machine to run on, e.g. `small-2x`. See [machines](/machines). Has no effect in `dev`.
+</ParamField>
+
+## Options
+
+<ParamField body="Environment" type="--env | -e">
+  The environment to use: `dev`, `prod`, `staging` or `preview`. Defaults to `dev`.
+</ParamField>
+
+<ConfigFileOptions />
+<ProjectRefOptions />
+<ParamField body="Branch" type="--branch | -b">
+  The branch to use. Required with `--env preview`. In `dev`, it defaults to the same [dev branch](/deployment/dev-branches) as the dev command.
+</ParamField>
+
+### Common options
+
+These options are available on most commands.
+
+<CommonOptions />

package/docs/cli-update-commands.mdx

@@ -14,19 +14,25 @@ Run the command like this:
 <CodeGroup>
 
 ```bash npm
-npx trigger.dev@latest update
+npx trigger.dev@latest update [path]
 ```
 
 ```bash pnpm
-pnpm dlx trigger.dev@latest update
+pnpm dlx trigger.dev@latest update [path]
 ```
 
 ```bash yarn
-yarn dlx trigger.dev@latest update
+yarn dlx trigger.dev@latest update [path]
 ```
 
 </CodeGroup>
 
+## Arguments
+
+<ParamField body="Project path" type="[path]">
+  The directory that contains the `package.json` file. Defaults to `.`.
+</ParamField>
+
 ## Options
 
 ### Common options

package/docs/cli-whoami-commands.mdx

@@ -26,6 +26,18 @@ yarn dlx trigger.dev@latest whoami
 
 ## Options
 
+<ParamField body="Config file" type="-c, --config <config file>">
+  The name of the config file.
+</ParamField>
+
+<ParamField body="Project ref" type="-p, --project-ref <project ref>">
+  The project ref. Overrides the project in the config file.
+</ParamField>
+
+<ParamField body="Env file" type="--env-file <env file>">
+  Path to a `.env` file to read `TRIGGER_PROJECT_REF` from. Defaults to `.env`, `.env.development`, `.env.local`, `.env.development.local` and `dev.vars` in the current directory.
+</ParamField>
+
 ### Common options
 
 These options are available on most commands.

package/docs/concurrency.mdx

@@ -367,6 +367,38 @@ await concurrencyLimits.reset("openai");
 
 Overrides survive deploys: redeploying your code keeps an active override until you reset it.
 
+### Overriding a limit for one key
+
+Pass `concurrencyKey` to override a limit's `perKey` for a single key, for example to let one session run more (or fewer) runs at once than the limit allows every other key:
+
+```ts
+import { concurrencyLimits } from "@trigger.dev/sdk";
+
+// this session may run 3 at once under "subagents", for the next 7 days
+await concurrencyLimits.override("subagents", {
+  concurrencyKey: sessionId,
+  perKey: 3,
+  ttl: "7d",
+});
+
+// read it back: the key's bound, the override, and when it expires
+const view = await concurrencyLimits.retrieve("subagents", { concurrencyKey: sessionId });
+console.log(view.perKey.override, view.perKey.expiresAt, view.running);
+
+// clear it early
+await concurrencyLimits.reset("subagents", { concurrencyKey: sessionId });
+```
+
+A per-key override behaves differently from a limit override:
+
+- **It is temporary.** It expires after `ttl` (a duration such as `"7d"` or a number of seconds). The default is 7 days and the maximum is 30 days. Call `override` again to extend it. Nothing warns you when it lapses, so check `expiresAt` if a key must keep its cap for longer than a week.
+- **It changes one limit only.** The limit's own bounds and every other limit the run holds are untouched. A tenant-wide limit keeps applying on top of a per-session override.
+- **It applies to every task holding the limit**, because the key's pool under a shared named limit is one pool.
+- **It needs a `perKey` to override.** A limit declared with only a `total` has no per-key bound, so the call is rejected, and if a later deploy removes a limit's `perKey` its per-key overrides stop applying. A task's inline limit is addressed as `task/<task-id>`. `total` is not per key, so `concurrencyKey` goes with `perKey` (and optionally `ttl`) and never with `total`; the SDK's types enforce this.
+- **`perKey: 0` blocks the key.** A paused limit stays paused whatever the override says.
+- **It does not stop runs.** Lowering a key's cap takes effect at the next run to start; runs already executing continue.
+- **`reset(name)` without a key leaves per-key overrides alone**; clear them with `reset(name, { concurrencyKey })` or let them expire.
+
 ### Pausing a limit
 
 Pause a limit to stop every run holding it from being dequeued; runs that are already executing continue to completion. The configured bounds are kept, and resuming restores them:

package/docs/config/config-file.mdx

@@ -267,6 +267,64 @@ export default defineConfig({
 });
 ```
 
+### Span processors
+
+Span processors run on every span before it is exported, to Trigger.dev and to any `exporters` you configure. Use them to redact or drop span content before it reaches the run trace.
+
+```ts trigger.config.ts
+import { defineConfig } from "@trigger.dev/sdk";
+import type { AttributeValue, Attributes } from "@opentelemetry/api";
+import type { SpanProcessor } from "@opentelemetry/sdk-trace-base";
+
+const EMAIL = /[\w.+-]+@[\w-]+\.[\w.]+/g;
+
+function redact(value: AttributeValue | undefined): AttributeValue | undefined {
+  if (typeof value === "string") return value.replace(EMAIL, "[email]");
+  // Some attributes are string arrays, like the messages sent mid-turn
+  if (Array.isArray(value)) {
+    return value.map((item) =>
+      typeof item === "string" ? item.replace(EMAIL, "[email]") : item
+    ) as AttributeValue;
+  }
+  return value;
+}
+
+function scrub(attributes: Attributes) {
+  for (const key of Object.keys(attributes)) attributes[key] = redact(attributes[key]);
+}
+
+const redactEmails: SpanProcessor = {
+  onStart: () => {},
+  // The span is complete here and still writable
+  onEnding: (span) => {
+    scrub(span.attributes);
+    for (const event of span.events) scrub(event.attributes ?? {});
+  },
+  onEnd: () => {},
+  forceFlush: async () => {},
+  shutdown: async () => {},
+};
+
+export default defineConfig({
+  project: "<project ref>",
+  telemetry: {
+    spanProcessors: [redactEmails],
+  },
+});
+```
+
+Your processors run ahead of ours, so they also see the in-progress copy of each span that the dashboard shows while a span is open. Redact in `onEnding`:
+
+- `onStart` runs before we add the run context, so it sees only the attributes the span was started with.
+- In `onEnd` the span is read-only and `setAttribute` does nothing. Writing to `span.attributes` directly still works.
+- Content can also sit in span events (exceptions, for example). Events are on `span.events`.
+
+After each call we restore the few attributes we use to link a span to its run, such as the run, task and attempt ids. Everything else can be redacted, including run tags and idempotency keys. If a processor throws, the error is reported and the span is still exported.
+
+<Note>
+  Span processors only change span content. Run payloads and outputs, and the messages on a chat agent's session streams, are stored as sent. For chat agents, see [Redact chat content from traces](/ai-chat/patterns/redacting-telemetry).
+</Note>
+
 ## Runtime
 
 If you don't set a `runtime`, your tasks run on the current Node.js LTS. Setting `runtime: "node"` does the same thing — see the Node.js versions section below to pin a specific version instead.

package/docs/config/extensions/audioWaveform.mdx

@@ -14,7 +14,10 @@ export default defineConfig({
   project: "<project ref>",
   // Your other config settings...
   build: {
-    extensions: [audioWaveform()], // uses verson 1.1.0 of audiowaveform by default
+    extensions: [audioWaveform()], // uses version 1.10.1 of audiowaveform by default
   },
 });
 ```
+
+To use a different version, pass the `version` and `checksum` options to `audioWaveform()`.
+

package/docs/config/extensions/overview.mdx

@@ -51,6 +51,8 @@ Trigger.dev provides a set of built-in extensions that you can use to customize
 | [prismaExtension](/config/extensions/prismaExtension)                 | Using prisma in your Trigger.dev tasks                                         |
 | [pythonExtension](/config/extensions/pythonExtension)                 | Execute Python scripts in your project                                         |
 | [puppeteer](/config/extensions/puppeteer)                             | Use Puppeteer in your Trigger.dev tasks                                        |
+| [playwright](/config/extensions/playwright)                           | Use Playwright in your Trigger.dev tasks                                       |
+| [lightpanda](/config/extensions/lightpanda)                           | Use Lightpanda in your Trigger.dev tasks                                       |
 | [ffmpeg](/config/extensions/ffmpeg)                                   | Use FFmpeg in your Trigger.dev tasks                                           |
 | [aptGet](/config/extensions/aptGet)                                   | Install system packages in your build image                                    |
 | [additionalFiles](/config/extensions/additionalFiles)                 | Copy additional files to your build image                                      |

package/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 }}
 ```
@@ -641,7 +641,7 @@ prismaExtension({
 ```prisma
 generator client {
   provider      = "prisma-client-js"
-  binaryTargets = ["native", "linux-arm64-openssl-3.0.x"]
+  binaryTargets = ["native", "debian-openssl-3.0.x"]
 }
 ```
 
@@ -885,7 +885,7 @@ export const db = new PrismaClient({
 generator client {
   provider      = "prisma-client-js"
   output        = "../src/generated/prisma"
-  binaryTargets = ["native", "linux-arm64-openssl-3.0.x"]
+  binaryTargets = ["native", "debian-openssl-3.0.x"]
 }
 
 datasource db {
@@ -902,7 +902,7 @@ datasource db {
   "scripts": {
     "generate": "prisma generate",
     "dev": "pnpm generate && trigger dev",
-    "deploy": "trigger deploy"
+    "deploy": "trigger deploy --env prod"
   }
 }
 ```
@@ -913,7 +913,6 @@ datasource db {
 prismaExtension({
   mode: "engine-only",
   version: "6.19.0",
-  binaryTarget: "linux-arm64-openssl-3.0.x",
 });
 ```
 
@@ -976,7 +975,7 @@ export default defineConfig({
   "scripts": {
     "generate": "prisma generate",
     "dev": "pnpm generate && trigger dev",
-    "deploy": "trigger deploy"
+    "deploy": "trigger deploy --env prod"
   }
 }
 ```

package/docs/config/extensions/puppeteer.mdx

@@ -4,6 +4,8 @@ sidebarTitle: "puppeteer"
 description: "Use the puppeteer build extension to enable support for Puppeteer in your project"
 ---
 
+import ScrapingWarning from "/snippets/web-scraping-warning.mdx";
+
 <ScrapingWarning />
 
 To use Puppeteer in your project, add these build settings to your `trigger.config.ts` file:
@@ -21,10 +23,6 @@ export default defineConfig({
 });
 ```
 
-And add the following environment variable in your Trigger.dev dashboard on the Environment Variables page:
-
-```bash
-PUPPETEER_EXECUTABLE_PATH: "/usr/bin/google-chrome-stable",
-```
+The extension installs Chrome and sets `PUPPETEER_EXECUTABLE_PATH=/usr/bin/google-chrome-stable` for deployed builds automatically, so you do not need to set it. Don't set it in your Dev environment: the extension does nothing in Dev, and locally Puppeteer uses the browser it downloads on install.
 
 Follow [this example](/guides/examples/puppeteer) to get setup with Trigger.dev and Puppeteer in your project.

package/docs/config/extensions/pythonExtension.mdx

@@ -103,6 +103,14 @@ export default defineConfig({
 
 This will install the packages specified in the `requirements.txt` file during the build process. You can then use these packages in your Python scripts.
 
+You can also list requirements inline with the `requirements` option instead. You can't use it together with `requirementsFile`:
+
+```ts
+pythonExtension({
+  requirements: ["pandas"],
+});
+```
+
 <Note>
   The `requirementsFile` option is only available in production mode. In development mode, you can
   install the required packages manually using the `pip` command.
@@ -145,7 +153,7 @@ export const myStreamingScript = task({
     const result = python.stream.runScript("./python/my_script.py", ["hello", "world"]);
 
     // result is an async iterable/readable stream
-    for await (const chunk of streamingResult) {
+    for await (const chunk of result) {
       console.log(chunk);
     }
   },

package/docs/config/extensions/syncEnvVars.mdx

@@ -31,6 +31,9 @@ The callback is passed a context object with the following properties:
 - `environment`: The environment name that the task is being deployed to (e.g. `production`, `staging`, etc.)
 - `projectRef`: The project ref of the Trigger.dev project
 - `env`: The environment variables that are currently set in the Trigger.dev project
+- `branch`: The preview branch name, if deploying to a preview branch (optional)
+
+`syncEnvVars` also accepts a second argument with an `override` option (defaults to `true`). When `true`, synced variables overwrite variables with the same name that are already set in the environment you're deploying to. Set it to `false` to only sync variables that aren't set there yet.
 
 ### Marking variables as secrets
 
@@ -168,12 +171,15 @@ export default defineConfig({
         projectId: "your-vercel-project-id",
         vercelAccessToken: "your-vercel-access-token", // optional, we recommend to keep it as env variable
         vercelTeamId: "your-vercel-team-id", // optional
+        branch: "your-preview-branch", // optional
       }),
     ],
   },
 });
 ```
 
+The `branch` option filters branch-specific Vercel variables for preview branches. It defaults to the `VERCEL_PREVIEW_BRANCH` environment variable, then the Trigger.dev preview branch. The access token is read from `VERCEL_ACCESS_TOKEN`, falling back to `VERCEL_TOKEN`.
+
 ### syncNeonEnvVars
 
 The `syncNeonEnvVars` build extension syncs environment variables from your Neon database project to Trigger.dev. It automatically detects branches and builds the appropriate database connection strings for your environment.

package/docs/deploy-environment-variables.mdx

@@ -3,6 +3,8 @@ title: "Environment Variables"
 description: "Any environment variables used in your tasks need to be added so the deployed code will run successfully."
 ---
 
+import { RollingOut } from "/snippets/feature-status.jsx";
+
 An environment variable in Node.js is accessed in your code using `process.env.MY_ENV_VAR`.
 
 We deploy your tasks and scale them up and down when they are triggered. So any environment variables you use in your tasks need to accessible to us so your code will run successfully.
@@ -14,7 +16,7 @@ We deploy your tasks and scale them up and down when they are triggered. So any
 <Steps>
 
 <Step title="Go to the Environment Variables page">
-  In the sidebar select the "Environment Variables" page, then press the "New environment variable"
+  In the sidebar select the "Environment Variables" page, then press the "Add new"
   button. ![Environment variables page](/images/environment-variables-page.jpg)
 </Step>
 
@@ -43,6 +45,8 @@ When creating an environment variable, you can mark it as a **Secret**. Secret v
 
 You can edit an environment variable's values. You cannot edit the key name, you must delete and create a new one.
 
+<RollingOut flag="allowEmptyEnvironmentVariableValues" />
+
 <Note>
   An empty string is a valid value. Saving a variable with an empty value stores it as an empty
   string (your task sees the variable set to `""`), which is different from deleting the variable

package/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.
@@ -443,6 +443,8 @@ If you use the [Vercel integration](/vercel-integration), version skew protectio
 
 This covers production, staging and preview alike.
 
+In production, the integration also gates the release on the task build. Each production deployment from your production branch carries a blocking **Trigger.dev Build** check, so a commit whose tasks fail to build never goes live and its runs never wait on a deployment that won't arrive. Re-run the **Trigger.dev deployment** check in GitHub to build that commit again. See [Production waits for your tasks](/vercel-integration#production-waits-for-your-tasks).
+
 ### Opting out
 
 Set `TRIGGER_AUTOMATIC_SKEW_VERSION_PROTECTION` to `0` on your Vercel project. A `0` you set today stays `0` through every subsequent build.

package/docs/deployment/dev-branches.mdx

@@ -59,7 +59,7 @@ You can also set the branch with the `TRIGGER_DEV_BRANCH` environment variable i
 
 ## Archive a branch
 
-Archive a branch from the CLI when you no longer need it. The CLI detects your local git branch, or you can name one with `--branch`:
+Archive a branch from the CLI when you no longer need it. Pass the branch with `--branch` (or set `TRIGGER_DEV_BRANCH`); it's required, and the `default` branch can't be archived:
 
 <CodeGroup>
 
@@ -81,12 +81,12 @@ You can also create and archive branches from the **Dev branches** page in the d
 
 ## Limits on active branches
 
-Each branch has its own concurrency, so we limit how many can be active per project. Archive a branch at any time to unlock another slot.
+Each branch has its own concurrency, so we limit how many dev branches each developer can have active per project. The `default` development environment counts toward this limit. If you are at the limit when you run `dev --branch`, the CLI automatically archives up to 3 of your branches that have no connected dev session and have been idle for over an hour, to make room. You can also archive a branch any time to free a slot.
 
 | Plan  | Active dev branches |
 | ----- | ------------------- |
-| Free  | 25                  |
-| Hobby | 25                  |
-| Pro   | 25                  |
+| Free  | 50                  |
+| Hobby | 50                  |
+| Pro   | 50                  |
 
 Need more? [Get in touch](https://trigger.dev/contact) and we'll raise the limit.

package/docs/deployment/overview.mdx

@@ -6,7 +6,7 @@ description: "Learn how to deploy your tasks to Trigger.dev."
 
 import CorepackError from "/snippets/corepack-error.mdx";
 
-Before you can run production workloads on Trigger.dev, you need to deploy your tasks. The only way to do this at the moment is through the [deploy CLI command](/cli-deploy-commands):
+Before you can run production workloads on Trigger.dev, you need to deploy your tasks. The manual way to do this is the [deploy CLI command](/cli-deploy-commands). You can also deploy automatically with the [GitHub integration](/github-integration) or the [Vercel integration](/vercel-integration):
 
 <CodeGroup>
 
@@ -100,8 +100,9 @@ When you deploy, the version number is automatically incremented, and the new ve
 The current version defines which version of the code new task runs will execute against. When a task run starts, it is locked to the current version. This ensures that the task run is not affected by changes to the code. Retries of the task run will also be locked to the original version.
 
 <Note>
-  When you Replay a run in the dashboard we will create a new run, locked to the current version and
-  not necessarily the version of the original run.
+  When you Replay a run in the dashboard we create a new run that uses the current version by default
+  (in deployed environments you can pick a specific version in the replay dialog), not necessarily
+  the version of the original run.
 </Note>
 
 ### Version locking
@@ -161,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
@@ -186,10 +187,10 @@ For additional environments beyond `prod` and `staging`, you can use [preview br
 
 ## Local builds
 
-By default we use a remote build provider to speed up builds. However, you can also force the build to happen locally on your machine using the `--force-local-build` flag:
+By default we use a remote build provider to speed up builds. However, you can also force the build to happen locally on your machine using the `--local-build` flag:
 
 ```bash
-npx trigger.dev deploy --force-local-build
+npx trigger.dev deploy --local-build
 ```
 
 <Tip>
@@ -205,7 +206,7 @@ To use local builds, you need the following tools installed on your machine:
 
 ## Environment variables
 
-To add custom environment variables to your deployed tasks, you need to add them to your project in the Trigger.dev dashboard, or automatically sync them using our [syncEnvVars](/config/config-file#syncenvvars) or [syncVercelEnvVars](/config/config-file#syncvercelenvvars) build extensions.
+To add custom environment variables to your deployed tasks, you need to add them to your project in the Trigger.dev dashboard, or automatically sync them using our [syncEnvVars](/config/extensions/syncEnvVars) or [syncVercelEnvVars](/config/extensions/syncEnvVars#syncvercelenvvars) build extensions.
 
 For more information on environment variables, see our [environment variables](/deploy-environment-variables) guide.
 
@@ -235,7 +236,7 @@ You can run the deploy command with `--log-level debug` at the end. This will pr
 
 There should be a link below the error message to the full build logs on your machine. Take a look at these to see what went wrong. Join [our Discord](https://trigger.dev/discord) and you share it privately with us if you can't figure out what's going wrong. Do NOT share these publicly as the verbose logs might reveal private information about your project.
 
-Sometimes these errors are caused by upstream availability issues with our remote build provider. In this case, you can try deploying with a local build using the `--force-local-build` flag. Refer to the [Local builds](#local-builds) section for more information.
+Sometimes these errors are caused by upstream availability issues with our remote build provider. In this case, you can try deploying with a local build using the `--local-build` flag. Refer to the [Local builds](#local-builds) section for more information.
 
 #### `Deployment encountered an error`
 

package/docs/deployment/preview-branches.mdx

@@ -18,10 +18,13 @@ The process to use preview branches looks like this:
 3. Create a named **Trigger only** API key in the Preview environment, then trigger runs using the key (`TRIGGER_SECRET_KEY`) and branch name (`TRIGGER_PREVIEW_BRANCH`).
 4. Archive the preview branch when the branch is done.
 
-There are two main ways to do this:
+There are three main ways to do this:
 
-1. Automatically: using GitHub Actions (recommended).
-2. Manually: in the dashboard and/or using the CLI.
+1. Automatically: using the [GitHub integration](/github-integration), which deploys pull requests to preview branches and archives them when the PR is merged or closed, without a GitHub Action.
+2. Automatically: using GitHub Actions, if you deploy from your own CI workflows.
+3. Manually: in the dashboard and/or using the CLI.
+
+Pick one of the automatic options, not both.
 
 ### Limits on active preview branches
 
@@ -144,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

package/docs/errors-retrying.mdx

@@ -15,8 +15,8 @@ You can configure retrying in two ways:
 <Note>Task-level retry settings override the defaults in your `trigger.config` file.</Note>
 
 <Note>
-  By default when you create your project using the CLI init command we disabled retrying in the DEV
-  environment. You can enable it in your [trigger.config file](/config/config-file).
+  By default when you create your project using the CLI init command, retrying is enabled in the DEV
+  environment. You can disable it by setting `enabledInDev: false` in your [trigger.config file](/config/config-file).
 </Note>
 
 ## A simple example with OpenAI
@@ -112,7 +112,7 @@ import { task, logger, retry } from "@trigger.dev/sdk";
 
 export const taskWithFetchRetries = task({
   id: "task-with-fetch-retries",
-  run: async ({ payload, ctx }) => {
+  run: async (payload: any, { ctx }) => {
     //if the Response is a 429 (too many requests), it will retry using the data from the response. A lot of good APIs send these headers.
     const headersResponse = await retry.fetch("http://my.host/test-headers", {
       retry: {
@@ -182,7 +182,7 @@ export const taskWithFetchRetries = task({
 
 ## Advanced error handling and retrying
 
-We provide a `catchError` callback on the task and in your `trigger.config` file. This gets called when an uncaught error is thrown in your task.
+We provide a `catchError` callback on the task, and you can register one globally with `tasks.catchError()`. This gets called when an uncaught error is thrown in your task.
 
 You can