CLI Reference

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

Run it with bunx (recommended for one-off usage):

bunx ecopages --help

Or install it in your app and run via scripts:

bun add ecopages

Commands

Ecopages supports app lifecycle and scaffolding commands.

`init`

Scaffolds a new Ecopages project.

Supports interactive setup and templates.
Example: ecopages init my-app --template starter-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 .eco 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.
Behaves like the start command but triggers a build first.

`start`

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

Does not watch files for changes.
optimized for performance.

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

Global Flags

These flags can be appended to any command to override default behavior.

Flag	Type	Description
`--dev`	`boolean`	Forces development mode regardless of the command.
`--build`	`boolean`	Forces build mode regardless of the command.
`--preview`	`boolean`	Forces preview mode regardless of the command.
`--react-fast-refresh`	`boolean`	Enables React Fast Refresh during development.

Server Flags

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

Flag	Environment Variable	Description
`-p, --port`	`ECOPAGES_PORT`	Server port (default `3000`)
`-n, --hostname`	`ECOPAGES_HOSTNAME`	Server hostname
`-b, --base-url`	`ECOPAGES_BASE_URL`	Public base URL
`-d, --debug`	`ECOPAGES_LOGGER_DEBUG`	Enable debug logs
`-r, --react-fast-refresh`	-	Enable React Fast Refresh

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, sitemaps, etc.).

ConfigBuilder.setBaseUrl(): Highest priority. Set directly in eco.config.ts.
ECOPAGES_BASE_URL: Environment variable override.
Default: http://localhost:3000.

Server Hostname & Port

Used to determine where the server listens.

serverOptions: Highest priority. Passed to the EcopagesApp constructor.
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`

Example Usage

Show CLI help

bunx ecopages --help

Initialize a starter app

bunx ecopages init ecopages-app

Run development server

bunx ecopages dev

Build for production with a specific base URL

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

Start the production server

NODE_ENV=production bunx ecopages start