feat(cli): agent-friendly trigger dev output and a tasks trigger command

`trigger dev` works better when a coding agent like Claude Code, Cursor
or Codex runs it. It skips the install prompts, exits with instructions
when your packages don't match the CLI version, lists the tasks it
registered, and prints each run's dashboard URL and output.

For everyone, failed builds now end with a line saying the dev command
will rebuild once you fix the errors and which version runs still use.
Retried attempts and crashed task processes now show their errors, and
build errors no longer contain color codes when the output isn't a
terminal.

New `trigger.dev tasks trigger <task id>` command to trigger a task from
your terminal. It uses the dev environment unless you pass `--env`. With
`--wait`, it waits for the run, prints its output or error, and exits
with code 1 if the run failed, expired or timed out. `--timeout` limits
how long it waits. It fails straight away if the task id doesn't exist,
and warns when the dev command isn't running.

The `runs` commands now use the same dev branch as `trigger dev` when
you pass `--env dev`.

Mono-RevId: 83d817c031bf943b87ebdf585cbf91d3e416e7f5

Author: ericallam

.changeset/cli-tasks-trigger.md

@@ -0,0 +1,9 @@
+---
+"trigger.dev": patch
+---
+
+Add `trigger.dev tasks trigger <task id>` to trigger a task from your terminal. It uses the dev environment unless you pass `--env`, and `--wait` waits for the run and prints its output or error, exiting with code 1 if it failed. The `runs` commands now use the same dev branch as `trigger dev` when you pass `--env dev`.
+
+```bash
+npx trigger.dev@latest tasks trigger hello-world --payload '{"name":"Ada"}' --wait
+```

.changeset/dev-output-for-agents.md

@@ -0,0 +1,5 @@
+---
+"trigger.dev": patch
+---
+
+`trigger dev` works better when a coding agent like Claude Code, Cursor or Codex runs it: it skips the install prompts, lists the tasks it registered, and prints each run's dashboard URL and output. For everyone, a failed build now ends with a line saying it will rebuild when you fix the errors, and retried attempts and crashed task processes now show their errors.

apps/webapp/app/routes/api.v1.projects.$projectRef.dev-status.ts

@@ -4,6 +4,7 @@ import { devPresence } from "~/presenters/v3/DevPresence.server";
 import {
   authenticatedEnvironmentForAuthentication,
   authenticateRequest,
+  branchNameFromRequest,
 } from "~/services/apiAuth.server";
 import { logger } from "~/services/logger.server";
 
@@ -31,10 +32,12 @@ export async function loader({ request, params }: LoaderFunctionArgs) {
 
     const { projectRef } = parsedParams.data;
 
+    // Dev branches each have their own dev session
     const runtimeEnv = await authenticatedEnvironmentForAuthentication(
       authenticationResult,
       projectRef,
-      "dev"
+      "dev",
+      branchNameFromRequest(request)
     );
 
     const isConnected = await devPresence.isConnected(runtimeEnv.id);

docs/cli-runs-commands.mdx

@@ -84,8 +84,8 @@ npx trigger.dev@latest runs cancel run_abc123
 
 <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 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

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 />

docs/docs.json

@@ -279,6 +279,7 @@
                   "cli-promote-commands",
                   "cli-runs-commands",
                   "cli-switch",
+                  "cli-tasks-commands",
                   "cli-update-commands",
                   "cli-whoami-commands"
                 ]

docs/snippets/cli-commands-develop.mdx

@@ -28,6 +28,21 @@ You will see in the terminal that the server is running and listening for tasks.
 
 It is worth noting that each task runs in a separate Node process. This means that if you have a long-running task, it will not block other tasks from running.
 
