CLI

The Vendure CLI is a command-line tool for boosting your productivity as a developer by automating common tasks such as creating new plugins, entities, API extensions and more.

It is much more than just a scaffolding tool - it is able to analyze your project and intelligently modify your existing codebase to integrate new functionality.

Installation

To manually install the CLI, run:

npm install -D @vendure/cli

Interactive vs Non-Interactive Mode

The Vendure CLI supports both interactive and non-interactive modes:

• Interactive mode: Provides guided prompts and menus for easy use during development
• Non-interactive mode: Allows direct command execution with arguments and options, perfect for automation, CI/CD, and AI agents

For guidance on using the CLI together with project instructions for AI coding agents, see the AI-assisted development guide.

The Add Command

The add command is used to add new entities, resolvers, services, plugins, and more to your Vendure project.

Interactive Mode

From your project's root directory, run:

npx vendure add

The CLI will guide you through the process of adding new functionality to your project.

The add command is much more than a simple file generator. It is able to analyze your project source code to deeply understand and correctly update your project files.

Non-Interactive Mode

For automation or when you know exactly what you need to add, you can use the non-interactive mode with specific arguments and options:

# Create a new pluginnpx vendure add -p MyPlugin# Add an entity to a pluginnpx vendure add -e MyEntity --selected-plugin MyPlugin# Add an entity with featuresnpx vendure add -e MyEntity --selected-plugin MyPlugin --custom-fields --translatable# Add a service to a pluginnpx vendure add -s MyService --selected-plugin MyPlugin# Add a service with specific typenpx vendure add -s MyService --selected-plugin MyPlugin --type entity# Add job queue support to a pluginnpx vendure add -j MyPlugin --name my-job --selected-service MyService# Add GraphQL codegen to a pluginnpx vendure add -c MyPlugin# Add API extension to a pluginnpx vendure add -a MyPlugin --queryName getCustomData --mutationName updateCustomData# Add Dashboard extensions to a pluginnpx vendure add -d MyPlugin# Use custom config filenpx vendure add -p MyPlugin --config ./custom-vendure.config.ts

Add Command Options

Sub-options for specific commands

Entity (-e) additional options:

• --selected-plugin <n>: Name of the plugin to add the entity to (required)
• --custom-fields: Add custom fields support to the entity
• --translatable: Make the entity translatable

Service (-s) additional options:

• --selected-plugin <n>: Name of the plugin to add the service to (required)
• --type <type>: Type of service: basic or entity (default: basic)

Job Queue (-j) additional options:

• --name <name>: Name for the job queue (required)
• --selected-service <name>: Service to add the job queue to (required)

API Extension (-a) additional options: (requires either)

• --queryName <n>: Name for the GraphQL query
• --mutationName <n>: Name for the GraphQL mutation

The Migrate Command

The migrate command is used to generate and manage database migrations for your Vendure project.

Interactive Mode

From your project's root directory, run:

npx vendure migrate

Non-Interactive Mode

For migration operations, use specific arguments and options:

# Generate a new migrationnpx vendure migrate -g my-migration-name# Run pending migrationsnpx vendure migrate -r# Revert the last migrationnpx vendure migrate --revert# Generate migration with custom output directorynpx vendure migrate -g my-migration -o ./custom/migrations

Migrate Command Options

The Schema Command

The schema command allows you to generate a schema file for your Admin or Shop APIs, in either the GraphQL schema definition language (SDL) or as JSON.

This is useful when integrating with GraphQL tooling such as your IDE's GraphQL plugin.

Interactive Mode

From your project's root directory, run:

npx vendure schema

Non-Interactive Mode

To automate or quickly generate a schema in one command

# Create a schema file in SDL format for the Admin APInpx vendure schema --api admin# Create a JSON format schema of the Shop APInpx vendure schema --api shop --format json

Schema Command Options

The Doctor Command

The doctor command runs a series of diagnostic checks against your Vendure project and produces an actionable report. It is useful for debugging a misbehaving project, verifying an upgrade, onboarding a new machine, or as a guard rail in CI.

Unlike the other commands, doctor is non-interactive only - it runs all applicable checks and prints a report:

npx vendure doctor

What gets checked

By default, the following checks run in order:

The Production check is not run by default - enable it with --profile production (see below).

Example output

Vendure DoctorProject         pass  Vendure config found at src/vendure-config.tsDependencies    pass  All dependency checks passedConfig          pass  Vendure config loaded and validated successfullySchema          pass  Admin and Shop schemas generated successfullyDatabase        pass  Successfully connected to postgres databaseResult: passed

Each check reports one of four statuses: pass, warn, fail, or skip.

Running specific checks

Use --check to run only a subset of checks. The flag is variadic, so list the check names after it:

# Run only the dependencies and config checksnpx vendure doctor --check dependencies config

Valid check names are: project, dependencies, config, schema, database.

Production profile

When preparing for a production deployment, run the production profile to surface unsafe settings:

npx vendure doctor --profile production

This adds a Production check that warns about settings such as disableAuth, default superadmin credentials, a missing cookie secret, enabled introspection/playground/debug, overly broad CORS, in-memory job queue/cache/session strategies, and missing asset storage.

Using in CI

For CI pipelines, combine --strict with --format json. The --strict flag treats warnings as failures, and the command exits with a non-zero code when the overall result is a failure - so a warning will fail your build:

# Fail the build on any warning or failure, and emit machine-readable outputnpx vendure doctor --strict --format json

Doctor Command Options

Working in Monorepos

The Vendure CLI automatically supports monorepo structures where packages have their own tsconfig.json files that extend a shared base configuration.

Requirements

For the CLI to work correctly in a monorepo, ensure that:

1. Each package containing a Vendure config has its own tsconfig.json that extends the root config
2. Path mappings are defined in your root tsconfig.json

Example Setup

A typical monorepo structure:

my-monorepo/├── tsconfig.json             # Root config with path mappings├── packages/│   └── vendure-app/│       ├── tsconfig.json     # Extends root config│       └── src/│           └── vendure-config.ts└── libs/    └── shared/        └── src/            └── index.ts

Root tsconfig.json:

{    "compilerOptions": {        "baseUrl": ".",        "paths": {            "@my-org/shared": ["libs/shared/src/index.ts"]        }    }}

Package packages/vendure-app/tsconfig.json:

{    "extends": "../../tsconfig.json",    "compilerOptions": {        "outDir": "./dist"    }}

How It Works

When you run CLI commands, it:

1. Locates the nearest tsconfig.json by walking up from your Vendure config file
2. Resolves the extends chain to merge all configurations
3. Registers path mappings so imports like @my-org/shared resolve correctly

Getting Help

To see all available commands and options:

npx vendure --helpnpx vendure add --helpnpx vendure migrate --helpnpx vendure schema --helpnpx vendure doctor --help