---
title: 'CLI Reference'
description: 'Command-line reference for ecopages init, dev, build, and related commands.'
order: 2
---

import { CodeTabs } from '@/components/code-tabs';

# 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:

<CodeTabs
	name="cli-reference-run"
	tabs={[
		{ id: 'npm', label: 'npm', code: 'npx ecopages --help' },
		{ id: 'pnpm', label: 'pnpm', code: 'pnpm dlx ecopages --help' },
		{ id: 'bun', label: 'bun', code: 'bunx ecopages --help' },
	]}
	defaultSelectedKey="npm"
/>

Or install it in your app and run via scripts:

<CodeTabs
	name="cli-reference-install"
	tabs={[
		{ id: 'npm', label: 'npm', code: 'npm install ecopages' },
		{ id: 'pnpm', label: 'pnpm', code: 'pnpm add ecopages' },
		{ id: 'bun', label: 'bun', code: 'bun add ecopages' },
	]}
	defaultSelectedKey="npm"
/>

## 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](/docs/core/sitemap) locations, etc.).

1. **CLI flag**: `--base-url <url>`.
2. **`ConfigBuilder.setBaseUrl()`**: Set directly in `eco.config.ts`.
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`.

| 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

<CodeTabs
	name="cli-reference-help"
	tabs={[
		{ id: 'npm', label: 'npm', code: 'npx ecopages --help' },
		{ id: 'pnpm', label: 'pnpm', code: 'pnpm dlx ecopages --help' },
		{ id: 'bun', label: 'bun', code: 'bunx ecopages --help' },
	]}
	defaultSelectedKey="npm"
/>

### Initialize a template app

<CodeTabs
	name="cli-reference-init"
	tabs={[
		{ id: 'npm', label: 'npm', code: 'npx ecopages init ecopages-app' },
		{ id: 'pnpm', label: 'pnpm', code: 'pnpm dlx ecopages init ecopages-app' },
		{ id: 'bun', label: 'bun', code: 'bunx ecopages init ecopages-app' },
	]}
	defaultSelectedKey="npm"
/>

### Run development server

<CodeTabs
	name="cli-reference-dev"
	tabs={[
		{ id: 'npm', label: 'npm', code: 'npx ecopages dev' },
		{ id: 'pnpm', label: 'pnpm', code: 'pnpm dlx ecopages dev' },
		{ id: 'bun', label: 'bun', code: 'bunx ecopages dev' },
	]}
	defaultSelectedKey="npm"
/>

### Build for production with a specific base URL

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

### Start the production server

```bash
pnpm dlx ecopages start --runtime node
```