cli-serve

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

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

Subcommands

dashboard

Flags:

• --url
• --port <port>
• --tui

Example:

AIRoute dashboard

restart

Flags:

• --port <port>

Example:

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:

AIRoute serve

stop

Example:

AIRoute stop

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

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

Requires Node.js ≥22.22.2 or ≥24.

Verify:

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

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

For a remote server:

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:

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

# 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 for install + global flags.

Server lifecycle

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

AIRoute setup                        # Step-by-step interactive setup

Non-interactive (CI / Docker)

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

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:

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

Backup & restore

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

Autostart (system tray / startup)

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:

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

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

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

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

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