CLI Reference

Manage your Uplink server from the command line.

Uplink ships with a CLI tool (uplink-chat) that handles starting, stopping, monitoring, and updating the server. If you installed globally via npm, the command is available everywhere. With npx, prefix commands with npx.

bash

uplink-chat [command] [options]

start

Start the Uplink server. This is the default command — running uplink-chat with no arguments is the same as uplink-chat start.

bash

# Foreground (default) — auto-restart via watchdog
uplink-chat

# Background (daemon mode)
uplink-chat start --detach

# Custom port
uplink-chat --port 8080

# Bind to specific host
uplink-chat --host 127.0.0.1

# Raw mode — no watchdog, no auto-restart
uplink-chat --no-watchdog

By default, Uplink starts with a watchdog that automatically restarts the server if it crashes. The watchdog uses exponential backoff (1s → 2s → 4s → max 30s) and resets after 60 seconds of stable uptime.

Option	Description	Default
`--port N`	Port to listen on	3456
`--host H`	Host/IP to bind to	0.0.0.0
`--detach`, `-d`	Run in background (daemon mode)	off
`--no-watchdog`	Disable auto-restart watchdog	off

💡 Foreground vs. Detached

In foreground mode (default), the server logs to your terminal and stops when you close it. In detached mode (-d), it runs silently in the background — ideal for always-on setups. Both modes include the watchdog by default.

stop

Stop a running Uplink server. Handles both foreground and daemon (watchdog) processes.

bash

uplink-chat stop

If the server was started with --detach, this stops the watchdog (which also stops the server). If it was started in foreground mode, it sends a SIGTERM to the server process directly.

status

Check whether Uplink is running and display process info.

bash

uplink-chat status

Example output when running in watchdog mode:

output

⬡ Uplink is running (watchdog mode)
  Watchdog PID: 12345
  Server PID:   12347
  Uptime:       2h 14m 30s
  Restarts:     0

If the server has crashed and restarted, you'll see the restart count and current backoff interval.

update

Update Uplink to the latest version from npm.

bash

uplink-chat update

The update command:

Checks the current version
Stops the server if it's running
Runs npm update -g @mooncompany/uplink-chat
Reports the version change (or confirms you're already up to date)
Restarts the server if it was running before the update

⚠ Permissions

If you installed Uplink globally with sudo, the update may also need elevated permissions. On macOS/Linux, use sudo uplink-chat update. On Windows, run your terminal as Administrator.

Other Flags

Flag	Description
`--version`, `-v`	Print the installed version and exit
`--help`, `-h`	Show usage help and exit

bash

# Check version
uplink-chat -v
# → uplink-chat v0.5.1

# Show help
uplink-chat --help

Watchdog

The watchdog is a lightweight supervisor that restarts the Uplink server if it exits unexpectedly. It's enabled by default in both foreground and detached modes.

Behavior	Value
Initial restart delay	1 second
Backoff multiplier	2×
Maximum backoff	30 seconds
Backoff reset after stable uptime	60 seconds
Clean exit (code 0) behavior	Does not restart

The watchdog writes its state to .uplink-watchdog.json in the Uplink root directory, which is how uplink-chat status reports uptime and restart counts.

To disable the watchdog entirely, pass --no-watchdog:

bash

uplink-chat --no-watchdog

Examples

Run on a different port

bash

uplink-chat --port 8080

Always-on daemon

bash

# Start in background
uplink-chat start -d

# Check on it later
uplink-chat status

# Stop when needed
uplink-chat stop

Quick one-off with npx

bash

# Run without installing
npx @mooncompany/uplink-chat

Update and restart

bash

# One command — stops, updates, restarts
uplink-chat update

Environment Variables

These can be used as alternatives to CLI flags:

Variable	Description	Equivalent Flag
`PORT`	Server port	`--port`
`UPLINK_HOST`	Bind address	`--host`

CLI flags take priority over environment variables.

Next Steps

Configuration — Customize Uplink via the Settings panel and config file
Voice Chat — Set up speech-to-text and text-to-speech
Remote Access — Access Uplink from other devices