ragent-cli

CLI agent for rAgent Live — browser-first terminal control plane for AI coding agents.

Installs a lightweight connector on your Linux host that streams terminal sessions to the rAgent Live portal via WebSocket.

Requirements

• Node.js >= 20
• Linux (systemd recommended, pidfile fallback available)
• tmux (optional, for multi-session support)

Installation

npm install -g ragent-cli

Quick Start

1. In the rAgent Live portal, click Setup Host to generate an enrollment token.
2. On your Linux host:

ragent enroll \
  --portal "https://your-portal.example.com" \
  --token "your-enrollment-token" \
  --as-service

This enrolls the host, installs a background service, and starts streaming.

Commands

ragent enroll

Enroll a host using a short-lived enrollment token from the portal.

ragent enroll --token <token> [options]

| Option | Description | |--------|-------------| | --token <token> | (required) Enrollment token from portal | | --portal <url> | Portal base URL (default: http://localhost:3000) | | -i, --id <id> | Host ID (auto-detected from hostname) | | -n, --name <name> | Host display name (auto-detected from hostname) | | -c, --command <command> | Shell command to run (default: bash) | | --as-service | Install and start background service after enrollment | | --no-run | Enroll only; do not start the connector |

ragent run

Run the connector using saved credentials.

ragent run [options]

| Option | Description | |--------|-------------| | --portal <url> | Portal base URL | | --agent-token <token> | Agent token (uses saved token by default) | | -i, --id <id> | Host ID | | -n, --name <name> | Host name | | -c, --command <command> | Shell command to run |

ragent service

Manage the background connector service.

ragent service install [--start] [--no-enable]
ragent service start
ragent service stop
ragent service restart
ragent service status
ragent service logs [-n <lines>] [-f]
ragent service uninstall

Uses systemd user units when available, with a pidfile-based fallback.

ragent doctor

Run environment and connectivity checks.

ragent doctor [--portal <url>] [--fix]

Checks: platform, Node.js version, tmux, portal reachability. Use --fix to interactively install missing dependencies.

ragent update

Update the CLI from npm.

ragent update [--check]

Use --check to see if an update is available without installing.

ragent sessions list

List tmux sessions, windows, and panes on this host.

ragent sessions list

Configuration

Config is stored at ~/.config/ragent/config.json. The enroll command creates this automatically.

Environment Variables

| Variable | Description | |----------|-------------| | RAGENT_PORTAL | Default portal URL | | RAGENT_NO_ART | Set to true to disable ASCII art banners | | RAGENT_DISABLE_UPDATE_CHECK | Set to true to skip update checks | | NO_COLOR | Set to 1 to disable ANSI colors |

Development

cd cli
npm install
npm run build      # Build with tsup
npm run typecheck   # Type check with tsc
npm test           # Run vitest tests
npm run dev        # Watch mode

License

MIT