+When a build fails, the dev command keeps watching your files and rebuilds as soon as you fix the errors. Until then, new runs use the last version that built successfully.
+
+## Running dev from a coding agent
+
+The dev command detects when a coding agent such as Claude Code, Cursor, Codex or Gemini CLI is running it, and changes its output so the agent can act on it:
+
+- It skips the prompts to install the MCP server and agent skills.
+- If your `@trigger.dev/*` packages don't match the CLI version, it exits with instructions instead of asking whether to update them.
+- When the local worker is ready, it lists the task ids it registered and prints plain dashboard URLs.
+- Each run prints its dashboard URL, and successful runs print their output.
+
+If your agent isn't detected, set the `AI_AGENT` environment variable to its name.
+
+To test a task, an agent can trigger it with [`tasks trigger`](/cli-tasks-commands) and `--wait`, which prints the run's output or error.
+
 ## Options
 
 <ConfigFileOption />

packages/cli-v3/src/build/bundle.ts

@@ -1,6 +1,7 @@
 import { CORE_VERSION } from "@trigger.dev/core/v3";
 import { DEFAULT_RUNTIME, ResolvedConfig } from "@trigger.dev/core/v3/build";
 import { BuildManifest, BuildTarget, TaskFile } from "@trigger.dev/core/v3/schemas";
+import chalk from "chalk";
 import * as esbuild from "esbuild";
 import { createHash } from "node:crypto";
 import { basename, join, relative, resolve } from "node:path";
@@ -348,7 +349,7 @@ export function logBuildWarnings(
 ) {
   const logs = esbuild.formatMessagesSync(warnings, {
     kind: "warning",
-    color: options.color ?? true,
+    color: options.color ?? chalk.level > 0,
   });
   for (const log of logs) {
     console.warn(log);
@@ -360,7 +361,7 @@ export function logBuildWarnings(
  * style esbuild would.
  */
 export function logBuildFailure(errors: esbuild.Message[], warnings: esbuild.Message[]) {
-  const logs = esbuild.formatMessagesSync(errors, { kind: "error", color: true });
+  const logs = esbuild.formatMessagesSync(errors, { kind: "error", color: chalk.level > 0 });
   for (const log of logs) {
     console.error(log);
   }

packages/cli-v3/src/cli/index.ts

@@ -12,6 +12,7 @@ import { configureProjectsCommand } from "../commands/projects/index.js";
 import { configurePromoteCommand } from "../commands/promote.js";
 import { configureRunsCommand } from "../commands/runs/index.js";
 import { configureSwitchProfilesCommand } from "../commands/switch.js";
+import { configureTasksCommand } from "../commands/tasks/index.js";
 import { configureUpdateCommand } from "../commands/update.js";
 import { configureWhoamiCommand } from "../commands/whoami.js";
 import { configureMintTokenCommand } from "../commands/mint-token.js";
@@ -47,6 +48,7 @@ configurePreviewCommand(program);
 configureProjectsCommand(program);
 configureOrgsCommand(program);
 configureRunsCommand(program);
+configureTasksCommand(program);
 configureAnalyzeCommand(program);
 configureMcpCommand(program);
 configureReportCommand(program);

packages/cli-v3/src/commands/dev.ts

@@ -18,6 +18,7 @@ import { loadConfig, watchConfig } from "../config.js";
 import type { DevSessionInstance } from "../dev/devSession.js";
 import { startDevSession } from "../dev/devSession.js";
 import { createLockFile } from "../dev/lock.js";
+import { isAgent } from "../utilities/agent.js";
 import { chalkError } from "../utilities/cliOutput.js";
 import {
   readConfigHasSeenMCPInstallPrompt,
@@ -157,8 +158,9 @@ export function configureDevCommand(program: Command) {
 async function devCommand(options: DevCommandOptions) {
   runtimeChecks();
 
-  // Only show these install prompts if the user is in a terminal (not in a Coding Agent)
-  if (process.stdout.isTTY) {
+  // Only show these install prompts to a person. Some coding agents (e.g. Cursor) run commands
+  // in a real terminal, so a TTY alone doesn't mean someone is there to answer them.
+  if (process.stdout.isTTY && !isAgent) {
     const skipMCPInstall = typeof options.skipMCPInstall === "boolean" && options.skipMCPInstall;
 
     if (!skipMCPInstall) {