@trigger.dev/sdk 4.5.16 → 4.6.1

package/docs/ai-chat/transcript-storage.mdx

@@ -0,0 +1,247 @@
+---
+title: "Transcript storage"
+sidebarTitle: "Transcript storage"
+description: "Where a chat.agent conversation is kept: the UIMessages the runtime saves, the platform default, reading history back, and bringing your own database through the TranscriptStorage adapter."
+---
+
+## Why a conversation needs a home
+
+A `chat.agent` conversation outlives a single run. One run answers many turns and survives the idle gaps between them, but a run does end eventually (a version upgrade, its turn limit, a crash), and the next message then boots a fresh run with nothing in memory (see [How it works](/ai-chat/how-it-works)). For that new run to answer in context, the conversation so far has to be read back from somewhere durable. The same store is what a page reload and the dashboard read to show history.
+
+That somewhere is a **transcript storage**. You get one by default with no setup: the platform keeps the conversation as a snapshot in object storage, the same blob the Sessions view in the dashboard renders. Bring your own when you want the conversation in your own database instead.
+
+## What gets saved
+
+The transcript is a list of **`UIMessage`s**, keyed by `chatId`. A `UIMessage` is the rich, renderable message the frontend works with: an `id`, a `role`, and an array of `parts` (text, reasoning, tool calls and their results, and any custom `data-*` parts). It is the same shape your React app holds and the same shape the dashboard renders, so what you store is exactly what a user sees.
+
+<Note>
+`UIMessage`s are not what the model reads. Each turn the runtime derives a `ModelMessage[]` from the transcript, the flattened `{ role, content }` form an LLM takes, and hands it to your `run()` as `messages`. The transcript storage never deals in `ModelMessage`s. It holds the UI messages; the model's view is derived from them.
+</Note>
+
+Keeping the UI shape is deliberate. It is lossless (a tool call and its result survive as parts), it is what renders, and the model's view can be rebuilt from it. Two things cannot be rebuilt from the messages alone, so the runtime hands them to the storage as well:
+
+- **`state`**: an opaque record for what the model saw that the transcript does not capture, a [compaction](/ai-chat/compaction) summary and [injected context](/ai-chat/background-injection). Store it as-is and give it back on load.
+- **cursors**: the stream positions the next run resumes from. Persist them opaquely; a storage never reads them.
+
+So a save is: the messages, a `state` blob, and two cursors. Nothing else.
+
+## The default storage
+
+Do nothing and you get the platform snapshot: the whole conversation written to object storage after each change, read back when a run continues. It is the blob the dashboard's Sessions view renders, and it needs no configuration.
+
+```ts
+import { chat } from "@trigger.dev/sdk/ai";
+import { anthropic } from "@ai-sdk/anthropic";
+
+export const myChat = chat.agent({
+  id: "my-chat",
+  run: async ({ messages, signal, streamText }) =>
+    streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal }),
+});
+```
+
+The default rewrites the whole conversation on every turn. That is fine for most chats and costs one write. When it stops being fine, or when you want the conversation in a database you already run, you bring your own.
+
+## Bring your own storage
+
+Set `storage` on the agent to persist the conversation yourself:
+
+```ts
+import { chat } from "@trigger.dev/sdk/ai";
+import { anthropic } from "@ai-sdk/anthropic";
+import { myTranscriptStorage } from "./transcript-storage";
+
+export const myChat = chat.agent({
+  id: "my-chat",
+  storage: myTranscriptStorage,
+  run: async ({ messages, signal, streamText }) =>
+    streamText({ model: anthropic("claude-sonnet-4-5"), messages, abortSignal: signal }),
+});
+```
+
+Reasons to:
+
+- **Your database is the source of truth.** History lives next to the rest of your data, queryable, backed up, and deletable on your terms.
+- **Cheaper writes on long chats.** A row-per-message store writes only what changed on a turn instead of rewriting the whole conversation.
+- **Render history in one query** from your own tables, the same `load` the runtime uses.
+- **Own the model's context** for branching, trust boundaries, or rollback (see [Owning the model's context](#owning-the-models-context)).
+
+The runtime drives the storage. You never decide when to write, what a regenerate means for your rows, or how a crash mid-answer is recovered. Those decisions are the same for every backend, so they live in the runtime; your job is to store what it hands you and give it back.
+
+## The interface
+
+```ts
+type TranscriptStorage<TClientData = unknown> = {
+  load(
+    scope: { chatId: string; clientData: TClientData },
+    opts?: { limit?: number; before?: string }
+  ): Promise<{
+    messages: UIMessage[];
+    state: unknown | null;
+    cursors?: { lastOutEventId?: string; lastInEventId?: string };
+    nextCursor?: string;
+  }>;
+
+  save(
+    ctx: {
+      chatId: string;
+      clientData: TClientData;
+      turn: number;
+      trigger: "submit-message" | "regenerate-message" | "action";
+      runId: string;
+      ctx: TaskRunContext;
+    },
+    changeset: {
+      reason: "turn-start" | "turn-complete" | "turn-error" | "action" | "compaction" | "recovery";
+      changes: TranscriptChange[];
+      transcript: { entries: Array<{ id: string; final: boolean; message: UIMessage }>; state: unknown | null };
+      cursors?: { lastOutEventId?: string; lastInEventId?: string };
+    }
+  ): Promise<void>;
+
+  loadContext?(
+    scope: { chatId: string; clientData: TClientData },
+    event: LoadContextEvent
+  ): Promise<UIMessage[]>;
+};
+
+type TranscriptChange =
+  | { op: "put"; message: UIMessage; final?: boolean }
+  | { op: "remove"; id: string }
+  | { op: "truncateAfter"; afterId: string }
+  | { op: "state"; value: unknown | null };
+```
+
+`load` returns the conversation. `save` records a change to it. `loadContext` is optional and covered [below](#owning-the-models-context). All the types are exported from `@trigger.dev/sdk/ai`.
+
+`scope` is the tenant of a read: the `chatId` and the `clientData` your app passed. `ctx` on a save is the same plus the run it happened in. `clientData` is how the runtime hands you the tenant; use it to scope or authorize where your backend needs to.
+
+## What the runtime hands `save`
+
+A changeset carries the same save two ways, and a storage uses whichever suits its shape.
+
+`changes` is the ordered list of what changed since the last save. A row-per-message store applies them, as one transaction where the backend supports one:
+
+| Change | Meaning |
+| --- | --- |
+| `put` | Upsert by `message.id`. An unknown id appends at the end; a known id is replaced in place. `final` is `false` for a partial answer captured from a turn that failed or was stopped, and `true` otherwise. |
+| `remove` | Delete by id. A no-op for an unknown id. |
+| `truncateAfter` | Drop every message ordered after `afterId`. This is what an undo or a regenerate becomes. A no-op for an unknown id. |
+| `state` | Replace the runtime's opaque record; `null` clears it. |
+
+`transcript` is the whole conversation as it stands after those changes, `entries` plus `state`. A store that keeps the conversation as one document (object storage, a key-value store, a JSON column) writes it as-is and keeps no state of its own between saves. The default storage is exactly that: it serialises `transcript` and rewrites the blob.
+
+The changes are the intent, spelled out. A normal turn is two `put`s, the user's message and the assistant's answer, split across the turn's two saves. A steering message the user sent mid-turn is another `put` in the same changeset. An undo through `chat.history.slice(0, -2)` is one `truncateAfter`. A regenerate is a `truncateAfter` and a `put`. A tool approval that updates the assistant message in place is one `put` for that id. Messages are addressed by id; how you order rows is your concern.
+
+Every turn saves twice. The `turn-start` save carries the message being answered, before the model runs. The `turn-complete` save carries the answer. Both `put` the same user message id, and a `put` upserts, so a storage that applies changes in order needs no special handling for the repeat.
+
+The `turn-start` save is what makes a reload during an answer show the question that is being answered. It leaves `cursors` on the previous turn's position, because the answer's own cursor does not exist yet, so a reload mid-answer still resumes from the last completed turn rather than skipping chunks it never received.
+
+A few properties worth knowing:
+
+- The `turn-start` save runs alongside the model rather than before it, so it costs no time to first token. Nothing from the turn reaches the browser until it settles, which is what makes the question durable before the answer can render. A save that fails or runs long lets the answer through rather than stalling the conversation.
+- The `turn-complete` save happens after the turn's answer has reached the browser, so it never delays the response. The runtime awaits each `save` before the run suspends.
+- A `save` that throws is logged and the turn continues. The changes fold into the next changeset, and every change is idempotent, so a retried changeset converges on the same result.
+- A `load` that throws boots the run from the durable stream's recent tail rather than failing.
+
+## Reading the transcript
+
+`load` is the one read for every backend, the default included. Call it on your server, scoped to the signed-in user through `clientData`, and pass the result to the browser:
+
+```ts app/actions.ts
+"use server";
+import { chat, defaultStorage } from "@trigger.dev/sdk/ai";
+
+export const loadTranscript = chat.createLoadTranscriptAction(defaultStorage, { limit: 50 });
+```
+
+```tsx app/chat/[chatId]/ChatPage.tsx
+"use client";
+import { useLoadTranscript, useTriggerChatTransport } from "@trigger.dev/sdk/chat/react";
+import { loadTranscript } from "@/app/actions";
+
+export function ChatPage({ chatId }: { chatId: string }) {
+  const transport = useTriggerChatTransport({ task: "my-chat", accessToken, startSession });
+  const { messages, isLoading, nextCursor } = useLoadTranscript(chatId, loadTranscript, {
+    transport,
+  });
+  if (isLoading) return <Spinner />;
+  return <ChatView chatId={chatId} initialMessages={messages} transport={transport} />;
+}
+```
+
+<Warning>
+The action receives `chatId` from the browser, so authorize it before returning: check that the signed-in user owns this chat. `defaultStorage` loads purely by `chatId` and does no tenant check of its own, so an exported action with no authorization lets any authenticated user read any chat's transcript. A custom storage can enforce tenancy inside `load` using `clientData`, but the server action is still the place to reject a `chatId` the caller may not read.
+</Warning>
+
+`limit` returns the most recent messages and a `nextCursor`; pass it as `before` for the page before that one. With the default storage, a paged read is served by the platform, so a long conversation is not downloaded in full to render its last fifty messages. A paged read returns the transcript only: `state` is always `null`, because the model lane is not part of what a page renders, and the platform reads just the bytes holding that page rather than the whole conversation. The runtime reads the state separately when it restores context at boot. When you pass `transport` and it already knows the session, the hook seeds its resume cursor from the transcript, so the live subscription opens just past the persisted history instead of replaying it.
+
+Swap `defaultStorage` for your own storage and nothing else about the read changes.
+
+<Warning>
+The saved format changed in this release, and an older SDK cannot read it. Rolling a deployment back to a version from before this release means its runs will not find a readable transcript for conversations already saved by the newer one, and will continue from the live stream tail instead, so earlier history is lost for those conversations. Roll forward rather than back, or keep your own transcript storage.
+</Warning>
+
+The default storage is deliberately basic about long conversations. Once compaction has run, it keeps roughly the last hundred messages and drops the rest, so what it rewrites on each save stops growing. A conversation that never compacts is kept whole. If your app renders history further back than that, give the agent your own storage and keep the messages yourself.
+
+## Owning the model's context
+
+By default the model's context each turn is the transcript the runtime accumulated, converted to `ModelMessage`s. A storage that declares `loadContext` takes that over: the runtime calls it on every turn and action, with the messages the frontend sent and the transcript the runtime had, and uses the `UIMessage`s it returns as the conversation (converting them to `ModelMessage`s the same way). Reach for it when your database decides what the model sees, for branching conversations, a trust boundary where the browser's history is not to be believed, or a curated context window.
+
+```ts
+const storage: TranscriptStorage<{ userId: string }> = {
+  load: (scope, opts) => rows.load(scope, opts),
+  save: (ctx, changeset) => rows.save(ctx, changeset),
+  loadContext: async ({ chatId, clientData }, { incomingMessages }) => {
+    const branch = await rows.activeBranch(chatId, clientData.userId);
+    return [...branch, ...incomingMessages];
+  },
+};
+```
+
+`save` keeps receiving every change, and crash recovery keeps running. This is the replacement for the deprecated [`hydrateMessages`](/ai-chat/lifecycle-hooks#hydratemessages) hook; setting both `hydrateMessages` and `storage` on an agent is a startup error.
+
+## Writing your own storage
+
+The contract is small and the conformance suite checks it. Point the suite at a factory for your storage and run it under vitest or jest:
+
+```ts transcript-storage.test.ts
+import { runTranscriptStorageTests } from "@trigger.dev/sdk/ai/test";
+import { postgresTranscriptStorage } from "./transcript-storage";
+
+runTranscriptStorageTests(() => postgresTranscriptStorage(process.env.TEST_DATABASE_URL!));
+```
+
+The suite covers appends and in-place replacement, idempotent `remove` and `truncateAfter`, `state` round-trips, cursors, replaying the same changeset twice, paging, and chat isolation. `memoryTranscriptStorage()` is the reference implementation, and it is handy in your own tests to see exactly what the runtime hands a storage.
+
+A few things to get right:
+
+- Pick one view and stay with it. Apply `changes` if you store rows, write `transcript` if you store a document; don't mix them within one save.
+- `put` for a known id replaces the message in place; position and ordering don't change.
+- Order is the message's position in the transcript. A document store gets it from `transcript.entries`. A row store needs an order column set once, when a `put` first inserts an id, following the order the `put`s arrive in, and left unchanged when a later `put` replaces that id in place. Don't sort by a write timestamp: a replaced message has to keep its place, and a steering message sent mid-turn sorts before the answer it shaped even though its row is written later.
+- `truncateAfter` and `remove` are idempotent. Applying a changeset twice gives the same result as applying it once.
+- `load` with no options returns the whole conversation in order. With `limit`, return the most recent messages and a `nextCursor` (the id of the oldest returned message) when earlier messages exist.
+- Scope reads and writes by `clientData` where your backend enforces tenancy.
+
+## Guarantees and limits
+
+- Crash recovery of a half-written answer is runtime-owned in every configuration. It comes from the durable session stream, which no application database can reconstruct. A storage holds settled turns; the runtime overlays the recovered tail and hands it to `save` like any other change.
+- Bringing your own database does not remove platform custody. Session streams still hold message content for their retention window.
+- The default storage rewrites the whole conversation each turn. A row-per-message storage writes only what changed. That is the reason to plug in your own.
+
+## Migrating from hydrateMessages
+
+`hydrateMessages` keeps working with a one-time deprecation warning. Crash recovery runs for it, but the runtime does not write to your store on its behalf. The move, in short:
+
+1. Implement `TranscriptStorage` over your existing tables. The writes you did in hooks become `save`; the read your hook did becomes `load`. Add `loadContext` only if your database decides what the model sees each turn.
+2. Set `storage` on the agent and remove `hydrateMessages`. Setting both is an error.
+3. Delete the recovery, compaction and cursor code the runtime now owns, and run `runTranscriptStorageTests` against your implementation.
+
+The [migration guide](/ai-chat/migrating-from-hydrate-messages) walks through each step with code, and lists what to delete from each hook.
+
+## See also
+
+- [Persistence and replay](/ai-chat/patterns/persistence-and-replay): how the runtime rebuilds a conversation when a new run boots
+- [Database persistence](/ai-chat/patterns/database-persistence): the hook-based pattern and how it relates
+- [Actions](/ai-chat/actions#actions-and-persistence): what an undo or regenerate becomes in the changeset
+- [Compaction](/ai-chat/compaction): the summary the runtime keeps in `state`

package/docs/ai-chat/upgrade-guide.mdx

@@ -298,8 +298,8 @@ and direct API consumers.
   fire at the same lifecycle points.
 - `onAction` is still defined the same way, but its semantics changed
   in the [May 6 prerelease](/ai-chat/changelog) — actions are no longer
-  turns, and `onAction` returning a `StreamTextResult` produces a model
-  response.
+  turns. To answer after an action's edit, return `chat.turn()`; returning
+  a `StreamTextResult` is no longer supported.
 - `chat.customAgent({...})` and the `chat.createSession(payload, ...)`
   helper for building a session loop manually inside a custom agent.
 - `chat.defer` (deferred work) and `chat.history` (imperative history

package/docs/apikeys.mdx

@@ -10,17 +10,35 @@ description: "Authenticate backend requests with environment-specific API keys."
   environment variable, never commit them to source control, and never expose them in frontend code.
 </Warning>
 
-## Find your API keys
+## Create an API key
 
-Open your project in the dashboard, select an environment, and open the [**API keys**](https://cloud.trigger.dev/_/apikeys) page.
+Create a separate named key for each service or integration that accesses Trigger.dev.
 
-API keys belong to one environment. A Development key cannot access Production, and a Production key cannot access Staging.
+API keys belong to one environment. A Development key cannot access Production, and a Production key cannot access Staging. Every team member has their own Development environment, so create local-development keys in your own environment.
 
 <Note>
-  Every team member has their own Development environment and keys. Copy the Development key from
-  your own API keys page so local requests run against your machine.
+  Creating and revoking keys requires permission to manage API keys for the selected environment.
+  The dashboard disables these actions when your role does not have permission.
 </Note>
 
+<Steps titleSize="h3">
+  <Step title="Open the API keys page">
+    Select the project and environment the integration needs to access, then open [**API keys**](https://cloud.trigger.dev/_/apikeys).
+  </Step>
+  <Step title="Create the key">
+    Click **New API key**, enter a descriptive name, and optionally set an expiration date. Names can
+    contain up to 64 characters.
+  </Step>
+  <Step title="Choose its access">
+    Select the narrowest access preset that supports the integration. For task-aware presets, choose
+    all tasks or up to 10 task identifiers.
+  </Step>
+  <Step title="Copy and store the secret">
+    Copy the key into your secret manager or backend environment. Trigger.dev shows the complete
+    value only once.
+  </Step>
+</Steps>
+
 ## Configure the SDK
 
 Set `TRIGGER_SECRET_KEY` in your backend environment. The SDK reads it automatically for operations such as triggering tasks and retrieving runs.
@@ -49,38 +67,12 @@ await tasks.trigger<typeof sendEmail>("send-email", {
 If you self-host Trigger.dev, set `TRIGGER_API_URL` or pass `baseURL` to `configure`:
 
 ```bash .env
-TRIGGER_SECRET_KEY="tr_prod_…"
+TRIGGER_SECRET_KEY="tr_prod_sk_…"
 TRIGGER_API_URL="https://trigger.example.com"
 ```
 
 The default API URL is `https://api.trigger.dev`.
 
-## Create a key
-
-Create a separate key for each service or integration that accesses Trigger.dev.
-
-<Note>
-  Creating and revoking keys requires permission to manage API keys for the selected environment.
-  The dashboard disables these actions when your role does not have permission.
-</Note>
-
-<Steps titleSize="h3">
-  <Step title="Open the API keys page">
-    Select the project and environment the integration needs to access, then open [**API keys**](https://cloud.trigger.dev/_/apikeys).
-  </Step>
-  <Step title="Create the key">
-    Click **New API key**, enter a descriptive name, and optionally set an expiration date. Names can
-    contain up to 64 characters.
-  </Step>
-  <Step title="Choose its access">
-    Select an access preset. For task-aware presets, choose all tasks or up to 10 task identifiers.
-  </Step>
-  <Step title="Copy and store the secret">
-    Copy the key into your secret manager or backend environment. Trigger.dev shows the complete
-    value only once.
-  </Step>
-</Steps>
-
 ## Access presets
 
 Access presets define what a key can do. Some presets require a paid plan. The dashboard shows which presets your organization can use — see [pricing](https://trigger.dev/pricing).
@@ -124,28 +116,18 @@ Revoking a key takes effect immediately and cannot be reversed. Requests using t
 
 Removing a team member does not revoke keys they created. Review and revoke their keys separately when their access changes.
 
-## Root keys
-
-<Warning>
-  Root keys are legacy, and are likely to be deprecated in the future. We recommend against using them.
-</Warning>
-
-Each environment has a single legacy root key. It can be regenerated, which creates a new value immediately. The previous root key remains valid for 24 hours so you can update services without downtime, then stops authenticating.
-
-Public access tokens signed with the previous root key remain valid until the earlier of their own expiration and the end of the 24-hour grace period.
-
 ## Create public access tokens
 
 API keys can be used to create scoped [Public Access Tokens](/realtime/auth) using `auth.createPublicToken()`.
 
-To do so with the newer non-root keys, you must use `@trigger.dev/sdk` version 4.5.8 or later. Creating public tokens with non-root keys has the following restrictions:
+Use `@trigger.dev/sdk` version 4.5.8 or later to create public tokens with environment API keys. Public tokens have the following restrictions:
 
 - The token must request at least one scope.
 - Its scopes cannot exceed the key's access.
 - Its expiration cannot exceed 30 days.
 
 <Note>
-Revoking or expiring an API key does not revoke tokens it already created. Those tokens remain valid until their own expiration, unless the environment's root key is regenerated.
+Revoking or expiring an API key does not revoke tokens it already created. Those tokens remain valid until their own expiration.
 </Note>
 
 ## Target Preview and Development branches
@@ -163,7 +145,7 @@ The SDK sends the branch automatically. When calling the API directly, send the
 
 Self-hosted installations support multiple keys with **No restrictions**. The restricted access presets are available in Trigger.dev Cloud.
 
-Keep your instance and SDK current before creating keys. Calling a public-token API with a key on a server that does not support server-minted tokens returns an upgrade error; use the root key until the server is upgraded.
+Keep your instance and SDK current before creating keys. Calling a public-token API with a key on a server that does not support server-minted tokens returns an upgrade error. Upgrade the instance before creating public tokens with an environment API key.
 
 ## Security recommendations
 

package/docs/cli-env-commands.mdx

@@ -0,0 +1,114 @@
+---
+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";
+import BranchOptions from "/snippets/cli-options-branch.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`. Fails if the file already exists unless you pass `--force`.
+
+```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.
+</ParamField>
+
+## Options
+
+<ParamField body="Environment" type="--env | -e">
+  The environment to use: `prod`, `staging` or `preview`. Defaults to `prod`.
+</ParamField>
+
+<ConfigFileOptions />
+<ProjectRefOptions />
+<BranchOptions />
+
+### Common options
+
+These options are available on most commands.
+
+<CommonOptions />

package/docs/cli-projects-commands.mdx

@@ -0,0 +1,62 @@
+---
+title: "CLI projects commands"
+sidebarTitle: "projects"
+description: "Create, inspect, and rename Trigger.dev projects from the terminal."
+---
+
+import CommonOptions from "/snippets/cli-options-common.mdx";
+
+These commands act on the organizations and projects your account can access, so run
+[`login`](/cli-login-commands) first.
+
+## projects create
+
+Creates a project. You are prompted for the organization and name when the options are omitted.
+
+<CodeGroup>
+
+```bash npm
+npx trigger.dev@latest projects create
+```
+
+```bash pnpm
+pnpm dlx trigger.dev@latest projects create
+```
+
+```bash yarn
+yarn dlx trigger.dev@latest projects create
+```
+
+</CodeGroup>
+
+<ParamField body="Organization" type="--org | -o">
+  The organization slug or ID to create the project in.
+</ParamField>
+
+<ParamField body="Name" type="--name | -n">
+  The name of the new project.
+</ParamField>
+
+## projects get
+
+Prints the name, ref, slug, organization, default runtime and region of a project.
+
+```bash
+npx trigger.dev@latest projects get proj_abc123
+```
+
+## projects rename
+
+Renames a project. The project ref does not change.
+
+```bash
+npx trigger.dev@latest projects rename proj_abc123 "My new name"
+```
+
+## Options
+
+### Common options
+
+These options are available on most commands.
+
+<CommonOptions />

package/docs/cli-runs-commands.mdx

@@ -0,0 +1,94 @@
+---
+title: "CLI runs commands"
+sidebarTitle: "runs"
+description: "Use these commands to list, inspect, replay and cancel runs 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";
+import BranchOptions from "/snippets/cli-options-branch.mdx";
+
+## runs list
+
+Lists runs, newest first, in a table of ID, task, status, version, created time and duration.
+
+<CodeGroup>
+
+```bash npm
+npx trigger.dev@latest runs list
+```
+
+```bash pnpm
+pnpm dlx trigger.dev@latest runs list
+```
+
+```bash yarn
+yarn dlx trigger.dev@latest runs list
+```
+
+</CodeGroup>
+
+<ParamField body="Limit" type="--limit">
+  The number of runs to list, up to 100. Defaults to 20.
+</ParamField>
+
+<ParamField body="Status" type="--status">
+  Only show runs with this status, e.g. `FAILED`.
+</ParamField>
+
+<ParamField body="Task" type="--task">
+  Only show runs for this task identifier.
+</ParamField>
+
+<ParamField body="Tag" type="--tag">
+  Only show runs with this tag.
+</ParamField>
+
+<ParamField body="Cursor" type="--cursor">
+  The pagination cursor printed at the end of the previous page.
+</ParamField>
+
+## runs get
+
+Prints the status, version, tags, timings, duration, cost and error of a single run.
+
+```bash
+npx trigger.dev@latest runs get run_abc123
+```
+
+## runs replay
+
+Triggers a new run with the same payload as an existing one, using the latest version of the task.
+
+```bash
+npx trigger.dev@latest runs replay run_abc123
+```
+
+## runs cancel
+
+Cancels a run that has not finished yet. You are asked to confirm first.
+
+```bash
+npx trigger.dev@latest runs cancel run_abc123
+```
+
+<ParamField body="Skip confirmation" type="--yes | -y">
+  Cancel without the confirmation prompt. Required in non-interactive environments such as CI.
+</ParamField>
+
+## Options
+
+<ParamField body="Environment" type="--env | -e">
+  The environment to use: `dev`, `prod`, `staging` or `preview`. Defaults to `prod`.
+</ParamField>
+
+<ConfigFileOptions />
+<ProjectRefOptions />
+<BranchOptions />
+
+### Common options
+
+These options are available on most commands.
+
+<CommonOptions />

package/docs/config/extensions/syncEnvVars.mdx

@@ -63,6 +63,12 @@ export default defineConfig({
 
 In this example we're using env vars from [Infisical](https://infisical.com).
 
+<Tip>
+  Infisical also offers a native [Secret Sync](/deploy-environment-variables#infisical-secret-sync)
+  that pushes secrets to Trigger.dev without a build extension or a redeploy. Use `syncEnvVars` when
+  you want to resolve secrets at deploy time in code, or for a service without a native sync.
+</Tip>
+
 ```ts trigger.config.ts
 import { defineConfig } from "@trigger.dev/sdk";
 import { syncEnvVars } from "@trigger.dev/build/extensions/core";