@trigger.dev/sdk 0.0.0-python-preview-20250226140121 → 0.0.0-rc-4-8-0-20261021151928

package/docs/billing-limits.mdx

@@ -0,0 +1,73 @@
+---
+title: "Billing limits and alerts"
+sidebarTitle: "Billing limits & alerts"
+description: "Set a monthly compute spend cap for your organization and get email alerts before you reach it."
+---
+
+Billing limits let you cap your organization's monthly compute spend so a runaway task or unexpected traffic spike can't blow your budget. Billing alerts notify you by email as you approach thresholds you choose.
+
+<Note>Billing limits and alerts are available to all [Trigger.dev Cloud](https://trigger.dev) organizations. They don't apply to self-hosted instances.</Note>
+
+You can find the settings in the dashboard: open the **Organization** menu in the top left, then **Settings** → **Billing limits**.
+
+<picture>
+  <source srcSet="/images/billing-docs.webp" type="image/webp" />
+  <img src="/images/billing-docs.png" alt="Billing limit settings" />
+</picture>
+
+## Setting a billing limit
+
+Choose one of three options:
+
+- **Plan limit**: Use your plan's maximum as the spending cap.
+- **Custom limit**: Set your own monthly spend threshold.
+- **No limit**: No cap is enforced. This is the default.
+
+A billing limit applies to your whole organization and covers billable environments: `production`, `staging`, and `preview`. Your `dev` environment is not affected.
+
+Optionally, enable **Cancel in-progress runs when this limit is reached** to immediately cancel executing runs when the limit is hit, instead of letting them finish naturally.
+
+## Billing alerts
+
+Billing alerts are email notifications sent when your monthly spend crosses a threshold. You can add multiple thresholds:
+
+- **With a billing limit set**: thresholds are percentages of your limit (e.g. 50%, 80%).
+- **Without a billing limit**: thresholds are dollar amounts.
+
+<picture>
+  <source srcSet="/images/billing-alerts-docs.webp" type="image/webp" />
+  <img src="/images/billing-alerts-docs.png" alt="Billing alerts settings" />
+</picture>
+
+Alerts only notify you — they never pause environments or reject runs. Use them on their own for visibility, or alongside a limit to get advance warning before enforcement kicks in.
+
+## What happens when you reach your limit
+
+When your organization's spend reaches the billing limit, billable environments enter a **grace period**:
+
+1. Queues pause across `production`, `staging`, and `preview`. In-progress runs finish naturally (unless you enabled **Cancel in-progress runs**).
+2. New runs can still be triggered and are queued, but they won't start executing. Queued runs incur no compute cost until they start.
+3. You have **24 hours** to review and decide what to do.
+
+If you don't act before the grace period ends, new triggers are rejected until you increase or remove the limit (limits also reset at the start of each billing cycle). Queued runs stay queued until you resolve the limit and choose to resume or cancel them. If the limit is still in place when a new billing cycle starts, queued runs resume automatically. Runs that have a TTL still expire if they stay queued past it.
+
+<Note>
+  Billing limits are **soft limits**, not instantaneous hard caps. Usage is evaluated on a short
+  delay, so spend can briefly exceed your limit before enforcement applies. See our
+  [terms](https://trigger.dev/terms) for refund policy details.
+</Note>
+
+## Resuming after hitting a limit
+
+To resume execution, increase or remove the billing limit from the **Billing limits** page. You'll be asked what to do with the runs that queued up during the pause:
+
+- **Resume queued runs**: everything that built up during the pause runs in order.
+- **Cancel queued runs**: the backlog is discarded and only new triggers run going forward.
+
+Execution resumes automatically once you've resolved the limit. Limits also reset at the start of each billing cycle.
+
+## Tracking spend against your limit
+
+On the **Usage** page (Organization menu → **Usage**), a **Billing limit** marker appears on the usage bar alongside your current spend and plan included usage, so you can see how close you are at a glance.
+
+For tips on lowering your spend in the first place, see [How to reduce your spend](/how-to-reduce-your-spend).

package/docs/building-with-ai.mdx

@@ -0,0 +1,261 @@
+---
+title: "Building with AI: overview"
+sidebarTitle: "Overview"
+description: "Tools and resources for building Trigger.dev projects with AI coding assistants."
+---
+
+## Quick setup
+
+We provide multiple tools to help AI coding assistants write correct Trigger.dev code. Use one or all of them for the best developer experience.
+
+
+<Steps>
+
+<Step title="Install the MCP Server">
+  Give your AI assistant direct access to Trigger.dev tools — search docs, trigger tasks, deploy projects, and monitor runs. Works with Claude Code, Cursor, Windsurf, VS Code (Copilot), and Zed.
+
+  ```bash
+  npx trigger.dev@latest install-mcp
+  ```
+
+  [Learn more →](/mcp-introduction)
+</Step>
+
+<Step title="Install Skills">
+  Portable instruction sets that teach any AI coding assistant Trigger.dev best practices: writing tasks, realtime frontends, and `chat.agent` AI agents. They install with the CLI into Claude Code, Cursor, VS Code (Copilot), and AGENTS-compatible tools such as Codex via `.agents/skills/`, and draw their API guidance from a version-pinned reference shipped in `@trigger.dev/sdk`.
+
+  ```bash
+  npx trigger.dev@latest skills
+  ```
+
+  [Learn more →](/skills)
+</Step>
+
+</Steps>
+
+## Skills and the MCP server
+
+Skills and the MCP server do different jobs and work best together. Here's how they compare:
+
+| | **Skills** | **MCP Server** |
+|:--|:-----------|:---------------|
+| **What it does** | Drops skill files into your project that teach Trigger.dev patterns | Runs a live server your AI connects to |
+| **Installs to** | `.claude/skills/`, `.cursor/skills/`, `.github/skills/`, `.agents/skills/` | `mcp.json`, `~/.claude.json`, etc. |
+| **Updates** | Re-run `npx trigger.dev@latest skills`, or auto-prompted on `trigger dev` | Always latest (uses `@latest`) |
+| **Best for** | Teaching patterns and best practices | Live project interaction (deploy, trigger, monitor) |
+| **Works offline** | Yes | No (calls Trigger.dev API) |
+
+**Our recommendation:** Install both. Skills teach your AI *how* to write Trigger.dev code; the MCP Server lets it *do things* in your project.
+
+## Project-level context snippet
+
+If you prefer a lightweight/passive approach, paste the snippet below into a context file at the root of your project. Different AI tools read different files:
+
+| File | Read by |
+|:-----|:--------|
+| `CLAUDE.md` | Claude Code |
+| `AGENTS.md` | OpenAI Codex, Jules, OpenCode |
+| `.cursor/rules/*.md` | Cursor |
+| `.github/copilot-instructions.md` | GitHub Copilot |
+| `CONVENTIONS.md` | Windsurf, Cline, and others |
+
+Create the file that matches your AI tool (or multiple files if your team uses different tools) and paste the snippet below. This gives the AI essential Trigger.dev context without installing anything.
+
+<Accordion title="Copy the snippet">
+
+````markdown
+# Trigger.dev rules
+
+## Imports
+
+Always import from `@trigger.dev/sdk` — never from `@trigger.dev/sdk/v3` or use the deprecated `client.defineJob` pattern.
+
+## Task pattern
+
+Every task must be exported. Use `task()` from `@trigger.dev/sdk`:
+
+```ts
+import { task } from "@trigger.dev/sdk";
+
+export const myTask = task({
+  id: "my-task",
+  retry: {
+    maxAttempts: 3,
+    factor: 1.8,
+    minTimeoutInMs: 500,
+    maxTimeoutInMs: 30_000,
+  },
+  run: async (payload: { url: string }) => {
+    // No timeouts — runs can take as long as needed
+    return { success: true };
+  },
+});
+```
+
+## Triggering tasks
+
+From your backend (Next.js route, Express handler, etc.):
+
+```ts
+import type { myTask } from "./trigger/my-task";
+import { tasks } from "@trigger.dev/sdk";
+
+// Fire and forget
+const handle = await tasks.trigger<typeof myTask>("my-task", { url: "https://example.com" });
+
+// Batch trigger (up to 1,000 items)
+const batchHandle = await tasks.batchTrigger<typeof myTask>("my-task", [
+  { payload: { url: "https://example.com/1" } },
+  { payload: { url: "https://example.com/2" } },
+]);
+```
+
+### From inside other tasks
+
+```ts
+export const parentTask = task({
+  id: "parent-task",
+  run: async (payload) => {
+    // Fire and forget
+    await childTask.trigger({ data: "value" });
+
+    // Wait for result — returns a Result object, NOT the output directly
+    const result = await childTask.triggerAndWait({ data: "value" });
+    if (result.ok) {
+      console.log(result.output); // The actual return value
+    } else {
+      console.error(result.error);
+    }
+
+    // Or use .unwrap() to get output directly (throws on failure)
+    const output = await childTask.triggerAndWait({ data: "value" }).unwrap();
+  },
+});
+```
+
+> Never wrap `triggerAndWait` or `batchTriggerAndWait` in `Promise.all` — this is not supported.
+
+## Error handling
+
+```ts
+import { task, retry, AbortTaskRunError } from "@trigger.dev/sdk";
+
+export const resilientTask = task({
+  id: "resilient-task",
+  retry: { maxAttempts: 5 },
+  run: async (payload) => {
+    // Permanent error — skip retrying
+    if (!payload.isValid) {
+      throw new AbortTaskRunError("Invalid payload, will not retry");
+    }
+
+    // Retry a specific block (not the whole task)
+    const data = await retry.onThrow(
+      async () => await fetchExternalApi(payload),
+      { maxAttempts: 3 }
+    );
+
+    return data;
+  },
+});
+```
+
+## Schema validation
+
+Use `schemaTask` with Zod for payload validation:
+
+```ts
+import { schemaTask } from "@trigger.dev/sdk";
+import { z } from "zod";
+
+export const processVideo = schemaTask({
+  id: "process-video",
+  schema: z.object({ videoUrl: z.string().url() }),
+  run: async (payload) => {
+    // payload is typed and validated
+  },
+});
+```
+
+## Waits
+
+Use `wait.for` for delays, `wait.until` for dates, and `wait.forToken` for external callbacks:
+
+```ts
+import { wait } from "@trigger.dev/sdk";
+await wait.for({ seconds: 30 });
+await wait.until({ date: new Date("2025-01-01") });
+```
+
+## Configuration
+
+`trigger.config.ts` lives at the project root:
+
+```ts
+import { defineConfig } from "@trigger.dev/sdk/build";
+
+export default defineConfig({
+  project: "<your-project-ref>",
+  dirs: ["./trigger"],
+});
+```
+
+## Common mistakes
+
+1. **Forgetting to export tasks** — every task must be a named export
+2. **Importing from `@trigger.dev/sdk/v3`** — this is the old v3 path; always use `@trigger.dev/sdk`
+3. **Using `client.defineJob()`** — this is the deprecated v2 API
+4. **Calling `task.trigger()` directly** — use `tasks.trigger<typeof myTask>("task-id", payload)` from your backend
+5. **Using `triggerAndWait` result as output** — it returns a `Result` object; check `result.ok` then access `result.output`, or use `.unwrap()`
+6. **Wrapping waits/triggerAndWait in `Promise.all`** — not supported in Trigger.dev tasks
+7. **Adding timeouts to tasks** — tasks have no built-in timeout; use `maxDuration` in config if needed
+````
+
+</Accordion>
+
+## llms.txt
+
+We also publish machine-readable documentation for LLM consumption:
+
+- [trigger.dev/docs/llms.txt](https://trigger.dev/docs/llms.txt) — concise overview
+- [trigger.dev/docs/llms-full.txt](https://trigger.dev/docs/llms-full.txt) — full documentation
+
+These follow the [llms.txt standard](https://llmstxt.org) and can be fed directly into any LLM context window.
+
+
+## Troubleshooting
+
+<AccordionGroup>
+
+<Accordion title="AI keeps generating old v2/v3 code">
+  Install [Skills](/skills); they override the outdated patterns in the AI's training data. The [context snippet](#project-level-context-snippet) above is a quick alternative.
+</Accordion>
+
+<Accordion title="MCP server won't connect">
+  1. Make sure you've restarted your AI client after adding the config
+  2. Run `npx trigger.dev@latest install-mcp` again — it will detect and fix common issues
+  3. Check that `npx trigger.dev@latest mcp` runs without errors in your terminal
+  4. See the [MCP introduction](/mcp-introduction) for client-specific config details
+</Accordion>
+
+<Accordion title="Which tool should I install?">
+  Both if possible:
+  - **Skills** to teach your AI how to write Trigger.dev code (tasks, realtime, chat.agent)
+  - **MCP Server** if you need to trigger tasks, deploy, and search docs from your AI
+</Accordion>
+
+</AccordionGroup>
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="MCP Server" icon="sparkles" href="/mcp-introduction">
+    Install and configure the MCP Server for live project interaction.
+  </Card>
+  <Card title="Skills" icon="wand-magic-sparkles" href="/skills">
+    Install Trigger.dev agent skills into any AI coding assistant.
+  </Card>
+  <Card title="Writing tasks" icon="code" href="/tasks/overview">
+    Learn the task patterns your AI assistant will follow.
+  </Card>
+</CardGroup>

package/docs/bulk-actions.mdx

@@ -0,0 +1,77 @@
+---
+title: "Bulk actions in the dashboard"
+sidebarTitle: "Bulk actions"
+description: "Replay or cancel multiple runs from the dashboard using filters or selected run IDs."
+---
+
+**Bulk actions let you replay or cancel multiple runs asynchronously from the dashboard.**
+
+Use bulk actions when you need to retry failed runs after deploying a fix, or stop a group of queued or executing runs.
+
+<Note>
+  For backend code, see [Bulk actions with the SDK](/runs/bulk-actions).
+</Note>
+
+<video
+  src="https://content.trigger.dev/bulk-actions.mp4"
+  preload="auto"
+  controls={true}
+  loop
+  muted
+  autoPlay={true}
+  width="100%"
+  height="100%"
+/>
+
+## Create a bulk action in the dashboard
+
+<Steps>
+  <Step title="Open the bulk action panel">
+    Open the runs page and click **Bulk action** in the top right.
+
+    ![Open the bulk action panel from the runs page](/images/bulk-action-open-panel.png)
+  </Step>
+
+  <Step title="Choose the runs">
+    Filter the runs table to target a group of runs, or select individual runs from the table.
+  </Step>
+
+  <Step title="Configure the action">
+    Choose **Replay** or **Cancel**, add an optional name, then confirm the action.
+
+    ![Configure and create a bulk action](/images/bulk-action-create.png)
+  </Step>
+
+  <Step title="Track progress">
+    Open the bulk action page to see progress, view affected runs, or replay the action.
+
+    ![View bulk action progress](/images/bulk-action-page.png)
+  </Step>
+</Steps>
+
+<Note>
+  You can only cancel runs that are still cancelable, such as queued or executing runs. Runs that have already reached a final state cannot be canceled.
+</Note>
+
+
+## Create a bulk action from the SDK
+
+Use `runs.bulk.replay()` or `runs.bulk.cancel()` when you want to create a bulk action from your backend code.
+
+```ts Your backend code
+import { runs } from "@trigger.dev/sdk";
+
+const action = await runs.bulk.replay({
+  filter: {
+    status: "FAILED",
+    taskIdentifier: "sync-customer",
+    period: "24h",
+  },
+  name: "Replay failed customer syncs",
+});
+
+const completed = await runs.bulk.poll(action.id);
+console.log(completed.status, completed.counts);
+```
+
+See [Bulk actions with the SDK](/runs/bulk-actions) for canceling, listing, polling, and aborting bulk actions from your backend code.

package/docs/changelog.mdx

@@ -0,0 +1,6 @@
+---
+title: "Changelog"
+url: "https://trigger.dev/changelog"
+---
+
+Our [changelog](https://trigger.dev/changelog) is the best way to stay up to date with the latest changes to Trigger.

package/docs/cli-deploy-commands.mdx

@@ -0,0 +1,9 @@
+---
+title: "CLI deploy command"
+sidebarTitle: "deploy"
+description: "Use the deploy command to deploy your tasks to Trigger.dev."
+---
+
+import CliDeployCommands from "/snippets/cli-commands-deploy.mdx";
+
+<CliDeployCommands />

package/docs/cli-dev-commands.mdx

@@ -0,0 +1,9 @@
+---
+title: "CLI dev command"
+sidebarTitle: "dev"
+description: "The `trigger.dev dev` command is used to run your tasks locally."
+---
+
+import CliDevCommands from "/snippets/cli-commands-develop.mdx";
+
+<CliDevCommands />

package/docs/cli-env-commands.mdx

@@ -0,0 +1,115 @@
+---
+title: "CLI env commands"
+sidebarTitle: "env"
+description: "List, get, set, and pull environment variables for a Trigger.dev project."
+---
+
+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";
+
+These commands manage environment variables on a project environment. They default to `prod`. Use `--env staging` or `--env preview` (with `--branch`) for the other environments. There is no `dev` target: local `trigger dev` reads your local `.env`.
+
+<CodeGroup>
+
+```bash npm
+npx trigger.dev@latest env list
+```
+
+```bash pnpm
+pnpm dlx trigger.dev@latest env list
+```
+
+```bash yarn
+yarn dlx trigger.dev@latest env list
+```
+
+</CodeGroup>
+
+## env list
+
+Lists user-set environment variables. `TRIGGER_` system variables are omitted. Values are hidden unless you pass `--show-values`.
+
+```bash
+npx trigger.dev@latest env list
+npx trigger.dev@latest env list --show-values
+```
+
+<ParamField body="Show values" type="--show-values">
+  Print the actual values, including secrets.
+</ParamField>
+
+## env get
+
+Prints one variable. `--raw` prints only the value, with no banner or extra text, so you can capture it in a script.
+
+```bash
+npx trigger.dev@latest env get MY_VAR
+npx trigger.dev@latest env get MY_VAR --raw
+```
+
+<ParamField body="Name" type="<name>">
+  The name of the environment variable.
+</ParamField>
+
+<ParamField body="Raw" type="--raw">
+  Print only the value.
+</ParamField>
+
+## env set
+
+Creates the variable if it does not exist, and overwrites the value if it does. Empty or whitespace-only values are rejected.
+
+Updating an existing secret without `--secret` changes the value and leaves it secret. Pass `--secret` when you first create a secret, or when you want a non-secret variable to become one.
+
+```bash
+npx trigger.dev@latest env set MY_VAR my-value
+npx trigger.dev@latest env set STRIPE_KEY sk_live_abc --secret
+```
+
+<ParamField body="Name" type="<name>">
+  The name of the environment variable.
+</ParamField>
+
+<ParamField body="Value" type="<value>">
+  The value to set. Cannot be empty.
+</ParamField>
+
+<ParamField body="Secret" type="--secret">
+  Store the value as a secret, so it cannot be read back.
+</ParamField>
+
+## env pull
+
+Writes the project's environment variables to a local file. Defaults to `.env.local`. Asks you to confirm before overwriting an existing file unless you pass `--force`. `TRIGGER_` system variables are omitted.
+
+```bash
+npx trigger.dev@latest env pull
+npx trigger.dev@latest env pull --output .env.trigger --force
+```
+
+<ParamField body="Output" type="-o, --output <file>">
+  The file to write. Defaults to `.env.local`.
+</ParamField>
+
+<ParamField body="Force" type="--force">
+  Overwrite the output file if it exists, without asking.
+</ParamField>
+
+## Options
+
+<ParamField body="Environment" type="--env | -e">
+  The environment to use: `prod`, `staging` or `preview`. Defaults to `prod`.
+</ParamField>
+
+<ConfigFileOptions />
+<ProjectRefOptions />
+<ParamField body="Preview branch" type="--branch | -b">
+  Required when using `--env preview`. Specify the branch, e.g. `--branch my-branch` or `-b my-branch`.
+</ParamField>
+
+### Common options
+
+These options are available on most commands.
+
+<CommonOptions />

package/docs/cli-init-commands.mdx

@@ -0,0 +1,84 @@
+---
+title: "CLI init command"
+sidebarTitle: "init"
+description: "Use these options when running the CLI `init` command."
+---
+
+import CommonOptions from '/snippets/cli-options-common.mdx';
+
+Run the command like this:
+
+<CodeGroup>
+
+```bash npm
+npx trigger.dev@latest init
+```
+
+```bash pnpm
+pnpm dlx trigger.dev@latest init
+```
+
+```bash yarn
+yarn dlx trigger.dev@latest init
+```
+
+</CodeGroup>
+
+## Arguments
+
+<ParamField body="Project path" type="[path]">
+  The path to the project. Defaults to `.`.
+</ParamField>
+
+## Options
+
+<ParamField body="Javascript" type="--javascript">
+  By default, the init command assumes you are using TypeScript. Use this flag to initialize a
+  project that uses JavaScript.
+</ParamField>
+
+<ParamField body="Project ref" type="--project-ref | -p">
+  The project ref to use when initializing the project.
+</ParamField>
+
+<ParamField body="Package tag" type="--tag | -t">
+  The version of the `@trigger.dev/sdk` package to install. Defaults to the CLI version.
+</ParamField>
+
+<ParamField body="Skip package install" type="--skip-package-install">
+  Skip installing the `@trigger.dev/sdk` package.
+</ParamField>
+
+<ParamField body="Override config" type="--override-config">
+  Override the existing config file if it exists.
+</ParamField>
+
+<ParamField body="Project name" type="--project-name <name>">
+  The name of the project to create when your account has no projects yet.
+</ParamField>
+
+<ParamField body="Organization name" type="--org-name <name>">
+  The organization to create the first project in. Matches an existing organization by name, or creates it if you have none.
+</ParamField>
+
+<ParamField body="Runtime" type="-r, --runtime <runtime>">
+  The runtime to use: `node`, `node-22`, `node-24`, `node-26` or `bun`. Defaults to `node-24`.
+</ParamField>
+
+<ParamField body="Yes" type="-y, --yes">
+  Skip all prompts. Requires `--project-ref`, or `--project-name` with `--org-name` for a new account.
+</ParamField>
+
+<ParamField body="No browser" type="--no-browser">
+  Do not open the browser during login. Print the URL only.
+</ParamField>
+
+<ParamField body="Package arguments" type="--pkg-args">
+  Additional arguments to pass to the package manager. Accepts CSV for multiple args.
+</ParamField>
+
+### Common options
+
+These options are available on most commands.
+
+<CommonOptions />

package/docs/cli-introduction.mdx

@@ -0,0 +1,25 @@
+---
+title: "Introduction"
+description: "The Trigger.dev CLI has a number of options and commands to help you develop locally, self host, and deploy your tasks."
+---
+
+import HelpOption from '/snippets/cli-options-help.mdx';
+import VersionOption from '/snippets/cli-options-version.mdx';
+
+## Options
+
+<HelpOption />
+<VersionOption />
+
+## Commands
+
+| Command                                      | Description                                                        |
+| :------------------------------------------- | :----------------------------------------------------------------- |
+| [login](/cli-login-commands)                 | Login with Trigger.dev so you can perform authenticated actions.   |
+| [init](/cli-init-commands)                   | Initialize your existing project for development with Trigger.dev. |
+| [dev](/cli-dev-commands)                     | Run your Trigger.dev tasks locally.                                |
+| [deploy](/cli-deploy-commands)               | Deploy your Trigger.dev project to the cloud.                      |
+| [whoami](/cli-whoami-commands)               | Display the current logged in user and project details.            |
+| [logout](/cli-logout-commands)               | Logout of Trigger.dev.                                             |
+| [list-profiles](/cli-list-profiles-commands) | List all of your CLI profiles.                                     |
+| [update](/cli-update-commands)               | Updates all `@trigger.dev/*` packages to match the CLI version.    |