ragent-cli 1.1.0

package/README.md

@@ -0,0 +1,139 @@
+# ragent-cli
+
+CLI agent for [rAgent Live](https://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
+
+```bash
+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:
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+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
+
+```bash
+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](../LICENSE)