CLI Tools

Relevant source files

The Trigger.dev CLI (trigger.dev) is the primary command-line interface for managing Trigger.dev projects. It handles project initialization, local development, and production deployments. The CLI orchestrates the build pipeline, coordinates with the webapp API, and manages Docker image creation for task workers.

For information about task definition and the SDK API, see Task Definition API. For deployment infrastructure and Docker builds, see Docker Build Pipeline and Deployment Process.

CLI Package Structure

The CLI is distributed as the trigger.dev npm package located at packages/cli-v3/package.json1-162 The package provides a single binary command trigger that dispatches to various subcommands.

Key Metadata:

Property	Value
Package Name	`trigger.dev`
Binary Command	`trigger`
Entry Point	`./dist/esm/index.js`
Required Node Version	`>=18.20.0`
Type	ESM module

The CLI depends on several internal packages:

@trigger.dev/build - Build system and extensions
@trigger.dev/core - Core utilities and schemas
@trigger.dev/schema-to-json - JSON schema conversion

External Dependencies:

The CLI uses specialized libraries for its operations:

@depot/cli - Remote Docker builds via Depot service
esbuild - JavaScript/TypeScript bundling
chokidar - File watching for dev mode
commander - Command-line argument parsing
socket.io-client - Real-time communication with webapp
@s2-dev/streamstore - Log streaming during deployments

Sources: packages/cli-v3/package.json1-162

Core Commands

Primary Commands

Sources: packages/cli-v3/CHANGELOG.md1-1000

Command: init

The init command scaffolds a new Trigger.dev project by creating the configuration file and initial task structure.

Workflow:

Prompts for project configuration (if not provided via flags)
Creates trigger.config.ts with project reference
Sets up task directory structure (default: ./trigger)
Installs required npm dependencies
Creates example task files

Configuration Options:

The generated trigger.config.ts file uses the defineConfig function and includes:

project - Project reference ID (from environment or prompt)
dirs - Array of directories containing task files
build - Build extensions (optional)
runtime - Node.js runtime version (default: "node")
retries - Global retry configuration
maxDuration - Maximum task duration in seconds

Example Generated Config:

Dependencies Installed:

The command automatically installs (via nypm package manager detection):

@trigger.dev/sdk - Latest v4 SDK
Development dependencies for TypeScript support

Sources: packages/cli-v3/CHANGELOG.md180-186 packages/core/package.json1-100

Command: dev

The dev command runs a local development server that executes tasks in response to trigger requests. It provides hot-reloading, real-time logs, and debugging capabilities.

Architecture Components:

Component	Location	Role
DevSupervisor	apps/supervisor	Coordinates task execution
TaskRunProcessPool	apps/supervisor	Manages child processes
TaskRunProcess	apps/supervisor	Individual task execution
esbuild	packages/cli-v3	Bundles TypeScript tasks
Socket.io client	packages/cli-v3	Communicates with webapp

Key Features:

Hot Reloading: File watcher (chokidar) detects changes and triggers rebuild
Content-Addressable Storage: Build outputs stored in .trigger/ directory to reduce disk usage
Process Pool: Reuses worker processes when experimental_processKeepAlive is enabled
Import Timing Analysis: Warns about slow imports that affect cold start times
Bundle Size Reporting: Displays bundle size and warns if excessive

Environment Variables:

The dev command recognizes these environment variables:

TRIGGER_PROJECT_REF - Project reference ID
TRIGGER_ACCESS_TOKEN - Personal access token for authentication
TRIGGER_SECRET_KEY - Alternative auth method
OTEL_EXPORTER_OTLP_ENDPOINT - External telemetry endpoint

Configuration Options:

From trigger.config.ts:

dirs - Task directories to watch and build
build.extensions - Build-time modifications (see Build Extensions)
build.external - Packages to exclude from bundle
build.keepNames - Preserve function names for debugging (default: true)
build.minify - Minify output (experimental)
experimental_processKeepAlive - Reuse worker processes between runs
telemetry.exporters - OpenTelemetry trace exporters
telemetry.logExporters - OpenTelemetry log exporters

Process Working Directory:

By default, process.cwd() in tasks points to the project root. Setting legacyDevProcessCwdBehaviour: false changes it to the build directory (.trigger/.trigger-*), which affects relative file paths.

Sources: packages/cli-v3/CHANGELOG.md155-162 packages/cli-v3/CHANGELOG.md287-289 packages/core/CHANGELOG.md68-74

