CLI Commands Reference

Fresh

Complete reference for all Trigger.dev CLI commands.

Installation

# Always use latest
npx trigger.dev@latest [command]

# Or install globally
npm install -g trigger.dev

Core Commands

init — Initialize a Project

npx trigger.dev@latest init

Option	Description
--project-ref -p	Project reference (skips selection prompt)
--trigger-dir	Custom directory for trigger files
--skip-package-install	Don't install npm packages

What it does:

• Optionally installs MCP server for AI assistants
• Logs you in (if not already)
• Lets you select your project
• Installs @trigger.dev/sdk
• Creates /trigger directory with example task
• Creates trigger.config.ts

---

dev — Start Dev Server

npx trigger.dev@latest dev

Option	Description
--config -c	Config file path (default: trigger.config.ts)
--project-ref -p	Project ref (if no config file)
--env-file	Load env vars from file
--skip-update-check	Skip @trigger.dev/* package update check
--analyze	Show import timing analysis

Common options (all commands):

Option	Description
--profile	Login profile to use (default: "default")
--api-url -a	Override API URL
--log-level -l	debug, info, log, warn, error, none
--skip-telemetry	Opt out of telemetry
--help -h	Show help
--version -v	Show version

---

deploy — Deploy to Production

npx trigger.dev@latest deploy

Option	Description
--env	Environment: prod (default) or staging
--skip-promotion	Deploy without making it the current version
--force-local-build	Build locally using Docker instead of remote
--dry-run	Build and inspect without deploying
--log-level debug	Verbose debug output

---

login / logout — Authentication

npx trigger.dev@latest login
npx trigger.dev@latest logout

# Use a specific profile
npx trigger.dev@latest login --profile staging

---

promote — Promote a Version

npx trigger.dev@latest promote 20260221.1

Makes a previously deployed (but not current) version the active current version.

---

whoami — Check Auth Status

npx trigger.dev@latest whoami

---

Concurrently (Running Dev + App Server Together)

Install concurrently as a dev dependency, then add to package.json:

{
  "scripts": {
    "dev": "concurrently --raw --kill-others npm:dev:*",
    "dev:trigger": "npx trigger.dev@latest dev",
    "dev:next": "next dev"
  }
}

---

Environment Variables

Variable	Description
TRIGGER_SECRET_KEY	API key for triggering tasks (tr_dev_xxx or tr_prod_xxx)
TRIGGER_API_URL	Override API endpoint
TRIGGER_VERSION	Pin all tasks to a specific version
TRIGGER_PREVIEW_BRANCH	Set preview branch name
TRIGGER_TELEMETRY_DISABLED	Opt out of telemetry (set to any non-empty value)

---

SDK Quick Reference

Triggering

import { tasks, batch } from "@trigger.dev/sdk";

// Single task (from backend, no import needed)
await tasks.trigger("task-id", payload);

// Batch same task
await tasks.batchTrigger("task-id", items.map(p => ({ payload: p })));

// Batch different tasks
await batch.trigger([
  { id: "task-1", payload: data1 },
  { id: "task-2", payload: data2 },
]);

Triggering from Inside a Task

import { task } from "@trigger.dev/sdk";
import { childTask } from "./child-task";

export const parentTask = task({
  id: "parent",
  run: async (payload) => {
    // Fire and forget
    await childTask.trigger(data);

    // Wait for result
    const result = await childTask.triggerAndWait(data);

    // Batch + wait
    const results = await childTask.batchTriggerAndWait(items);

    // Mixed tasks + wait
    const mixed = await batch.triggerAndWait([
      { id: "task-a", payload: dataA },
      { id: "task-b", payload: dataB },
    ]);
  }
});

Trigger Options

await myTask.trigger(payload, {
  delay: "1h",                    // Delay execution
  ttl: "30m",                     // Expire if not started
  idempotencyKey: "unique-key",   // Prevent duplicates
  debounce: {                     // Debounce
    key: "user-123",
    delay: "5s",
    mode: "trailing",             // "leading" (default) or "trailing"
    maxDelay: "1m"
  },
  queue: {
    name: "priority-queue",
    concurrencyLimit: 10
  },
  concurrencyKey: userId,         // Per-entity queues
  maxAttempts: 5,                 // Override retry count
  machine: "large-1x",           // Machine preset
  region: "eu-central-1",        // Run region
  version: "20260221.1",         // Pin version
});

---

Task Configuration Cheatsheet

export const myTask = task({
  id: "my-task",                  // Required, unique
  retry: {
    maxAttempts: 3,               // Default: 3
    factor: 2,                    // Backoff multiplier
    minTimeoutInMs: 1000,
    maxTimeoutInMs: 30000,
    randomize: true,
  },
  queue: {
    concurrencyLimit: 5,          // Global limit for this task
  },
  machine: {
    preset: "large-1x",           // micro, small-1x, medium-1x, large-1x, etc.
  },
  maxDuration: 300,               // Seconds — stop if exceeded
  run: async (payload, { ctx }) => {
    // ctx.run.id, ctx.run.attempt.number, etc.
    return { result: "done" };
  },
});