# How to Run the pi-web Application After Setup: Complete CLI Guide

> Learn how to run the pi-web application using the CLI after setup. Execute the pi-web command to launch the Next.js server and open your browser automatically.

- Repository: [Alex Yang/pi-web](https://github.com/agegr/pi-web)
- Tags: how-to-guide
- Published: 2026-08-09

---

**Run the pi-web application by executing the `pi-web` CLI command after installation, which spawns a Next.js server on `http://127.0.0.1:30141` by default and automatically opens your browser.**

The pi-web application from the `agegr/pi-web` repository provides a browser-based UI for the pi coding-agent. After completing the setup, you launch the application through a command-line interface that handles Node version validation, option parsing, and Next.js server initialization. Understanding the boot sequence and available configuration flags ensures you can customize the server for local development or network exposure.

## Prerequisites and Node Version Validation

Before starting the application, ensure your environment meets the Node.js version requirements. The CLI entry point at [`bin/pi-web.js`](https://github.com/agegr/pi-web/blob/main/bin/pi-web.js) imports [`bin/node-version.js`](https://github.com/agegr/pi-web/blob/main/bin/node-version.js) to validate that the running Node version meets the minimum supported range (Node 22+). If the version check fails, the process aborts immediately with an error message.

Install the package globally to access the `pi-web` command system-wide:

```bash
npm install -g @agegr/pi-web@latest

```

Alternatively, run without installation using npx:

```bash
npx @agegr/pi-web@latest

```

## Starting the pi-web Server

When you execute `pi-web`, the script at [`bin/pi-web.js`](https://github.com/agegr/pi-web/blob/main/bin/pi-web.js) orchestrates the boot process through five distinct stages:

1. **Node version validation** – Confirms compatibility via [`bin/node-version.js`](https://github.com/agegr/pi-web/blob/main/bin/node-version.js).
2. **Parse launch options** – Transforms CLI flags and environment variables into configuration objects using `parseLaunchOptions()` from [`lib/pi-web-options.ts`](https://github.com/agegr/pi-web/blob/main/lib/pi-web-options.ts).
3. **Locate Next.js binary** – Resolves the `next` executable path from the package's `node_modules` directory.
4. **Spawn Next.js process** – Executes `node <next-bin> start -p <port> -H <hostname>` with piped stdio.
5. **Browser auto-launch** – Opens the default browser once Next.js prints "Ready" (unless disabled).

The server listens on `http://<hostname>:<port>` with defaults of `127.0.0.1:30141`.

## CLI Options and Environment Variables

The `parseLaunchOptions()` function in [`lib/pi-web-options.ts`](https://github.com/agegr/pi-web/blob/main/lib/pi-web-options.ts) accepts both command-line arguments and environment variables:

- **`--port` / `-p`** or **`PORT`** – Server port (default: `30141`)
- **`--hostname` / `-H`** or **`HOST`** – Bind address (default: `127.0.0.1`)
- **`--no-open`** or **`PI_WEB_NO_OPEN`** – Disable automatic browser opening
- **`PI_WEB_PASSWORD`** – Enable HTTP Basic Auth (username: `pi`)

Command-line flags take precedence over environment variables. The function uses `minimist` to parse arguments:

```typescript
// lib/pi-web-options.ts
export function parseLaunchOptions() {
  const args = minimist(process.argv.slice(2), {
    alias: { p: "port", H: "hostname", "no-open": "noOpen" },
    default: { 
      port: process.env.PORT ?? 30141, 
      hostname: process.env.HOST ?? "127.0.0.1", 
      openBrowser: !(process.env.PI_WEB_NO_OPEN) 
    },
  });
  return { 
    port: String(args.port), 
    hostname: String(args.hostname), 
    openBrowser: Boolean(args.openBrowser) 
  };
}

```

## Common Usage Examples

Run the server with default settings:

```bash
pi-web

```

Customize the port and disable browser auto-open:

```bash
pi-web --port 8080 --no-open

```

Expose on all network interfaces with Basic Auth protection:

```bash
PI_WEB_PASSWORD='secure-random-string' pi-web --hostname 0.0.0.0

```

Use environment variables instead of flags:

```bash
PORT=9090 HOST=0.0.0.0 PI_WEB_NO_OPEN=1 pi-web

```

## Security and Network Configuration

When exposing pi-web beyond localhost using `--hostname 0.0.0.0`, always enable Basic Auth to prevent unauthorized access. Set `PI_WEB_PASSWORD` to enforce authentication with username `pi`. The application handles the auth layer before serving the Next.js UI.

For proxy configurations, the application respects standard environment variables like `HTTP_PROXY` during the startup phase, though specific proxy handling depends on the underlying Node.js and Next.js network stack.

## Summary

- **Run** the pi-web application using the `pi-web` CLI command after global installation or via `npx @agegr/pi-web@latest`.
- **Default address** is `http://127.0.0.1:30141`, customizable via `--port` and `--hostname` flags or `PORT` and `HOST` environment variables.
- **Auto-browser** opens by default; disable with `--no-open` or `PI_WEB_NO_OPEN`.
- **Security** requires `PI_WEB_PASSWORD` when binding to `0.0.0.0` to enable Basic Auth with username `pi`.
- **Boot process** involves Node validation in [`bin/node-version.js`](https://github.com/agegr/pi-web/blob/main/bin/node-version.js), option parsing in [`lib/pi-web-options.ts`](https://github.com/agegr/pi-web/blob/main/lib/pi-web-options.ts), and Next.js spawning in [`bin/pi-web.js`](https://github.com/agegr/pi-web/blob/main/bin/pi-web.js).

## Frequently Asked Questions

### What is the default port and host for pi-web?

By default, pi-web binds to `127.0.0.1` on port `30141`. You can override these values using the `--port` and `--hostname` CLI flags, or by setting the `PORT` and `HOST` environment variables before executing the command.

### How do I prevent pi-web from automatically opening a browser?

Pass the `--no-open` flag when starting the server, or set the `PI_WEB_NO_OPEN` environment variable to any truthy value. The `parseLaunchOptions()` function in [`lib/pi-web-options.ts`](https://github.com/agegr/pi-web/blob/main/lib/pi-web-options.ts) checks for these conditions to disable the browser launch behavior that normally triggers when Next.js reports "Ready".

### Can I run pi-web without installing it globally?

Yes. Use `npx @agegr/pi-web@latest` to download and execute the latest version without permanent installation. This command performs the same Node version validation and boot sequence as the globally installed CLI.

### How do I secure pi-web with password protection?

Set the `PI_WEB_PASSWORD` environment variable when launching the application. This enables HTTP Basic Authentication with the fixed username `pi` and your chosen password. Always use this setting when exposing the server to the network via `--hostname 0.0.0.0` to prevent unauthorized access to the coding-agent UI.