Cli Serve

---
name: cli-serve
description: Start, stop, and restart the AIRoute server from the CLI. Manage daemon mode, port configuration, auto-recovery, system tray integration, and the dashboard open shortcut.
---
<!-- generated by src/lib/agentSkills/generator.ts; manual edits will be overwritten -->

## Overview

Start, stop, and restart the AIRoute server from the CLI. Manage daemon mode, port configuration, auto-recovery, system tray integration, and the dashboard open shortcut.

## Quick install

```bash
npm install -g AIRoute   # or: npx AIRoute
AIRoute --version
```

## Subcommands

### `dashboard`

**Flags:**

- `--url`
- `--port <port>`
- `--tui`

**Example:**

```bash
AIRoute dashboard
```

### `restart`

**Flags:**

- `--port <port>`

**Example:**

```bash
AIRoute restart
```

### `serve`

**Flags:**

- `--port <port>`
- `--no-open`
- `--daemon`
- `--log`
- `--no-recovery`
- `--max-restarts <n>`
- `--tray`
- `--no-tray`
- `--tls-cert <path>`
- `--tls-key <path>`

**Example:**

```bash
AIRoute serve
```

### `stop`

**Example:**

```bash
AIRoute stop
```

<!-- skill:custom-start -->
<!-- Aggregated from: AIRoute-cli (setup + index), AIRoute-cli-admin (lifecycle/setup/backup/tunnel) -->

## Setup

The `AIRoute` binary ships with the AIRoute server. It is both the server launcher and a full management CLI with 250+ commands across 39 groups.

### Install

```bash
npm install -g AIRoute          # npm registry
# or: use the binary bundled with the desktop app
```

Requires Node.js ≥22.22.2 or ≥24.

Verify:

```bash
AIRoute --version   # prints installed version
AIRoute --help      # full command tree
```

### Connection

Every CLI command that talks to the server reads two values:

| Source   | Variable / Flag                      |
| -------- | ------------------------------------ |
| Base URL | `AIRoute_BASE_URL` or `--base-url` |
| API key  | `AIRoute_API_KEY` or `--api-key`   |

Default base URL: `http://localhost:20128`

```bash
export AIRoute_BASE_URL="http://localhost:20128"
export AIRoute_API_KEY="sk-..."          # from Dashboard → API Manager
```

For a remote server:

```bash
export AIRoute_BASE_URL="https://your-server.com"
```

### Global flags

| Flag                | Description                                              |
| ------------------- | -------------------------------------------------------- |
| `--base-url <url>`  | Override server URL for this invocation                  |
| `--api-key <key>`   | Override API key for this invocation                     |
| `--output <format>` | Output format: `table` (default), `json`, `jsonl`, `csv` |
| `--json`            | Shorthand for `--output json`                            |
| `--non-interactive` | Disable prompts — for CI / shell scripts                 |
| `--no-open`         | Don't auto-open the browser on start                     |
| `--port <n>`        | Override default port 20128                              |
| `--help`, `-h`      | Show help for the current command                        |
| `--version`, `-v`   | Print the installed version                              |

### Output formats

All listing commands support `--output`:

```bash
AIRoute combo list                      # human-readable table
AIRoute combo list --output json        # JSON array
AIRoute combo list --output jsonl       # one JSON object per line
AIRoute combo list --output csv         # CSV with header row
```

### Quick start: one-shot server + provider setup

```bash
# 1. Start server
AIRoute

# 2. (First run) interactive setup wizard
AIRoute setup

# 3. Verify everything is healthy
AIRoute doctor
```

### CLI capability skills

| Capability                           | Skill                                                                                                 |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| Server admin + backup                | https://raw.githubusercontent.com/diegosouzapw/AIRoute/main/skills/AIRoute-cli-admin/SKILL.md     |
| Provider & key management            | https://raw.githubusercontent.com/diegosouzapw/AIRoute/main/skills/AIRoute-cli-providers/SKILL.md |
| Cloud agents (Codex / Devin / Jules) | https://raw.githubusercontent.com/diegosouzapw/AIRoute/main/skills/AIRoute-cli-cloud/SKILL.md     |
| Evals & benchmarking                 | https://raw.githubusercontent.com/diegosouzapw/AIRoute/main/skills/AIRoute-cli-eval/SKILL.md      |

### Errors

- `Connection refused` → server not running; run `AIRoute` or `AIRoute serve`
- `401 Unauthorized` → wrong or missing API key
- `command not found: AIRoute` → not in PATH; check `npm root -g` or re-install
- `doctor` reports SQLite incompatible → `npm rebuild better-sqlite3` in the app directory

## Admin lifecycle