Command: deploy

The deploy command builds a Docker image containing your tasks and deploys it to the Trigger.dev platform. It supports both local and remote builds.

Deployment Stages:

Stage	Status	Description
Initialize	PENDING	Create deployment record in database
Install	INSTALLING	Install dependencies (native build only)
Build	BUILDING	Create Docker image
Push	DEPLOYING	Upload to container registry
Index	DEPLOYING	Extract task metadata from image
Finalize	DEPLOYED	Activate deployment for traffic

Build Strategies:

1. Remote Build (Default - Depot)

Uses the @depot/cli package to build on Depot's infrastructure:

Supports multi-platform builds (amd64, arm64)
Faster than local builds for large projects
No local Docker daemon required
Requires Depot access token (managed by webapp)

2. Local Build (--local-build)

Builds using local Docker daemon:

Uses docker buildx build for multi-platform support
Requires Docker daemon running locally
Useful when remote services are unavailable
Supports external cache via BUILDX_CACHE_FROM/BUILDX_CACHE_TO env vars

3. Native Build Server (--native-build-server)

Delegates building to the Trigger.dev platform:

Asynchronous build process on server infrastructure
No local Docker required
Suitable for CI/CD environments without Docker access
Uses TRIGGER_EXISTING_DEPLOYMENT_ID to attach to pre-created deployment

Docker Image Structure:

The Dockerfile uses multi-stage builds (see Docker Build Pipeline):

pruner - Isolates workspace dependencies
base - Base Node.js runtime image
dev-deps - Development dependencies for building
builder - Compiles TypeScript and bundles tasks
runner - Final minimal runtime image

Registry Configuration:

Images are pushed to container registries configured by the webapp:

AWS ECR for cloud deployments
GHCR (GitHub Container Registry) for self-hosted
Configured automatically via API response

Environment Variable Synchronization:

The CLI can automatically sync environment variables during deployment:

syncEnvVars() build extension - Syncs from webapp API
syncVercelEnvVars() - Syncs from Vercel project environment
syncNeonEnvVars() - Syncs from Neon database project

Deployment Metadata:

The deployment record includes:

triggeredVia - Deployment source ("CLI", "GitHub Action", etc.)
Image digest for reproducibility
Runtime version detection (Node.js, Bun)
Build duration and log streaming

Image Compression:

Since v4.3.0, deployments use zstd compression for Docker layers, reducing image size and push/pull times.

Error Handling:

Missing TRIGGER_ACCESS_TOKEN in CI fails fast with helpful error message
Build timeouts include hint about --local-build flag
Deployment finalization issues are reported with enhanced error details

Sources: packages/cli-v3/CHANGELOG.md28-33 packages/core/CHANGELOG.md49-50 packages/cli-v3/CHANGELOG.md7-8 packages/cli-v3/CHANGELOG.md187-195

Command: whoami

The whoami command displays authentication information and project details.

Output Information:

