CLI Reference

The Ecopages CLI is the canonical command-line interface for scaffolding, developing, building, and serving Ecopages apps.

Run it with your package manager's one-off executor:

npx ecopages --help

Or install it in your app and run via scripts:

npm install ecopages

Commands

Ecopages supports app lifecycle and scaffolding commands.

`init <dir>`

Scaffolds a new Ecopages project.

Requires a target directory and supports selecting a template.
Example: ecopages init my-app --template jsx.

`dev`

Starts the development server.

Enables Hot Module Replacement (HMR).
Enables file watching for automatic reloads.
Uses http://localhost:3000 by default (unless overridden).

`dev:watch`

Starts the development server with restart-on-change behavior.

`dev:hot`

Starts the development server with hot reload behavior.

`build`

Generates a static production build of your project.

Pre-renders all static pages in src/pages.
Optimizes assets and images.
Outputs the build to the dist directory.
Strips development-only code.

`preview`

Builds your project and starts a local production server for testing.

Useful for verifying the production build before deployment.
Rebuilds dist first, then serves that output locally.

`start`

Starts the production server using the existing build in the dist directory.

Does not watch files for changes.
optimized for performance.

Note: Commands that accept [entry] default to app.ts when omitted.

Server Flags

These flags are supported by server commands and map to environment variables.

Flag	Environment Variable	Description
`-p, --port <port>`	`ECOPAGES_PORT`	Server port (default `3000`)
`-n, --hostname <host>`	`ECOPAGES_HOSTNAME`	Server hostname
`-b, --base-url <url>`	`ECOPAGES_BASE_URL`	Public base URL
`-d, --debug`	`ECOPAGES_LOGGER_DEBUG`	Enable debug logs
`-r, --react-fast-refresh`	-	Enable React Fast Refresh
`--runtime <runtime>`	-	Force execution via `bun`, `node`, or `node-experimental`

Environment Variables

Ecopages listens to environment variables for configuration. When these are set, they often override defaults, but specific rules apply for precedence.

Canonical Base URL

Used for generating absolute URLs in production builds (meta tags, sitemap locations, etc.).

CLI flag: --base-url <url>.
ConfigBuilder.setBaseUrl(): Set directly in eco.config.ts.
ECOPAGES_BASE_URL: Environment variable override when the config does not set it explicitly.
Default: http://localhost:3000.

Server Hostname & Port

Used to determine where the server listens.

serverOptions: Highest priority. Passed to createApp() options.
Environment Variables: ECOPAGES_PORT and ECOPAGES_HOSTNAME.
Defaults: localhost:3000.

Variable	Description	Default
`ECOPAGES_BASE_URL`	The canonical base URL of your site.	`http://localhost:3000`
`ECOPAGES_PORT`	The port the server listens on.	`3000`
`ECOPAGES_HOSTNAME`	The hostname the server binds to.	`localhost`
`ECOPAGES_LOGGER_DEBUG`	Enables verbose debug logging.	`false`

Note: CLI server flags map to environment overrides before the runtime process starts. This lets one-off commands change host, port, base URL, or runtime without editing eco.config.ts.

Example Usage

Show CLI help

npx ecopages --help

Initialize a template app

npx ecopages init ecopages-app

Run development server

npx ecopages dev

Build for production with a specific base URL

ECOPAGES_BASE_URL=https://my-site.com pnpm dlx ecopages build

Start the production server

pnpm dlx ecopages start --runtime node

Getting Started

Core Concepts

Server

Integrations

Ecosystem

Extending

Reference