Requires the `AIRoute` CLI. See [CLI entry-point skill](https://raw.githubusercontent.com/diegosouzapw/AIRoute/main/skills/AIRoute-cli/SKILL.md) for install + global flags.

### Server lifecycle

```bash
AIRoute                              # Start server (default port 20128)
AIRoute serve                        # Explicit alias
AIRoute --port 3000                  # Override port
AIRoute --no-open                    # Don't auto-open browser
AIRoute --mcp                        # Start as MCP server (stdio transport)

AIRoute stop                         # Stop the running server
AIRoute restart                      # Restart the server

AIRoute dashboard                    # Open dashboard in browser
AIRoute open                         # Alias for dashboard
AIRoute status                       # Runtime status (uptime, requests, providers)
```

### Setup & provisioning

#### Interactive wizard

```bash
AIRoute setup                        # Step-by-step interactive setup
```

#### Non-interactive (CI / Docker)

```bash
AIRoute setup --non-interactive \
  --password 'admin-password' \
  --add-provider \
  --provider openai \
  --api-key 'sk-...' \
  --test-provider
```

Environment variables for non-interactive setup:

| Variable                      | Purpose                                      |
| ----------------------------- | -------------------------------------------- |
| `AIRoute_SETUP_PASSWORD`    | Admin password (≥8 chars)                    |
| `AIRoute_PROVIDER`          | Provider id (e.g. `openai`, `anthropic`)     |
| `AIRoute_PROVIDER_NAME`     | Display name for the connection              |
| `AIRoute_PROVIDER_BASE_URL` | Optional OpenAI-compatible base URL override |
| `AIRoute_API_KEY`           | Provider API key                             |
| `AIRoute_DEFAULT_MODEL`     | Optional default model                       |
| `DATA_DIR`                    | Override AIRoute data directory            |

### Diagnostics

```bash
AIRoute doctor                       # Full health check
AIRoute doctor --json                # Machine-readable JSON
AIRoute doctor --no-liveness         # Skip HTTP health probe
AIRoute doctor --host 0.0.0.0        # Override liveness host
AIRoute doctor --liveness-url <url>  # Full URL override
```

Checks performed: Config, Database, Storage/encryption, Port, Node runtime, Native binary (better-sqlite3), Memory, Server liveness.

Exit code is non-zero if any check fails — useful in CI:

```bash
AIRoute doctor --json | jq '.checks[] | select(.status=="fail")'
```

### Backup & restore

```bash
AIRoute backup                       # Snapshot config + SQLite DB to ~/.AIRoute/backups/
AIRoute restore                      # Restore from a previous snapshot (interactive picker)
```

### Autostart (system tray / startup)

```bash
AIRoute autostart enable             # Register AIRoute as a system startup item
AIRoute autostart disable            # Remove startup registration
AIRoute autostart status             # Show current autostart state
```

On Linux: creates a **systemd user service** (`~/.config/systemd/user/AIRoute.service`) and enables **linger** so the service can start after reboot without a graphical login; on desktop sessions it also adds an XDG autostart entry with `--tray`. On macOS: LaunchAgent plist. On Windows: registry startup entry.

### Tunnels (public URL)

Expose a local AIRoute instance via a secure tunnel:

```bash
AIRoute tunnel list                  # List active tunnels
AIRoute tunnel create cloudflare     # Start a Cloudflare Tunnel (free)
AIRoute tunnel create tailscale      # Start a Tailscale funnel
AIRoute tunnel create ngrok          # Start an ngrok tunnel
AIRoute tunnel stop <id>             # Stop a running tunnel
```

The tunnel URL is printed and can be used as `AIRoute_BASE_URL` from remote machines.

### Config & environment

```bash
AIRoute config show                  # Display current effective configuration
AIRoute env show                     # List all AIRoute environment variables
AIRoute env get <KEY>                # Get a single env var value
AIRoute env set <KEY> <value>        # Set an env var (temporary — until restart)
```

### Recovery

```bash
AIRoute reset-password               # Reset the admin password interactively
AIRoute reset-encrypted-columns      # Dry-run: show encrypted credential columns
AIRoute reset-encrypted-columns --force  # Null out encrypted credentials in SQLite
```

Use `reset-encrypted-columns --force` only if `STORAGE_ENCRYPTION_KEY` was lost and you need to re-enter all provider API keys.

### Logs

```bash
AIRoute logs                         # Stream live request logs
AIRoute logs --json                  # JSON log entries
AIRoute logs --search <term>         # Filter by term
AIRoute logs --follow                # Tail mode (keep streaming)
```

### Update

```bash
AIRoute update                       # Check for a newer version and prompt to update
```

### Errors

- `doctor` shows `STORAGE_ENCRYPTION_KEY missing` → set the key in `.env` or run `reset-encrypted-columns --force` to wipe and re-enter credentials
- `doctor` reports native binary fail → `npm rebuild better-sqlite3` in the AIRoute app directory
- `tunnel create cloudflare` hangs → ensure `cloudflared` is installed: `brew install cloudflare/cloudflare/cloudflared`
<!-- skill:custom-end -->