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:

Or install it in your app and run via scripts:

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.

build

Generates the production build of your project.

• Pre-renders all static pages in src/pages.
• Imports each endpoint file (*.api.ts, or .api.tsx, .api.js, .api.jsx) and checks its exports before bundling the server; a broken file fails the build, and --keep-going does not skip this check.
• Bundles the server into dist/server/ when the app registers API or WebSocket handlers or has endpoint files.
• Optimizes assets and images.
• Writes public files to dist/client/ and private server files, when needed, to dist/server/ under the configured output directory.
• Strips development-only code.
• Empties the configured output directory and renders every Page from source on each run; the command takes no option to reuse earlier output.
• By default, exits with status 1 after exporting the remaining pages if a Page fails to render. Pass --keep-going to retain the earlier log-and-continue behavior.

preview

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

• Useful for verifying the production build before deployment.
• Runs the same build as build first, then serves dist/client/ locally.
• Pass --serve-only (or set ECOPAGES_PREVIEW_SERVE_ONLY=true) to serve an existing client build without rebuilding or modifying dist/. This mode does not start the app's server runtime, so it serves built client files without API routes.

start

Starts the production server using the existing build. It needs a server bundle, and only apps that register API or WebSocket handlers or have endpoint files build one. A static-only app has no server bundle, so start stops and says so when dist/client/ (or the selected --dist-dir output's client/) holds built HTML; serve it with preview, or deploy dist/client/ to a static host. start does not read distDir from eco.config.ts. It runs the only <dir>/server/manifest.json one level below the app root, including dot-prefixed output directories such as .output. With none it asks you to run ecopages build, and with several it fails and lists them. Pass --dist-dir <dir> to choose one, which is also needed for a nested output such as out/web or a symlinked directory. An app that builds several outputs, such as dist-<scope> per build target, therefore needs --dist-dir for a plain start.

• Does not watch files for changes.
• optimized for performance.

types

Writes the types for virtual modules such as ecopages:images and ecopages:content/*, then exits.

• Processors generate these types in setup(). The types command runs that setup to write virtual-module declarations; production start restores Processor state from emitted server modules and does not call setup().
• It loads eco.config.ts (or the file given with --config), as astro sync does, and sets the processors up, so image optimization and the first PostCSS pass run too. Your entry file (app.ts) does not run.
• Run it before the type checker: "typecheck": "ecopages types && tsc --noEmit". The official templates ship that script.

Note: The entry file defaults to app.ts; override it with --entry-file <file>. A positional entry argument is refused.

Server Flags

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

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.).

1. CLI flag: --base-url <url>.
2. baseUrl in eco.config.ts: Set directly via defineConfig({ baseUrl: '...' }).
3. ECOPAGES_BASE_URL: Environment variable override when the config does not set it explicitly.
4. Default: http://localhost:3000.

Server Hostname & Port

Used to determine where the server listens.

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

When the preferred port is already in use, ecopages dev and ecopages preview can bind the next free port. TTY sessions ask for confirmation. Non-interactive sessions scan automatically only for the default port; a port pinned with --port or ECOPAGES_PORT fails instead.

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

Initialize a template app

Run development server

Build for production with a specific base URL

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

Start the production server

pnpm dlx ecopages start --runtime nodeCopy