User ID (from environment's org member)
Environment details (ID, type, project ref)
Organization information
Project details (including slug, name)
API endpoint being used

API Endpoint:

Calls GET /api/v1/whoami to retrieve information. The server authenticates using the API key or personal access token from the request headers.

Usage Scenarios:

Verify authentication is working
Confirm which project/environment is active
Check current CLI profile configuration
Debug connection issues with the platform

Sources: apps/webapp/app/routes/api.v1.whoami.ts1-34 packages/cli-v3/CHANGELOG.md174-177

Command: switch

The switch command changes the active CLI profile, allowing developers to work with multiple projects or environments.

Functionality:

Accepts profile name as argument (e.g., trigger switch production)
If no argument provided, shows interactive profile selector
Updates stored credentials in user's config directory (via xdg-app-paths)
After switching, automatically reflects new profile in CLI header

Related Configuration:

CLI profiles are stored per-user and persist across terminal sessions. Each profile stores:

API endpoint URL
Access token or secret key
Project reference
Environment selection

Sources: packages/cli-v3/CHANGELOG.md189-195 packages/cli-v3/CHANGELOG.md270-272

Command: update

The update command checks for and installs newer versions of Trigger.dev packages.

Version Detection:

Scans package.json for @trigger.dev/* dependencies
Checks npm registry for latest versions
Detects version mismatches between packages
Handles version ranges correctly

Update Process:

Analyzes current versions in project
Queries npm registry via fast-npm-meta package
Presents available updates
Uses nypm to install updates (detects npm/yarn/pnpm/bun)
Verifies installation success

Error Prevention:

The command includes safeguards against:

False-positive version mismatch warnings
Incorrect version range handling
Package manager detection failures

Sources: packages/cli-v3/CHANGELOG.md162-164 packages/cli-v3/CHANGELOG.md180-182

login:

Authenticates the CLI with the Trigger.dev platform:

Opens browser to platform login page
Receives OAuth callback with credentials
Stores access token in user config directory
Automatically switches to new profile after successful login

logout:

Clears stored credentials:

Removes access token from config
Does not affect other profiles
User must login again to use CLI

Sources: packages/cli-v3/CHANGELOG.md270-272

Configuration File

The trigger.config.ts file is the central configuration for CLI behavior and task execution. It uses the defineConfig function exported from @trigger.dev/sdk/v3.

Core Options:

Build Extensions:

Extensions modify the Docker image or build process. Built-in extensions include:

prismaExtension() - Prisma client generation and migrations
puppeteer() - Chromium browser installation
playwright() - Playwright browser binaries
audioWaveform() - Audio processing tools
ffmpeg() - Video processing (v6 or v7)
syncVercelEnvVars() - Sync environment variables from Vercel
syncNeonEnvVars() - Sync from Neon database

Environment-Specific Configuration:

Configuration can vary by environment using process.env:

OpenTelemetry Configuration:

External observability can be configured via exporters:

Resource Attributes:

Custom OpenTelemetry resource attributes can be set via config or environment variable:

Sources: packages/cli-v3/package.json83-149 packages/trigger-sdk/CHANGELOG.md14-16

CLI Architecture

CLI Dependencies Map:

Dependency	Version	Purpose
commander	^9.4.1	CLI argument parsing
c12	^1.11.1	Configuration loading
esbuild	^0.23.0	TypeScript bundling
chokidar	^3.6.0	File watching
socket.io-client	4.7.5	Real-time communication
@depot/cli	0.0.1-cli.2.80.0	Remote Docker builds
@s2-dev/streamstore	^0.17.6	Log streaming
eventsource	^3.0.2	SSE for build logs
semver	^7.5.0	Version comparisons
zod	3.25.76	Schema validation

Sources: packages/cli-v3/package.json83-149

Command Flags and Options

Global Flags:

Available for all commands:

--config <path> - Path to config file (default: ./trigger.config.ts)
--project-ref <ref> - Override project reference from config
--env <name> - Target environment (dev/staging/prod)
--profile <name> - Use specific CLI profile

dev Command Flags:

--port <port> - HTTP server port for health checks
--hostname <host> - Bind to specific hostname
--debugger - Enable Node.js debugger
--skip-update-check - Don't check for CLI updates

deploy Command Flags:

--env <name> - Target environment (required for prod/staging)
--skip-typecheck - Skip TypeScript type checking
--dry-run - Build image but don't deploy
--save-logs - Save build logs even on success
--push - Push image after dry-run build
--local-build - Force local Docker build
--native-build-server - Use platform build server
--self-hosted - (Deprecated) No longer required

Environment Variables:

CLI behavior can be controlled via environment variables:

Variable	Purpose	Example
`TRIGGER_ACCESS_TOKEN`	API authentication	`tr_prod_abc123...`
`TRIGGER_PROJECT_REF`	Project reference	`proj_abc123`
`TRIGGER_SECRET_KEY`	Alternative auth	`tr_dev_xyz...`
`TRIGGER_API_URL`	Custom API endpoint	`https://api.trigger.dev`
`TRIGGER_EXISTING_DEPLOYMENT_ID`	Attach to deployment	`dep_123`
`OTEL_RESOURCE_ATTRIBUTES`	OpenTelemetry attributes	`env=prod,version=1.0`
`BUILDX_CACHE_FROM`	Docker cache source	`type=registry,ref=...`
`BUILDX_CACHE_TO`	Docker cache target	`type=registry,ref=...`

Sources: packages/cli-v3/CHANGELOG.md28-33 packages/core/CHANGELOG.md68-69 packages/cli-v3/CHANGELOG.md118-121

Integration with Webapp

The CLI communicates with the webapp through multiple channels:

REST API Endpoints:

Endpoint	Method	Purpose
`/api/v1/whoami`	GET	Authentication check
`/api/v1/deployments`	POST	Initialize deployment
`/api/v1/deployments/:id/index`	POST	Upload task metadata
`/api/v1/deployments/:id`	PUT	Finalize deployment
`/api/v1/projects/:ref/envvars`	GET	Retrieve environment variables

WebSocket Communication (dev mode):

The CLI uses Socket.io for real-time communication during local development:

Worker registration with environment details
Run assignment messages
Task execution status updates
Log streaming from worker to dashboard
Checkpoint and resumption coordination

Authentication Methods:

Personal Access Token (TRIGGER_ACCESS_TOKEN)
- Used for CLI commands
- Long-lived, user-scoped
- Passed via Authorization: Bearer header
Secret Key (TRIGGER_SECRET_KEY)
- Development environment key
- Environment-scoped, not user-scoped
- Used for programmatic access
Worker Token
- Generated during worker registration
- Short-lived, session-scoped
- Used for dev mode WebSocket connection

Sources: apps/webapp/app/routes/api.v1.whoami.ts1-34 packages/cli-v3/CHANGELOG.md214-215

Model Context Protocol (MCP) Support

The CLI includes an experimental MCP (Model Context Protocol) server for AI agent integration:

MCP Package Metadata:

Available Tools:

AI agents can interact with Trigger.dev via MCP tools:

Trigger tasks
Get run details
Wait for run completion
List available tasks
Query project configuration

Installation:

The trigger install-mcp command registers the CLI as an MCP server with supported AI tools (Claude Desktop, etc.).

Sources: packages/cli-v3/package.json15 packages/cli-v3/package.json80-81 packages/cli-v3/CHANGELOG.md144-146

Build Output and Caching

Build Directory Structure:

.trigger/
├── .trigger-<hash>/       # Content-addressable build output
│   ├── index.js          # Bundled task code
│   ├── index.js.map      # Source maps
│   └── package.json      # Runtime dependencies
├── metafile.json         # esbuild metafile (with --dry-run)
└── logs/                 # Build logs

Content-Addressable Storage:

Since v4.2.0, the dev CLI uses content-addressable storage for build outputs:

Each build is stored in .trigger/.trigger-<hash>/
Hash is derived from build configuration and source files
Reduces disk usage by deduplicating identical builds
Enables instant rollback to previous builds

Bundle Analysis:

The CLI provides detailed bundle analysis:

Total bundle size with warning for large bundles (>5MB)
Import timing analysis to identify slow imports
External package detection
Module tree visualization (experimental)

Cache Strategies:

For deployments with --local-build:

BUILDX_CACHE_FROM - Load cache from registry or local
BUILDX_CACHE_TO - Export cache to registry or local
Supports multi-platform cache sharing

Sources: packages/cli-v3/CHANGELOG.md31-32 packages/cli-v3/CHANGELOG.md180-181

Error Handling and Debugging

Common Error Scenarios:

Missing Authentication:
- Error: "Invalid or Missing API key"
- Solution: Run trigger login or set TRIGGER_ACCESS_TOKEN
- In CI: Ensure token is set in secrets with link to docs
Missing Configuration:
- Error: "maxDuration is now required"
- Solution: Add maxDuration to trigger.config.ts
- Hint about --config flag for custom locations
Build Failures:
- Provides AI assistance link for build errors
- Distinguishes between local and remote build failures
- Suggests --local-build flag on upstream provider outages
Deployment Stuck:
- Enhanced error reporting for finalization issues
- Image digest retrieval for debugging
- Full logs always printed in CI environments

Debug Options:

DEBUG=trigger:* - Enable debug logging (uses debug package)
--save-logs - Keep build logs even on success
Source maps enabled by default for stack traces
keepNames: true preserves function names for debugging

Graceful Shutdown:

The CLI handles signals properly:

SIGTERM: Complete current runs, disable new runs
SIGINT (Ctrl+C): Graceful shutdown with cleanup
Prevents orphaned task processes
Flushes telemetry data before exit

Sources: packages/cli-v3/CHANGELOG.md82-84 packages/cli-v3/CHANGELOG.md213-214 packages/cli-v3/CHANGELOG.md267-271

CLI Tools

Relevant source files

For information about task definition and the SDK API, see Task Definition API. For deployment infrastructure and Docker builds, see Docker Build Pipeline and Deployment Process.

CLI Package Structure

The CLI is distributed as the trigger.dev npm package located at packages/cli-v3/package.json1-162 The package provides a single binary command trigger that dispatches to various subcommands.

Key Metadata:

Property	Value
Package Name	`trigger.dev`
Binary Command	`trigger`
Entry Point	`./dist/esm/index.js`
Required Node Version	`>=18.20.0`
Type	ESM module

The CLI depends on several internal packages:

@trigger.dev/build - Build system and extensions
@trigger.dev/core - Core utilities and schemas
@trigger.dev/schema-to-json - JSON schema conversion

External Dependencies:

The CLI uses specialized libraries for its operations:

@depot/cli - Remote Docker builds via Depot service
esbuild - JavaScript/TypeScript bundling
chokidar - File watching for dev mode
commander - Command-line argument parsing
socket.io-client - Real-time communication with webapp
@s2-dev/streamstore - Log streaming during deployments

Sources: packages/cli-v3/package.json1-162

Core Commands

Primary Commands

Sources: packages/cli-v3/CHANGELOG.md1-1000

Command: init

The init command scaffolds a new Trigger.dev project by creating the configuration file and initial task structure.

Workflow:

Prompts for project configuration (if not provided via flags)
Creates trigger.config.ts with project reference
Sets up task directory structure (default: ./trigger)
Installs required npm dependencies
Creates example task files

Configuration Options:

The generated trigger.config.ts file uses the defineConfig function and includes:

project - Project reference ID (from environment or prompt)
dirs - Array of directories containing task files
build - Build extensions (optional)
runtime - Node.js runtime version (default: "node")
retries - Global retry configuration
maxDuration - Maximum task duration in seconds

Example Generated Config:

Dependencies Installed:

The command automatically installs (via nypm package manager detection):

@trigger.dev/sdk - Latest v4 SDK
Development dependencies for TypeScript support

Sources: packages/cli-v3/CHANGELOG.md180-186 packages/core/package.json1-100

Command: dev

The dev command runs a local development server that executes tasks in response to trigger requests. It provides hot-reloading, real-time logs, and debugging capabilities.

Architecture Components:

Component	Location	Role
DevSupervisor	apps/supervisor	Coordinates task execution
TaskRunProcessPool	apps/supervisor	Manages child processes
TaskRunProcess	apps/supervisor	Individual task execution
esbuild	packages/cli-v3	Bundles TypeScript tasks
Socket.io client	packages/cli-v3	Communicates with webapp

Key Features:

Hot Reloading: File watcher (chokidar) detects changes and triggers rebuild
Content-Addressable Storage: Build outputs stored in .trigger/ directory to reduce disk usage
Process Pool: Reuses worker processes when experimental_processKeepAlive is enabled
Import Timing Analysis: Warns about slow imports that affect cold start times
Bundle Size Reporting: Displays bundle size and warns if excessive

Environment Variables:

The dev command recognizes these environment variables:

TRIGGER_PROJECT_REF - Project reference ID
TRIGGER_ACCESS_TOKEN - Personal access token for authentication
TRIGGER_SECRET_KEY - Alternative auth method
OTEL_EXPORTER_OTLP_ENDPOINT - External telemetry endpoint

Configuration Options:

From trigger.config.ts:

dirs - Task directories to watch and build
build.extensions - Build-time modifications (see Build Extensions)
build.external - Packages to exclude from bundle
build.keepNames - Preserve function names for debugging (default: true)
build.minify - Minify output (experimental)
experimental_processKeepAlive - Reuse worker processes between runs
telemetry.exporters - OpenTelemetry trace exporters
telemetry.logExporters - OpenTelemetry log exporters

Process Working Directory:

Sources: packages/cli-v3/CHANGELOG.md155-162 packages/cli-v3/CHANGELOG.md287-289 packages/core/CHANGELOG.md68-74

Command: deploy

The deploy command builds a Docker image containing your tasks and deploys it to the Trigger.dev platform. It supports both local and remote builds.

Deployment Stages:

Stage	Status	Description
Initialize	PENDING	Create deployment record in database
Install	INSTALLING	Install dependencies (native build only)
Build	BUILDING	Create Docker image
Push	DEPLOYING	Upload to container registry
Index	DEPLOYING	Extract task metadata from image
Finalize	DEPLOYED	Activate deployment for traffic

Build Strategies:

1. Remote Build (Default - Depot)

Uses the @depot/cli package to build on Depot's infrastructure:

Supports multi-platform builds (amd64, arm64)
Faster than local builds for large projects
No local Docker daemon required
Requires Depot access token (managed by webapp)

2. Local Build (--local-build)

Builds using local Docker daemon:

Uses docker buildx build for multi-platform support
Requires Docker daemon running locally
Useful when remote services are unavailable
Supports external cache via BUILDX_CACHE_FROM/BUILDX_CACHE_TO env vars

3. Native Build Server (--native-build-server)

Delegates building to the Trigger.dev platform:

Asynchronous build process on server infrastructure
No local Docker required
Suitable for CI/CD environments without Docker access
Uses TRIGGER_EXISTING_DEPLOYMENT_ID to attach to pre-created deployment

Docker Image Structure:

The Dockerfile uses multi-stage builds (see Docker Build Pipeline):

pruner - Isolates workspace dependencies
base - Base Node.js runtime image
dev-deps - Development dependencies for building
builder - Compiles TypeScript and bundles tasks
runner - Final minimal runtime image

Registry Configuration:

Images are pushed to container registries configured by the webapp:

AWS ECR for cloud deployments
GHCR (GitHub Container Registry) for self-hosted
Configured automatically via API response

Environment Variable Synchronization:

The CLI can automatically sync environment variables during deployment:

syncEnvVars() build extension - Syncs from webapp API
syncVercelEnvVars() - Syncs from Vercel project environment
syncNeonEnvVars() - Syncs from Neon database project

Deployment Metadata:

The deployment record includes:

triggeredVia - Deployment source ("CLI", "GitHub Action", etc.)
Image digest for reproducibility
Runtime version detection (Node.js, Bun)
Build duration and log streaming

Image Compression:

Since v4.3.0, deployments use zstd compression for Docker layers, reducing image size and push/pull times.

Error Handling:

Missing TRIGGER_ACCESS_TOKEN in CI fails fast with helpful error message
Build timeouts include hint about --local-build flag
Deployment finalization issues are reported with enhanced error details

Sources: packages/cli-v3/CHANGELOG.md28-33 packages/core/CHANGELOG.md49-50 packages/cli-v3/CHANGELOG.md7-8 packages/cli-v3/CHANGELOG.md187-195

Command: whoami

The whoami command displays authentication information and project details.

Output Information:

User ID (from environment's org member)
Environment details (ID, type, project ref)
Organization information
Project details (including slug, name)
API endpoint being used

API Endpoint:

Calls GET /api/v1/whoami to retrieve information. The server authenticates using the API key or personal access token from the request headers.

Usage Scenarios:

Verify authentication is working
Confirm which project/environment is active
Check current CLI profile configuration
Debug connection issues with the platform

Sources: apps/webapp/app/routes/api.v1.whoami.ts1-34 packages/cli-v3/CHANGELOG.md174-177

Command: switch

The switch command changes the active CLI profile, allowing developers to work with multiple projects or environments.

Functionality:

Accepts profile name as argument (e.g., trigger switch production)
If no argument provided, shows interactive profile selector
Updates stored credentials in user's config directory (via xdg-app-paths)
After switching, automatically reflects new profile in CLI header

Related Configuration:

CLI profiles are stored per-user and persist across terminal sessions. Each profile stores:

API endpoint URL
Access token or secret key
Project reference
Environment selection

Sources: packages/cli-v3/CHANGELOG.md189-195 packages/cli-v3/CHANGELOG.md270-272

Command: update

The update command checks for and installs newer versions of Trigger.dev packages.

Version Detection:

Scans package.json for @trigger.dev/* dependencies
Checks npm registry for latest versions
Detects version mismatches between packages
Handles version ranges correctly

Update Process:

Analyzes current versions in project
Queries npm registry via fast-npm-meta package
Presents available updates
Uses nypm to install updates (detects npm/yarn/pnpm/bun)
Verifies installation success

Error Prevention:

The command includes safeguards against:

False-positive version mismatch warnings
Incorrect version range handling
Package manager detection failures

Sources: packages/cli-v3/CHANGELOG.md162-164 packages/cli-v3/CHANGELOG.md180-182

login:

Authenticates the CLI with the Trigger.dev platform:

Opens browser to platform login page
Receives OAuth callback with credentials
Stores access token in user config directory
Automatically switches to new profile after successful login

logout:

Clears stored credentials:

Removes access token from config
Does not affect other profiles
User must login again to use CLI

Sources: packages/cli-v3/CHANGELOG.md270-272

Configuration File

The trigger.config.ts file is the central configuration for CLI behavior and task execution. It uses the defineConfig function exported from @trigger.dev/sdk/v3.

Core Options:

Build Extensions:

Extensions modify the Docker image or build process. Built-in extensions include:

prismaExtension() - Prisma client generation and migrations
puppeteer() - Chromium browser installation
playwright() - Playwright browser binaries
audioWaveform() - Audio processing tools
ffmpeg() - Video processing (v6 or v7)
syncVercelEnvVars() - Sync environment variables from Vercel
syncNeonEnvVars() - Sync from Neon database

Environment-Specific Configuration:

Configuration can vary by environment using process.env:

OpenTelemetry Configuration:

External observability can be configured via exporters:

Resource Attributes:

Custom OpenTelemetry resource attributes can be set via config or environment variable:

Sources: packages/cli-v3/package.json83-149 packages/trigger-sdk/CHANGELOG.md14-16

CLI Architecture

CLI Dependencies Map:

Dependency	Version	Purpose
commander	^9.4.1	CLI argument parsing
c12	^1.11.1	Configuration loading
esbuild	^0.23.0	TypeScript bundling
chokidar	^3.6.0	File watching
socket.io-client	4.7.5	Real-time communication
@depot/cli	0.0.1-cli.2.80.0	Remote Docker builds
@s2-dev/streamstore	^0.17.6	Log streaming
eventsource	^3.0.2	SSE for build logs
semver	^7.5.0	Version comparisons
zod	3.25.76	Schema validation

Sources: packages/cli-v3/package.json83-149

Command Flags and Options

Global Flags:

Available for all commands:

--config <path> - Path to config file (default: ./trigger.config.ts)
--project-ref <ref> - Override project reference from config
--env <name> - Target environment (dev/staging/prod)
--profile <name> - Use specific CLI profile

dev Command Flags:

--port <port> - HTTP server port for health checks
--hostname <host> - Bind to specific hostname
--debugger - Enable Node.js debugger
--skip-update-check - Don't check for CLI updates

deploy Command Flags:

--env <name> - Target environment (required for prod/staging)
--skip-typecheck - Skip TypeScript type checking
--dry-run - Build image but don't deploy
--save-logs - Save build logs even on success
--push - Push image after dry-run build
--local-build - Force local Docker build
--native-build-server - Use platform build server
--self-hosted - (Deprecated) No longer required

Environment Variables:

CLI behavior can be controlled via environment variables:

Variable	Purpose	Example
`TRIGGER_ACCESS_TOKEN`	API authentication	`tr_prod_abc123...`
`TRIGGER_PROJECT_REF`	Project reference	`proj_abc123`
`TRIGGER_SECRET_KEY`	Alternative auth	`tr_dev_xyz...`
`TRIGGER_API_URL`	Custom API endpoint	`https://api.trigger.dev`
`TRIGGER_EXISTING_DEPLOYMENT_ID`	Attach to deployment	`dep_123`
`OTEL_RESOURCE_ATTRIBUTES`	OpenTelemetry attributes	`env=prod,version=1.0`
`BUILDX_CACHE_FROM`	Docker cache source	`type=registry,ref=...`
`BUILDX_CACHE_TO`	Docker cache target	`type=registry,ref=...`

Sources: packages/cli-v3/CHANGELOG.md28-33 packages/core/CHANGELOG.md68-69 packages/cli-v3/CHANGELOG.md118-121

Integration with Webapp

The CLI communicates with the webapp through multiple channels:

REST API Endpoints:

Endpoint	Method	Purpose
`/api/v1/whoami`	GET	Authentication check
`/api/v1/deployments`	POST	Initialize deployment
`/api/v1/deployments/:id/index`	POST	Upload task metadata
`/api/v1/deployments/:id`	PUT	Finalize deployment
`/api/v1/projects/:ref/envvars`	GET	Retrieve environment variables

WebSocket Communication (dev mode):

The CLI uses Socket.io for real-time communication during local development:

Worker registration with environment details
Run assignment messages
Task execution status updates
Log streaming from worker to dashboard
Checkpoint and resumption coordination

Authentication Methods:

Personal Access Token (TRIGGER_ACCESS_TOKEN)
- Used for CLI commands
- Long-lived, user-scoped
- Passed via Authorization: Bearer header
Secret Key (TRIGGER_SECRET_KEY)
- Development environment key
- Environment-scoped, not user-scoped
- Used for programmatic access
Worker Token
- Generated during worker registration
- Short-lived, session-scoped
- Used for dev mode WebSocket connection

Sources: apps/webapp/app/routes/api.v1.whoami.ts1-34 packages/cli-v3/CHANGELOG.md214-215

Model Context Protocol (MCP) Support

The CLI includes an experimental MCP (Model Context Protocol) server for AI agent integration:

MCP Package Metadata:

Available Tools:

AI agents can interact with Trigger.dev via MCP tools:

Trigger tasks
Get run details
Wait for run completion
List available tasks
Query project configuration

Installation:

The trigger install-mcp command registers the CLI as an MCP server with supported AI tools (Claude Desktop, etc.).

Sources: packages/cli-v3/package.json15 packages/cli-v3/package.json80-81 packages/cli-v3/CHANGELOG.md144-146

Build Output and Caching

Build Directory Structure:

.trigger/
├── .trigger-<hash>/       # Content-addressable build output
│   ├── index.js          # Bundled task code
│   ├── index.js.map      # Source maps
│   └── package.json      # Runtime dependencies
├── metafile.json         # esbuild metafile (with --dry-run)
└── logs/                 # Build logs

Content-Addressable Storage:

Since v4.2.0, the dev CLI uses content-addressable storage for build outputs:

Each build is stored in .trigger/.trigger-<hash>/
Hash is derived from build configuration and source files
Reduces disk usage by deduplicating identical builds
Enables instant rollback to previous builds

Bundle Analysis:

The CLI provides detailed bundle analysis:

Total bundle size with warning for large bundles (>5MB)
Import timing analysis to identify slow imports
External package detection
Module tree visualization (experimental)

Cache Strategies:

For deployments with --local-build:

BUILDX_CACHE_FROM - Load cache from registry or local
BUILDX_CACHE_TO - Export cache to registry or local
Supports multi-platform cache sharing

Sources: packages/cli-v3/CHANGELOG.md31-32 packages/cli-v3/CHANGELOG.md180-181

Error Handling and Debugging

Common Error Scenarios:

Missing Authentication:
- Error: "Invalid or Missing API key"
- Solution: Run trigger login or set TRIGGER_ACCESS_TOKEN
- In CI: Ensure token is set in secrets with link to docs
Missing Configuration:
- Error: "maxDuration is now required"
- Solution: Add maxDuration to trigger.config.ts
- Hint about --config flag for custom locations
Build Failures:
- Provides AI assistance link for build errors
- Distinguishes between local and remote build failures
- Suggests --local-build flag on upstream provider outages
Deployment Stuck:
- Enhanced error reporting for finalization issues
- Image digest retrieval for debugging
- Full logs always printed in CI environments

Debug Options:

DEBUG=trigger:* - Enable debug logging (uses debug package)
--save-logs - Keep build logs even on success
Source maps enabled by default for stack traces
keepNames: true preserves function names for debugging

Graceful Shutdown:

The CLI handles signals properly:

SIGTERM: Complete current runs, disable new runs
SIGINT (Ctrl+C): Graceful shutdown with cleanup
Prevents orphaned task processes
Flushes telemetry data before exit

Sources: packages/cli-v3/CHANGELOG.md82-84 packages/cli-v3/CHANGELOG.md213-214 packages/cli-v3/CHANGELOG.md267-271

CLI Tools

CLI Package Structure

Core Commands

Command: init

Command: dev

Command: deploy

Command: whoami

Command: switch

Command: update

Configuration File

CLI Architecture

Command Flags and Options

Integration with Webapp

Model Context Protocol (MCP) Support

Build Output and Caching

Error Handling and Debugging

On this page

CLI Tools

CLI Package Structure

Core Commands

Command: init

Command: dev

Command: deploy

Command: whoami

Command: switch

Command: update

Configuration File

CLI Architecture

Command Flags and Options

Integration with Webapp

Model Context Protocol (MCP) Support

Build Output and Caching

Error Handling and Debugging

On this page

CLI Tools

CLI Package Structure

Core Commands

Command: init

Command: dev

Command: deploy

Command: whoami

Command: switch

Command: update

Command: login / logout

Configuration File

CLI Architecture

Command Flags and Options

Integration with Webapp

Model Context Protocol (MCP) Support

Build Output and Caching

Error Handling and Debugging

On this page

CLI Tools

CLI Package Structure

Core Commands

Command: init

Command: dev

Command: deploy

Command: whoami

Command: switch

Command: update

Command: login / logout

Configuration File

CLI Architecture

Command Flags and Options

Integration with Webapp

Model Context Protocol (MCP) Support

Build Output and Caching

Error Handling and Debugging

On this page