# How to Run OmniRoute from the Command Line: Complete CLI Setup

> Learn to run OmniRoute from the command line with our CLI setup guide. Easily launch the HTTP server and configure OmniRoute for your projects.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-09-11

---

**Run OmniRoute from the command line by executing `npx omniroute serve` after installing dependencies, which launches the HTTP server on port 20128 via the CLI entry point at `bin/omniroute.mjs`.**

OmniRoute is a self‑hosted AI proxy and router that exposes a dedicated command‑line interface for server management. According to the diegosouzapw/OmniRoute source code, the CLI is registered in [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json) and dispatches commands through a Node.js executable. This guide covers installation, configuration, and execution of the `omniroute` binary.

## Installation and Prerequisites

Before invoking the CLI, you must install Node.js dependencies and prepare the environment configuration.

### Install Dependencies

Clone the repository and install packages using the lockfile to ensure reproducible builds. This step prepares the `bin/omniroute.mjs` script and all runtime libraries required by the server.

```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute
npm ci

```

### Configure Environment Variables

Copy the example environment file to `.env` and set required secrets. The CLI reads variables such as `PORT`, `JWT_SECRET`, and `API_KEY_SECRET` at startup to initialize the router.

```bash
cp .env.example .env

# Edit .env to configure JWT_SECRET and API_KEY_SECRET

```

## Running the OmniRoute CLI

The [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json) file maps the `omniroute` command to `bin/omniroute.mjs`, enabling both local and global execution.

### Local Execution with npx

Run the CLI without a global installation by using `npx`, which resolves the binary from the local `node_modules` directory.

```bash
npx omniroute serve

```

### Global Installation

Install the package globally to invoke the `omniroute` command directly from any shell session. This registers the entry point from `bin/omniroute.mjs` in your system’s executable path.

```bash
npm install -g .
omniroute serve

```

### Custom Port Configuration

Override the default port by exporting the `PORT` environment variable before starting the server. The initialization logic in `bin/omniroute.mjs` consumes this value when binding the HTTP listener.

```bash
export PORT=8080
npx omniroute serve

```

## CLI Subcommands and Architecture

The `bin/omniroute.mjs` script parses arguments and dispatches to subcommand handlers. While `serve` starts the production server, additional administrative tasks—such as `reset` and `backup`—are available for database maintenance.

Once the CLI initializes, incoming requests are handled by Next.js API routes located in `src/app/api/v1/` and core logic in `open-sse/handlers/` that processes chat completions and embeddings.

## Summary

- **Install dependencies** with `npm ci` to prepare the runtime environment.
- **Execute the CLI** using `npx omniroute serve` or the globally installed `omniroute` command.
- **Configure secrets** in `.env` (copied from `.env.example`) including `PORT`, `JWT_SECRET`, and `API_KEY_SECRET`.
- **Default port** is 20128, overridable via the `PORT` environment variable.
- **Entry point** is `bin/omniroute.mjs`, registered in [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json) for npm binary resolution.
- **Request handling** is implemented in `src/app/api/v1/` and `open-sse/handlers/` as implemented in diegosouzapw/OmniRoute.

## Frequently Asked Questions

### What is the default port when I run OmniRoute from the command line?

The default port is **20128**. When you execute `npx omniroute serve` without setting the `PORT` environment variable, the server binds to this port as defined in the source configuration.

### How do I change the port when running OmniRoute CLI?

Set the `PORT` environment variable before invoking the command. For example, run `export PORT=8080` followed by `npx omniroute serve` to bind the server to port 8080 instead of the default.

### Where is the OmniRoute CLI entry point located in the source code?

The CLI entry point is `bin/omniroute.mjs`. This file contains the argument parsing logic and is registered in [`package.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/package.json) under the `bin` field, enabling the `omniroute` command through npm.

### Can I run OmniRoute CLI without installing dependencies globally?

Yes. After running `npm ci` to install local dependencies, you can execute `npx omniroute serve` to run the CLI without a global installation. The `npx` utility resolves the binary path automatically from the local `node_modules`.