This document describes the command-line interface (CLI) commands available in n8n and the execution modes that determine how workflow executions are processed. It covers the binary boot sequence, BaseCommand lifecycle, the start/worker/webhook commands, CommandRegistry/DI container wiring, and the variables API. For information about the workflow execution engine itself, see Workflow Execution Engine. For deployment configuration details, see Configuration System.
n8n provides three primary CLI commands (start, worker, webhook) that launch different process types, each with specific responsibilities. The system supports two execution modes: regular mode (in-process execution) and queue mode (distributed execution via Redis/Bull), which fundamentally change how workflow executions are orchestrated across processes.
The n8n binary (packages/cli/bin/n8n) bootstraps the process, initializes environment configuration, and delegates to CommandRegistry, which is resolved from the @n8n/di DI container. CommandRegistry identifies the target command from process.argv[2], instantiates the matching class via the DI container, and drives the command lifecycle: flag parsing ā init() ā run(). Each command class extends BaseCommand and is annotated with the @Command decorator from @n8n/decorators.
The entry point for the n8n process is packages/cli/bin/n8n. It performs several ordered steps before any application code runs.
Boot steps (in order):
| Step | Code / Mechanism | Notes |
|---|---|---|
| 1. Version flags | process.argv.slice(-1)[0] check | -v, -V, --version print version and exit |
| 2. Node.js version check | semver.satisfies(process.versions.node, engines.node) | Exits with error if unsatisfied |
| 3. Disable custom inspect | util.inspect.defaultOptions.customInspect = false | Prevents oversized object dumps in logs |
| 4. Source maps | require('source-map-support').install() | Readable TypeScript stack traces |
| 5. Reflect metadata | require('reflect-metadata') | Required for @n8n/di decorator-based DI |
| 6. dotenv | require('dotenv').config({ quiet: true }) | Skipped when E2E_TESTS=true |
| 7. Config bootstrap | require('../dist/config') | Triggers GlobalConfig and legacy convict initialization; must precede TypeORM entity loading |
| 8. DNS settings | dns.setDefaultResultOrder / net.setDefaultAutoSelectFamily | Optional IPv4-first; disables Happy Eyeballs algorithm |
| 9. Command execution | Container.get(CommandRegistry).execute() | Resolves and runs the matched command |
The config bootstrap step (7) is critical: TypeORM entity decorators in @n8n/db read GlobalConfig.database.type to select SQL column types. Loading dist/config first ensures GlobalConfig is populated from environment variables before any entity class is evaluated.
Boot sequence: bin/n8n through CommandRegistry
Sources: packages/cli/bin/n8n1-65 packages/cli/src/config/index.ts1-73 packages/cli/src/config/schema.ts1-55 packages/@n8n/config/src/index.ts69-232
require('../dist/config') loads packages/cli/src/config/index.ts, which initializes two separate configuration systems:
GlobalConfig (@n8n/config): Zod-validated, class-based environment variable mapping. All new configuration should be added here. See Configuration System.config/schema.ts): A small remaining set of convict-managed keys (userManagement.authenticationMethod, endpoints.rest, ai.*). Marked @deprecated ā no new variables should be added here.Sources: packages/cli/src/config/index.ts28-30 packages/cli/src/config/schema.ts1-7
@CommandEach command class declares itself using the @Command decorator from @n8n/decorators. The decorator associates the class with:
name string matched against process.argv[2]flagsSchema (Zod object) for type-safe CLI flag parsingdescription and examples list@Command({ name: 'start', description: '...', flagsSchema })
export class Start extends BaseCommand<z.infer<typeof flagsSchema>> { ... }
@Command({ name: 'worker', description: '...', flagsSchema })
export class Worker extends BaseCommand<z.infer<typeof flagsSchema>> { ... }
@Command({ name: 'webhook', description: '...' })
export class Webhook extends BaseCommand { ... }
Command class hierarchy and DI resolution
Sources: packages/cli/src/commands/start.ts49-55 packages/cli/src/commands/worker.ts26-32 packages/cli/src/commands/webhook.ts16-20 packages/cli/src/commands/base-command.ts43-46
Commands define accepted flags as Zod schemas, giving full type inference and runtime validation:
| Command | Flag | Type | Default | Description |
|---|---|---|---|---|
start | --open / -o | boolean | ā | Open editor UI in browser at startup |
worker | --concurrency | number (int) | 10 | Maximum concurrent workflow jobs |
webhook | (none) | ā | ā | No command-level flags |
Sources: packages/cli/src/commands/start.ts45-47 packages/cli/src/commands/worker.ts22-24
BaseCommandBaseCommand resolves all shared services from Container at construction time or lazily during init(). Services decorated with @Service() (from @n8n/di) are singleton-scoped: first Container.get() call instantiates and caches them.
Key services resolved at construction:
| Property | Type | Resolved via |
|---|---|---|
logger | Logger | Container.get(Logger) |
instanceSettings | InstanceSettings | Container.get(InstanceSettings) |
shutdownService | ShutdownService | Container.get(ShutdownService) |
globalConfig | GlobalConfig | Container.get(GlobalConfig) |
moduleRegistry | ModuleRegistry | Container.get(ModuleRegistry) |
executionContextHookRegistry | ExecutionContextHookRegistry | Container.get(ExecutionContextHookRegistry) |
Sources: packages/cli/src/commands/base-command.ts46-70
Sources: packages/cli/src/commands/base-command.ts42-350 packages/cli/src/commands/start.ts49-411 packages/cli/src/commands/worker.ts26-210 packages/cli/src/commands/webhook.ts16-113
The Start command launches the main n8n application server, providing the web UI, REST API, and workflow execution capabilities.
Primary Responsibilities:
Key Initialization Sequence:
Sources: packages/cli/src/commands/start.ts189-269 packages/cli/src/commands/start.ts302-368
Configuration Parameters:
| Environment Variable | Default | Description |
|---|---|---|
N8N_PORT | 5678 | HTTP port for the server |
N8N_HOST | localhost | Hostname |
N8N_PROTOCOL | http | Protocol (http/https) |
N8N_DISABLE_UI | false | Disable web UI |
N8N_EXECUTIONS_MODE | regular | Execution mode (regular/queue) |
N8N_MULTI_MAIN_SETUP_ENABLED | false | Enable multi-main mode |
Sources: packages/@n8n/config/src/index.ts111-128 packages/@n8n/config/src/configs/executions.config.ts
Command Line Usage:
Sources: packages/cli/src/commands/start.ts45-54
The Worker command launches a process dedicated to executing workflow jobs from the Redis queue in queue mode.
Primary Responsibilities:
Initialization Sequence:
Sources: packages/cli/src/commands/worker.ts74-173
Configuration Parameters:
| Environment Variable | Default | Description |
|---|---|---|
N8N_CONCURRENCY_PRODUCTION_LIMIT | -1 | Max concurrent executions (-1 = unlimited) |
QUEUE_HEALTH_CHECK_ACTIVE | false | Enable health endpoint |
QUEUE_HEALTH_CHECK_PORT | 5678 | Health endpoint port |
N8N_GRACEFUL_SHUTDOWN_TIMEOUT | 30 | Graceful shutdown timeout (seconds) |
Sources: packages/@n8n/config/src/configs/executions.config.ts packages/@n8n/config/src/configs/scaling-mode.config.ts
Command Line Usage:
Sources: packages/cli/src/commands/worker.ts22-31
Worker Server Endpoints:
When enabled, workers can expose HTTP endpoints:
| Endpoint | Purpose | Config |
|---|---|---|
/healthz | Health check | QUEUE_HEALTH_CHECK_ACTIVE=true |
/metrics | Prometheus metrics | N8N_METRICS=true |
| Credentials overwrites | Dynamic credential updates | CREDENTIALS_OVERWRITE_ENDPOINT set |
Sources: packages/cli/src/scaling/worker-server.ts22-31 packages/cli/src/commands/worker.ts180-189
The Webhook command launches a dedicated process for handling production webhooks in queue mode, offloading webhook processing from the main instance.
Primary Responsibilities:
Requirements:
executions.mode = 'queue' and exits with an error otherwiseSources: packages/cli/src/commands/webhook.ts44-59
Initialization Sequence:
Sources: packages/cli/src/commands/webhook.ts44-98
Command Line Usage:
Webhook Endpoint Paths:
| Endpoint Type | Default Path | Config Variable |
|---|---|---|
| Production webhooks | /webhook | N8N_ENDPOINT_WEBHOOK |
| Test webhooks | /webhook-test | N8N_ENDPOINT_WEBHOOK_TEST |
| Waiting webhooks | /webhook-waiting | N8N_ENDPOINT_WEBHOOK_WAITING |
| Form endpoints | /form | N8N_ENDPOINT_FORM |
Sources: packages/@n8n/config/src/configs/endpoints.config.ts packages/cli/src/abstract-server.ts85-92
All commands inherit from BaseCommand, which provides common initialization and lifecycle management.
Common Initialization Steps:
Sources: packages/cli/src/commands/base-command.ts83-192
Shutdown Handling:
All commands implement graceful shutdown on SIGTERM and SIGINT signals:
ShutdownServiceN8N_GRACEFUL_SHUTDOWN_TIMEOUT seconds)Sources: packages/cli/src/commands/base-command.ts323-349
Crash Journal:
The crash journal tracks process starts/stops to detect crashes and enable recovery:
~/.n8n/crash.jsonSources: packages/cli/src/commands/base-command.ts198-200 packages/cli/src/crash-journal.ts
n8n supports two execution modes that fundamentally change how workflows are executed: regular mode (in-process) and queue mode (distributed via Redis).
Sources: packages/cli/src/commands/start.ts193-221 packages/cli/src/commands/worker.ts64-69
In regular mode, workflow executions run in the same process as the main n8n server.
Characteristics:
Execution Flow:
Sources: packages/cli/src/workflow-runner.ts packages/cli/src/active-executions.ts
Configuration:
Sources: packages/@n8n/config/src/configs/executions.config.ts
In queue mode, workflow executions are enqueued to Redis and processed by separate worker processes.
Characteristics:
Architecture Components:
| Component | Process Type | Responsibility |
|---|---|---|
ScalingService | Main | Enqueue jobs to Bull queue |
Bull Queue | Redis | Job queue and state management |
JobProcessor | Worker | Consume and execute jobs |
Publisher/Subscriber | All | Command and event distribution |
Sources: packages/cli/src/scaling/scaling.service.ts packages/cli/src/scaling/pubsub/publisher.service.ts packages/cli/src/scaling/pubsub/subscriber.service.ts
Execution Flow:
Sources: packages/cli/src/scaling/scaling.service.ts packages/cli/src/commands/worker.ts165-172
Configuration:
Sources: packages/@n8n/config/src/configs/executions.config.ts packages/@n8n/config/src/configs/scaling-mode.config.ts
The execution mode is determined by the executions.mode configuration at startup:
Sources: packages/cli/src/commands/start.ts193-221 packages/cli/src/commands/worker.ts64-69 packages/cli/src/commands/webhook.ts44-59
In queue mode, n8n supports running multiple main instances for high availability. This requires a valid license with the MULTIPLE_MAIN_INSTANCES feature.
Multi-Main Features:
Configuration:
Sources: packages/@n8n/config/src/configs/multi-main-setup.config.ts packages/cli/src/commands/start.ts205-227
The execution mode and CLI behavior are controlled via environment variables, managed by the GlobalConfig class.
Sources: packages/@n8n/config/src/index.ts69-232 packages/@n8n/config/src/configs/executions.config.ts
| Config Class | Environment Prefix | Purpose |
|---|---|---|
ExecutionsConfig | N8N_EXECUTIONS_* | Execution mode and behavior |
ScalingModeConfig | N8N_QUEUE_* | Queue/Redis configuration |
EndpointsConfig | N8N_ENDPOINT_* | HTTP endpoint paths |
TaskRunnersConfig | N8N_RUNNERS_* | Task runner configuration |
GenericConfig | N8N_* | Generic settings (timezone, shutdown) |
Sources: packages/@n8n/config/src/configs/executions.config.ts packages/@n8n/config/src/configs/scaling-mode.config.ts packages/@n8n/config/src/configs/endpoints.config.ts packages/@n8n/config/src/configs/runners.config.ts packages/@n8n/config/src/configs/generic.config.ts
Configuration is accessed via dependency injection:
Sources: packages/cli/src/commands/base-command.ts63 packages/cli/src/commands/worker.ts67
Some configuration can be changed at runtime via the E2E controller (test environments only):
The setQueueMode handler in E2EController mutates ExecutionsConfig.mode directly on the container-resolved instance, toggling between 'regular' and 'queue' at runtime for test isolation.
Sources: packages/cli/src/controllers/e2e.controller.ts222-226
The variables API is an Enterprise Edition (EE) feature that provides named, persistent environment variables accessible in workflow expressions via $vars.<name>.
| Layer | Component | Path |
|---|---|---|
| Controller | VariablesController | packages/cli/src/environments.ee/variables/variables.controller.ee.ts |
| Registration | registerAdditionalControllers() | packages/cli/src/server.ts |
| License gate | License.isVariablesEnabled() | packages/cli/src/license.ts |
| Frontend setting | FrontendSettings.variables.limit | @n8n/api-types/src/frontend-settings.ts |
The controller is dynamically imported during server startup inside a try/catch to handle the case where the EE module is unavailable:
await import('@/environments.ee/variables/variables.controller.ee');
Sources: packages/cli/src/server.ts143-148
Variables are enabled when the instance holds the feat:variables license feature flag. The license also controls the maximum number of variables via a numeric quota. FrontendService.getSettings() sets variables.limit from the license:
if (this.license.isVariablesEnabled()) {
this.settings.variables.limit = this.license.getVariablesLimit();
}
The frontend uses variables.limit to enforce the cap in the UI. A limit of -1 means unlimited.
Sources: packages/cli/src/services/frontend.service.ts498-501 packages/cli/src/license.ts254-256
Variables are managed at /rest/variables. Typical CRUD operations include:
| Method | Path | Description |
|---|---|---|
GET | /rest/variables | List all variables |
POST | /rest/variables | Create a variable |
PATCH | /rest/variables/:id | Update a variable |
DELETE | /rest/variables/:id | Delete a variable |
Variables created here are available in any workflow expression as $vars.<variableName>.
The initialization sequence varies by command and execution mode:
| Initialization Step | Start (Regular) | Start (Queue) | Worker | Webhook |
|---|---|---|---|---|
| Database connection | ā | ā | ā | ā |
| License activation | ā | ā | ā | ā |
| Binary data service | ā | ā | ā | ā |
| Express server | ā | ā | ā | ā |
| UI static assets | ā | ā | ā | ā |
| Active workflows | ā | ā | ā | ā |
| Orchestration (Redis) | ā | ā | ā | ā |
| Scaling service (queue setup) | ā | ā | ā | ā |
| Scaling service (worker setup) | ā | ā | ā | ā |
| Multi-main setup | ā | ā (if enabled) | ā | ā |
| Task runner server | ā (if enabled) | ā (if enabled) | ā (if enabled) | ā |
| Community packages | ā | ā | ā | ā |
Sources: packages/cli/src/commands/start.ts189-269 packages/cli/src/commands/worker.ts74-126 packages/cli/src/commands/webhook.ts44-87
Sources: packages/@n8n/config/src/configs/executions.config.ts
Sources: packages/@n8n/config/src/configs/scaling-mode.config.ts
Sources: packages/@n8n/config/src/configs/scaling-mode.config.ts packages/@n8n/config/src/configs/endpoints.config.ts
Sources: packages/@n8n/config/src/configs/multi-main-setup.config.ts
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.