CLI Overview

The ExpressoTS CLI (@expressots/cli) is a single binary that covers the full lifecycle of an ExpressoTS application: scaffolding, code generation, development, build, production, containerization, CI/CD pipelines, cost estimation, and Studio integration.

Binary names	Description
expressots	Primary command
ex	Short alias, interchangeable with expressots

Requirements

Requirement	Version
Node.js	>= 20.18.0
Package mgr	npm, yarn, pnpm, or bun (bun is unavailable on Windows for expressots new)

Installation

npm install -g @expressots/cli

You can also call it without installing globally via npx @expressots/cli .... Most templates pin @expressots/cli as a devDependency, so commands like npm run dev route through the local install.

Command catalogue

The CLI is grouped by what stage of the app's life it serves.

Scaffolding

Command	Alias	Purpose	Page
new	(none)	Create a new project from a template (application / micro)	new
generate	g	Scaffold a single resource (controller, use case, DTO, interceptor, event handler, guard, etc.)	generate
create	(none)	Scaffold a standalone provider package skeleton	providers

Running

Command	Alias	Purpose	Page
dev	(none)	Local dev server with tsx --watch. Optional --container flag for the Docker flow.	running
build	(none)	Compile to JavaScript with tsc. Rewrites alias imports in opinionated projects.	running
prod	(none)	Run the compiled output with node	running
container-dev	cdev, docker-dev	Compose-based dev workflow (start, stop, attach, shell, status, logs).	running

Dependencies

Command	Purpose	Page
add	Install an external provider (detects npm / yarn / pnpm via lockfile)	providers
remove	Uninstall an external provider	providers
scripts	Interactively run any script from package.json	scripts
studio	Launch ExpressoTS Studio; auto-installs @expressots/studio if missing	studio

Container & deployment

Command	Alias	Purpose	Page
containerize	c	Generate Dockerfiles, compose files, Kubernetes manifests	containerize
profile	prof, analyze	Lint a Dockerfile or built image and emit optimization recommendations	containerize
cicd	ci, pipeline	Generate CI/CD pipelines for GitHub Actions, GitLab CI, CircleCI, Jenkins, Bitbucket, Azure	cicd
migrate	mig, migration	Generate migration configurations between platforms (Heroku → Railway, Compose → K8s, etc.)	migrate
costs	cost, pricing	Estimate and compare cloud deployment costs	costs
templates	tpl	Manage the CI/CD / Docker / K8s template cache	templates

Diagnostics

Command	Alias	Purpose	Page
info	i	Print OS, Node, CLI bundle version, and project info from package.json	info
resources	r	Print the table of all commands and generate schematics (cheat sheet)	info
--help	(none)	yargs-generated help; works on every command (expressots <cmd> --help)	(none)

Conventions

These apply across the CLI:

Convention	Detail
No global --version	The CLI deliberately does not expose expressots --version. Use expressots info or npm list -g @expressots/cli.
expressots.config.ts is required	For dev, build, prod, and generate. The CLI walks up from cwd until it finds the file.
tsconfig.build.json with outDir	Required for build and prod. The CLI creates outDir if it doesn't exist.
Strict yargs mode	Unknown flags or commands fail fast, no silent typos.
A subcommand is always required	Running expressots with no arguments prints the help and exits.
The run command was removed	Use dev, build, or prod directly.
Path positional, not --module=	expressots g controller auth/user post, not expressots g controller --module=auth user.

expressots.config.ts

Every project the CLI manages keeps its configuration here. Generated by expressots new:

import { ExpressoConfig, Pattern } from "@expressots/shared";

export const config: ExpressoConfig = {
  scaffoldPattern: Pattern.KEBAB_CASE,
  sourceRoot: "src",
  entryPoint: "main",
  opinionated: true,
  scaffoldSchematics: {
    controller: "useCases",
    usecase: "useCases",
    dto: "useCases",
    module: "useCases",
    provider: "providers",
    entity: "entities",
    middleware: "middleware",
    interceptor: "interceptors",
    event: "events",
    handler: "events",
    guard: "guards",
    config: "config",
  },
};

export default config;

Field	Purpose
sourceRoot	Root the CLI scaffolds under (must be non-empty)
entryPoint	The file name in sourceRoot/ (without .ts) that dev/prod boots
opinionated	When true, generate places resources in the scaffoldSchematics folders and build rewrites @alias/* imports to relative paths in the emitted JS
scaffoldPattern	Naming convention for generated files: KEBAB_CASE (default), CAMEL_CASE, PASCAL_CASE, LOWER_CASE
scaffoldSchematics	Per-resource folder names. Custom folders are auto-added to tsconfig.json paths (and tsconfig.build.json in opinionated projects)

See Configuration File for the full surface.

Project layout the CLI assumes

my-app/
├── expressots.config.ts        # CLI configuration
├── tsconfig.json               # editor + dev tsconfig
├── tsconfig.build.json         # has `compilerOptions.outDir`; used by `build` / `prod`
├── package.json
└── src/
    ├── main.ts                 # entryPoint; calls bootstrap(App)
    ├── app.ts                  # extends AppExpress
    └── ...                     # generated into folders driven by scaffoldSchematics

Worked example

# 1. Scaffold a project with the application template, pnpm, and the API preset.
expressots new my-api --template application --package-manager pnpm --preset api

cd my-api

# 2. Scaffold a typed config file.
expressots g cfg app

# 3. Generate a full CRUD slice (controller + usecase + dto + module wiring).
expressots g s users/create post
expressots g s users/list get
expressots g s users/update put
expressots g s users/delete delete

# 4. Add an interceptor for response logging.
expressots g i Logging --priority 5

# 5. Add a domain event + handler.
expressots g ev UserCreated
expressots g h EmailWelcome --event UserCreated --priority 20

# 6. Run dev.
expressots dev

# 7. Build and run prod.
expressots build && expressots prod

---

Next

• new: create a project from a template.
• generate: scaffold a resource.
• running: dev, build, prod, and the Docker container workflow.
• providers: add, remove, create.
• studio: launch the Studio UI from the CLI.
• containerize, cicd, migrate, costs: production-ready DevOps artifacts.