robopark 2.8.35 → 3.0.0

package/dist/robopark-cli.js

@@ -0,0 +1,799 @@
+/**
+ * RoboPark CLI entry point (shipped as `infinicode/robopark` and `robopark`).
+ *
+ * A thin operator layer over the infinicode mesh. Keeps product concerns
+ * (scheduler, fleet UI, video sessions, InfiniBot map) separate from the
+ * execution kernel.
+ */
+import { Command } from 'commander';
+import chalk from 'chalk';
+import Conf from 'conf';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { roboparkScan } from './robopark/scan.js';
+import { roboparkServe } from './robopark/serve.js';
+import { roboparkSetup } from './robopark/setup.js';
+import { stopAll } from './robopark/stop-all.js';
+import { roboparkDoctor } from './robopark/doctor.js';
+import { roboparkAddRobot } from './robopark/add-robot.js';
+import { saveHubProfile, clearHubProfile } from './robopark/profile.js';
+import { roboparkAgentUp, roboparkAgentDown, roboparkAgentLogs } from './robopark/agent-ctl.js';
+import { roboparkSecrets } from './robopark/secrets.js';
+import { roboparkRobotRuntime } from './robopark/robot-runtime.js';
+import { roboparkVisionDown, roboparkVisionRestart, roboparkVisionStatus, roboparkVisionUp, } from './robopark/vision-control.js';
+import { roboparkConversationDown, roboparkConversationInstall, roboparkConversationRestart, roboparkConversationStart, roboparkConversationStop, roboparkConversationUp, } from './robopark/conversation.js';
+import { roboparkScreenDown, roboparkScreenInstall, roboparkScreenRestart, roboparkScreenUp } from './robopark/screen-control.js';
+import { roboparkMotorDiscover, roboparkMotorDown, roboparkMotorRestart, roboparkMotorStatus, roboparkMotorStop, roboparkMotorTest, roboparkMotorUp, } from './robopark/motor-control.js';
+import { connectDevice, gatewayStart, printRuntimeStatus, runGatewayService, startDevice, superviseDevice, } from './robopark/standalone.js';
+import { requirePackageAccess } from './robopark/access.js';
+import { deploymentCommandSheet } from './robopark/deployment-commands.js';
+// Read the real version from package.json so `--version` never drifts from
+// what is actually installed (this was a hardcoded constant that went stale
+// across several releases — see the identical fix + comment in cli.ts).
+function pkgVersion() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    for (const rel of ['../package.json', '../../package.json']) {
+        try {
+            return JSON.parse(readFileSync(join(here, rel), 'utf8')).version ?? '0.0.0';
+        }
+        catch { /* try next */ }
+    }
+    return '0.0.0';
+}
+const config = new Conf({
+    // Preserve the deployed config location so packaging never forks an
+    // existing robot into a fresh identity/config namespace.
+    projectName: 'infinicode',
+    ...(process.env.ROBOPARK_CONFIG_DIR ? { cwd: process.env.ROBOPARK_CONFIG_DIR } : {}),
+});
+const program = new Command('robopark')
+    .description('RoboPark fleet control CLI — set up, watch, and drive talking robots')
+    .version(pkgVersion())
+    .option('--password <password>', 'one-time package activation password (prefer ROBOPARK_PACKAGE_PASSWORD)');
+program.hook('preAction', (_command, actionCommand) => {
+    // A valid gateway pairing token is itself the device bootstrap capability.
+    // connectDevice() records activation only after enrollment succeeds.
+    if (actionCommand.name() === 'connect' || actionCommand.name() === 'commands')
+        return;
+    requirePackageAccess(program.opts().password);
+});
+program
+    .command('commands')
+    .description('Print the exact gateway and persistent per-character deployment commands')
+    .option('--token <token>', 'include a gateway pairing token in the device command')
+    .option('--public-url <url>', 'include the gateway public/Tailscale URL')
+    .action((opts) => {
+    try {
+        console.log(deploymentCommandSheet({ version: pkgVersion(), ...opts }));
+    }
+    catch (err) {
+        console.error(chalk.red(`  ✗ command sheet failed: ${err?.message ?? err}`));
+        process.exitCode = 1;
+    }
+});
+const gateway = program
+    .command('gateway')
+    .description('Run the standalone RoboPark dashboard, scheduler, and device gateway');
+gateway
+    .command('start')
+    .description('Start the dashboard/gateway and print a one-line device connection token')
+    .option('--port <port>', 'gateway HTTP port', '8080')
+    .option('--host <host>', 'gateway bind host', '0.0.0.0')
+    .option('--public-url <url>', 'URL devices use to reach this gateway')
+    .option('--data-dir <dir>', 'durable gateway data directory')
+    .option('--no-open', 'do not open the dashboard')
+    .option('--foreground', 'keep the gateway attached to this terminal')
+    .action(async (opts) => {
+    try {
+        await gatewayStart(opts);
+    }
+    catch (err) {
+        console.error(chalk.red(`  ✗ gateway start failed: ${err?.message ?? err}`));
+        process.exitCode = 1;
+    }
+});
+program
+    .command('connect <token>')
+    .description('Register this device with a gateway using one copy/paste token')
+    .option('--name <name>', 'device name (defaults to hostname)')
+    .action(async (token, opts) => {
+    try {
+        await connectDevice(token, opts);
+    }
+    catch (err) {
+        console.error(chalk.red(`  ✗ connect failed: ${err?.message ?? err}`));
+        process.exitCode = 1;
+    }
+});
+program
+    .command('start')
+    .description('Persist and supervise this device camera/voice runtime')
+    .option('--voice', 'stream microphone audio and accept supervised voice sessions')
+    .option('--video', 'stream the selected camera')
+    .option('--character <id>', 'gateway character preset, e.g. vixen')
+    .option('--video-device <device>', 'camera selection', 'auto')
+    .option('--audio-device <device>', 'microphone selection', 'default')
+    .option('--width <px>', 'video width', '640')
+    .option('--height <px>', 'video height', '480')
+    .option('--fps <n>', 'video frame rate', '15')
+    .option('--foreground', 'run the supervisor in this terminal')
+    .action(async (opts) => {
+    try {
+        await startDevice(opts);
+    }
+    catch (err) {
+        console.error(chalk.red(`  ✗ start failed: ${err?.message ?? err}`));
+        process.exitCode = 1;
+    }
+});
+program
+    .command('status')
+    .description('Show the local supervisor state')
+    .action(() => {
+    try {
+        printRuntimeStatus();
+    }
+    catch (err) {
+        console.error(chalk.red(`  ✗ status failed: ${err?.message ?? err}`));
+        process.exitCode = 1;
+    }
+});
+program
+    .command('_gateway', { hidden: true })
+    .option('--port <port>', 'gateway HTTP port', '8080')
+    .option('--host <host>', 'gateway bind host', '0.0.0.0')
+    .option('--data-dir <dir>', 'durable gateway data directory')
+    .action(async (opts) => {
+    try {
+        await runGatewayService({ ...opts, open: false, foreground: true });
+    }
+    catch (err) {
+        console.error(chalk.red(`  gateway service fatal: ${err?.message ?? err}`));
+        process.exitCode = 1;
+    }
+});
+program
+    .command('_supervise', { hidden: true })
+    .requiredOption('--config <path>')
+    .action(async (opts) => {
+    try {
+        await superviseDevice(opts.config);
+    }
+    catch (err) {
+        console.error(chalk.red(`  supervisor fatal: ${err?.message ?? err}`));
+        process.exitCode = 1;
+    }
+});
+const conversation = program
+    .command('conversation')
+    .description('Run a direct motion/voice-triggered ElevenLabs agent on robot hardware');
+conversation
+    .command('install')
+    .description('Idempotently install and verify Pi audio/Python dependencies')
+    .option('--with-vision', 'also install and verify RoboVision dependencies')
+    .option('--skip-apt', 'skip apt and only repair/verify the RoboPark Python environment')
+    .action(async (opts) => {
+    try {
+        await roboparkConversationInstall(opts);
+    }
+    catch (err) {
+        console.error(chalk.red(`  ✗ conversation install failed: ${err?.message ?? err}`));
+        process.exitCode = 1;
+    }
+});
+conversation
+    .command('up')
+    .description('Arm motion and local voice triggers, then join the configured ElevenLabs agent')
+    .requiredOption('--agent-id <id>', 'ElevenLabs agent id')
+    .option('--branch-id <id>', 'pin conversations to an ElevenLabs agent branch')
+    .option('--api-key <key>', 'ElevenLabs API key (prefer ELEVENLABS_API_KEY)')
+    .option('--public-agent', 'agent does not require an API key')
+    .option('--always-on', 'join immediately and reconnect forever without waiting for a trigger')
+    .option('--name <name>', 'robot name (defaults to hostname)')
+    .option('--audio-input <device>', 'stable USB microphone name or ALSA/PyAudio device', 'Usb Audio Device: USB Audio')
+    .option('--audio-output <device>', 'stable USB speaker name or ALSA/PyAudio device', 'USB Audio Device: -')
+    .option('--no-motion', 'disable the local motion webhook')
+    .option('--no-voice-trigger', 'disable the local sound-level trigger')
+    .option('--motion-host <host>', 'motion webhook bind host', '127.0.0.1')
+    .option('--motion-port <port>', 'motion webhook port', '5057')
+    .option('--vision-url <url>', 'running RoboVision server to configure for motion', 'http://127.0.0.1:5000')
+    .option('--no-manage-vision', 'do not start and supervise the local RoboVision camera process')
+    .option('--camera-device <device>', 'RoboVision camera device (auto prefers /dev/robopark-camera)', 'auto')
+    .option('--voice-threshold <rms>', 'idle microphone RMS required to trigger', '900')
+    .option('--idle-timeout <sec>', 'end after this many seconds without a transcript; 0 disables', '120')
+    .option('--max-session <sec>', 'hard maximum conversation duration; 0 disables', '540')
+    .option('--cooldown <sec>', 'minimum delay before another session', '2')
+    .option('--motor <pin-name>', 'register motor/relay, e.g. 17-head (repeatable)', (value, previous) => [...previous, value], [])
+    .option('--motor-active-high', 'registered motor relays activate HIGH (default: active-low)')
+    .option('--motor-pulse-ms <ms>', 'default bounded motor pulse duration', '300')
+    .option('--no-provision-agent-tools', 'skip automatic ElevenLabs robotMotor tool creation/attachment')
+    .option('--auto-start', 'install and start a production systemd service')
+    .action(async (opts) => {
+    try {
+        await roboparkConversationUp(opts);
+    }
+    catch (err) {
+        console.error(chalk.red(`  ✗ conversation failed: ${err?.message ?? err}`));
+        process.exitCode = 1;
+    }
+});
+conversation
+    .command('stop')
+    .description('Stop local conversation workers without deleting their configuration')
+    .option('--name <name>', 'explicit service override (normally unnecessary)')
+    .action((opts) => {
+    try {
+        roboparkConversationStop(opts.name);
+    }
+    catch (err) {
+        console.error(chalk.red(`  ✗ conversation stop failed: ${err?.message ?? err}`));
+        process.exitCode = 1;
+    }
+});
+conversation
+    .command('start')
+    .description('Start the selected local conversation worker and wait for real readiness')
+    .option('--name <name>', 'explicit service override (normally unnecessary)')
+    .option('--trigger', 'trigger one conversation after readiness')
+    .action(async (opts) => {
+    try {
+        await roboparkConversationStart(opts.name, Boolean(opts.trigger));
+    }
+    catch (err) {
+        console.error(chalk.red(`  ✗ conversation start failed: ${err?.message ?? err}`));
+        process.exitCode = 1;
+    }
+});
+conversation
+    .command('down')
+    .description('Stop and remove the direct conversation auto-start service')
+    .option('--name <name>', 'robot name (defaults to hostname)')
+    .action((opts) => {
+    try {
+        roboparkConversationDown(opts.name);
+    }
+    catch (err) {
+        console.error(chalk.red(`  ✗ conversation stop failed: ${err?.message ?? err}`));
+        process.exitCode = 1;
+    }
+});
+conversation
+    .command('restart')
+    .description('Cleanly restart a production conversation worker and wait until it is ready')
+    .option('--name <name>', 'explicit service override (normally unnecessary)')
+    .option('--trigger', 'trigger one conversation after readiness')
+    .action(async (opts) => {
+    try {
+        await roboparkConversationRestart(opts.name, Boolean(opts.trigger));
+    }
+    catch (err) {
+        console.error(chalk.red(`  ✗ conversation restart failed: ${err?.message ?? err}`));
+        process.exitCode = 1;
+    }
+});
+program
+    .command('scan')
+    .description('Auto-discover the fleet and print ready-to-run setup commands')
+    .option('--token <token>', 'mesh auth token to use')
+    .option('--output <dir>', 'write install scripts to this directory')
+    .option('--no-gateway', 'skip InfiniBot gateway in generated commands')
+    .action(async (opts) => {
+    await roboparkScan({
+        token: opts.token,
+        output: opts.output,
+        gateway: opts.gateway,
+    });
+});
+program
+    .command('probe')
+    .description('Dispatch opencode agents across the mesh to map infrastructure')
+    .option('--token <token>', 'mesh auth token (optional, for context)')
+    .option('--timeout <sec>', 'seconds per node', '60')
+    .option('--output <file>', 'write JSON results to this file')
+    .option('--local', 'probe only this machine')
+    .action(async (opts) => {
+    const { roboparkProbe } = await import('./robopark/probe.js');
+    await roboparkProbe(opts);
+});
+program
+    .command('setup-livekit')
+    .description('Dispatch an opencode agent on the hub to install LiveKit server via Docker')
+    .option('--hub-url <url>', 'hub federation URL, e.g. http://100.64.1.2:47913')
+    .option('--token <token>', 'mesh auth token')
+    .option('--scheduler-url <url>', 'scheduler URL to register the new server, e.g. http://100.64.1.2:8080')
+    .option('--timeout <sec>', 'max seconds to wait for the agent', '180')
+    .option('--dry-run', 'print the prompt instead of dispatching')
+    .action(async (opts) => {
+    const { roboparkSetupLivekit } = await import('./robopark/setup-livekit.js');
+    await roboparkSetupLivekit(opts);
+});
+program
+    .command('verify')
+    .description('Verify the RoboPark fleet is ready for live preview')
+    .option('--scheduler-url <url>', 'scheduler base URL, e.g. http://livekit-1:8080')
+    .option('--robot-id <id>', 'robot name to verify (defaults to hostname)')
+    .action(async (opts) => {
+    const { roboparkVerify } = await import('./robopark/verify.js');
+    await roboparkVerify(opts);
+});
+program
+    .command('serve')
+    .description('Start the RoboPark scheduler + web UI')
+    .option('--port <port>', 'scheduler HTTP port', '8080')
+    .option('--host <host>', 'scheduler bind host', '0.0.0.0')
+    .option('--data-dir <dir>', 'scheduler data directory')
+    .option('--gateway <url>', 'InfiniBot gateway ws:// URL')
+    .option('--gateway-token <token>', 'InfiniBot gateway token')
+    .option('--gateway-password <pw>', 'InfiniBot gateway password')
+    .option('--no-open', 'do not open the RoboPark Control Center in a browser')
+    .option('--foreground', 'stay in foreground; do not detach')
+    .action(async (opts) => {
+    await roboparkServe(opts);
+});
+program
+    .command('secrets')
+    .description('Provision the scheduler-managed ROBOVOICE authentication secret')
+    .option('--scheduler-url <url>', 'scheduler base URL', 'http://localhost:8080')
+    .option('--worker-env <path>', 'ROBOVOICE worker .env file', '.env')
+    .option('--rotate', 'rotate the shared secret before synchronizing it')
+    .action(async (opts) => {
+    try {
+        await roboparkSecrets(opts);
+    }
+    catch (err) {
+        console.error(chalk.red(`  ✗ secret provisioning failed: ${err?.message ?? err}`));
+        process.exitCode = 1;
+    }
+});
+program
+    .command('enroll')
+    .description('Enroll this robot/satellite with the RoboPark scheduler')
+    .option('--scheduler-url <url>', 'scheduler base URL', 'http://localhost:8080')
+    .option('--robot-id <id>', 'robot/device name (defaults to hostname)')
+    .option('--enrollment-token <token>', 'one-time enrollment token (or ENV ENROLLMENT_TOKEN)')
+    .option('--save-config', 'write settings to ~/.robopark/preview_agent.json')
+    .action(async (opts) => {
+    const { roboparkEnroll } = await import('./robopark/enroll.js');
+    await roboparkEnroll(opts);
+});
+program
+    .command('preview-agent')
+    .description('Start the robot-side preview agent (camera + mic to scheduler)')
+    .option('--scheduler-url <url>', 'scheduler base URL', 'http://localhost:8080')
+    .option('--robot-id <id>', 'robot/device name (defaults to hostname)')
+    .option('--device-token <token>', 'long-lived device token')
+    .option('--enrollment-token <token>', 'one-time enrollment token')
+    .option('--video-device <dev>', 'camera: auto, /dev/video0, 0, picamera', 'auto')
+    .option('--audio-device <dev>', 'microphone: default, none, or name/index', 'default')
+    .option('--robovision-url <url>', 'RoboVision base URL used for camera streaming and hardware inventory')
+    .option('--width <px>', 'video width', '640')
+    .option('--height <px>', 'video height', '480')
+    .option('--fps <n>', 'video fps', '15')
+    .option('--vision-webhook-port <port>', 'local port for RoboVisionAI_PI\'s motion webhook (0 disables)', '5057')
+    .option('--vision-trigger-cooldown <sec>', 'min seconds between motion-triggered sessions', '20')
+    .option('--vision-session-seconds <sec>', 'how long a motion-triggered session holds the publisher', '90')
+    .option('--save-config', 'write settings to ~/.robopark/preview_agent.json')
+    .option('--foreground', 'stay in foreground; do not detach')
+    .action(async (opts) => {
+    const { roboparkPreviewAgent } = await import('./robopark/preview-agent-launcher.js');
+    await roboparkPreviewAgent(opts);
+});
+program
+    .command('vision-agent')
+    .description('Start the robot-side camera/motion detector (RoboVisionAI_PI) — self-arms and wires to preview-agent\'s vision webhook')
+    .option('--port <port>', 'vision server port', '5000')
+    .option('--motion-webhook-url <url>', 'where to POST on motion (defaults to the local preview-agent\'s vision webhook, http://127.0.0.1:5057/)')
+    .option('--no-motion-active', 'do not arm motion detection on startup (armed by default)')
+    .option('--foreground', 'stay in foreground; do not detach')
+    .action(async (opts) => {
+    const { roboparkVisionAgent } = await import('./robopark/vision-agent-launcher.js');
+    await roboparkVisionAgent(opts);
+});
+const visionProgram = program
+    .command('vision')
+    .description('Register and operate an always-on robot camera feed independently of voice calls');
+const collectOption = (value, previous) => previous.concat(value);
+const motorProgram = program
+    .command('motor')
+    .description('Register and operate a persistent robot-local GPIO motor server');
+motorProgram.command('up <name>')
+    .description('Start the motor server and persist its safe relay registry')
+    .option('--token <token>', 'motor API token (defaults to the saved mesh token)')
+    .option('--port <port>', 'loopback motor API port', '8001')
+    .option('--motor <gpio-name>', 'register a relay, e.g. 17-head or 27-eyes:low', collectOption, [])
+    .option('--no-auto-start', 'run without registering the service at boot')
+    .action(async (name, opts) => {
+    try {
+        await roboparkMotorUp(name, opts);
+    }
+    catch (err) {
+        console.error(chalk.red(`  ✗ motor up failed: ${err?.message ?? err}`));
+        process.exitCode = 1;
+    }
+});
+motorProgram.command('status <name>')
+    .description('Show motor service, GPIO, and registry health')
+    .action(async (name) => {
+    try {
+        await roboparkMotorStatus(name);
+    }
+    catch (err) {
+        console.error(chalk.red(`  ✗ motor status failed: ${err?.message ?? err}`));
+        process.exitCode = 1;
+    }
+});
+motorProgram.command('discover <name>')
+    .description('Read the robot-local persisted motor registry')
+    .action(async (name) => {
+    try {
+        await roboparkMotorDiscover(name);
+    }
+    catch (err) {
+        console.error(chalk.red(`  ✗ motor discovery failed: ${err?.message ?? err}`));
+        process.exitCode = 1;
+    }
+});
+motorProgram.command('test <name> [motor]')
+    .description('Pulse one registered motor, or safely test all registered relays')
+    .option('--seconds <seconds>', 'pulse duration', '0.3')
+    .action(async (name, motor, opts) => {
+    try {
+        await roboparkMotorTest(name, motor, Number(opts.seconds));
+    }
+    catch (err) {
+        console.error(chalk.red(`  ✗ motor test failed: ${err?.message ?? err}`));
+        process.exitCode = 1;
+    }
+});
+motorProgram.command('stop <name>')
+    .description('Immediately de-energize all registered relays')
+    .action(async (name) => {
+    try {
+        await roboparkMotorStop(name);
+    }
+    catch (err) {
+        console.error(chalk.red(`  ✗ motor stop failed: ${err?.message ?? err}`));
+        process.exitCode = 1;
+    }
+});
+motorProgram.command('restart <name>')
+    .description('Cleanly restart the persistent motor server')
+    .action((name) => {
+    try {
+        roboparkMotorRestart(name);
+    }
+    catch (err) {
+        console.error(chalk.red(`  ✗ motor restart failed: ${err?.message ?? err}`));
+        process.exitCode = 1;
+    }
+});
+motorProgram.command('down <name>')
+    .description('Stop and remove the persistent motor server')
+    .action((name) => {
+    try {
+        roboparkMotorDown(name);
+    }
+    catch (err) {
+        console.error(chalk.red(`  ✗ motor down failed: ${err?.message ?? err}`));
+        process.exitCode = 1;
+    }
+});
+const screenProgram = program
+    .command('screen')
+    .description('Operate an authenticated internal noVNC desktop relay over the Infinicode mesh');
+screenProgram.command('install')
+    .description('Install Wayland/X11 VNC and noVNC relay dependencies on a Pi')
+    .action(() => { try {
+    roboparkScreenInstall();
+}
+catch (err) {
+    console.error(chalk.red(`  ✗ screen install failed: ${err?.message ?? err}`));
+    process.exitCode = 1;
+} });
+screenProgram.command('up <name>')
+    .description('Start and persist a loopback-only desktop relay for a robot')
+    .option('--desktop-user <user>', 'Linux desktop account to share')
+    .action(async (name, opts) => { try {
+    await roboparkScreenUp(name, opts.desktopUser);
+}
+catch (err) {
+    console.error(chalk.red(`  ✗ screen up failed: ${err?.message ?? err}`));
+    process.exitCode = 1;
+} });
+screenProgram.command('restart <name>')
+    .description('Restart a robot desktop relay')
+    .action((name) => { try {
+    roboparkScreenRestart(name);
+}
+catch (err) {
+    console.error(chalk.red(`  ✗ screen restart failed: ${err?.message ?? err}`));
+    process.exitCode = 1;
+} });
+screenProgram.command('down <name>')
+    .description('Stop and remove a robot desktop relay')
+    .action((name) => { try {
+    roboparkScreenDown(name);
+}
+catch (err) {
+    console.error(chalk.red(`  ✗ screen down failed: ${err?.message ?? err}`));
+    process.exitCode = 1;
+} });
+visionProgram
+    .command('up <name>')
+    .description('Start and persist a named camera relay using saved hub credentials')
+    .option('--hub-url <url>', 'hub mesh URL (defaults to `robopark hub-use` profile)')
+    .option('--token <token>', 'mesh token (defaults to `robopark hub-use` profile)')
+    .option('--character <id>', 'optional character preset associated with this robot')
+    .option('--video-device <dev>', 'camera selection', 'auto')
+    .option('--port <port>', 'robot mesh port', '47913')
+    .option('--lan', 'use LAN transport (default)')
+    .option('--tailscale', 'use Tailscale transport')
+    .option('--no-auto-start', 'run now without registering the feed at boot')
+    .action(async (name, opts) => {
+    try {
+        await roboparkVisionUp(config, name, opts);
+    }
+    catch (err) {
+        console.error(chalk.red(`  ✗ vision up failed: ${err?.message ?? err}`));
+        process.exitCode = 1;
+    }
+});
+visionProgram
+    .command('status <name>')
+    .description('Show the camera runtime and local feed status')
+    .action(async (name) => {
+    try {
+        await roboparkVisionStatus(name);
+    }
+    catch (err) {
+        console.error(chalk.red(`  ✗ vision status failed: ${err?.message ?? err}`));
+        process.exitCode = 1;
+    }
+});
+visionProgram
+    .command('restart <name>')
+    .description('Cleanly restart the persistent camera relay')
+    .action((name) => {
+    try {
+        roboparkVisionRestart(name);
+    }
+    catch (err) {
+        console.error(chalk.red(`  ✗ vision restart failed: ${err?.message ?? err}`));
+        process.exitCode = 1;
+    }
+});
+visionProgram
+    .command('down <name>')
+    .description('Stop and remove the persistent camera relay')
+    .action((name) => {
+    try {
+        roboparkVisionDown(name);
+    }
+    catch (err) {
+        console.error(chalk.red(`  ✗ vision down failed: ${err?.message ?? err}`));
+        process.exitCode = 1;
+    }
+});
+const robotProgram = program
+    .command('robot')
+    .description('Run the complete robot runtime as one supervised service');
+robotProgram
+    .command('up')
+    .description('Start mesh, RoboVision, audio, motion webhook, and preview agent in dependency order')
+    .requiredOption('--name <name>', 'robot name')
+    .requiredOption('--hub-url <url>', 'hub mesh URL, e.g. http://192.168.1.12:47913')
+    .requiredOption('--token <token>', 'shared mesh token')
+    .option('--scheduler-url <url>', 'scheduler URL (derived from --hub-url when omitted)')
+    .option('--enrollment-token <token>', 'one-time scheduler enrollment token for a fresh device')
+    .option('--character <id>', 'character preset assigned during canonical device bootstrap')
+    .option('--port <port>', 'robot mesh port', '47913')
+    .option('--lan', 'use LAN transport (default)')
+    .option('--tailscale', 'use Tailscale transport')
+    .option('--video-device <dev>', 'camera selection', 'auto')
+    .option('--audio-device <dev>', 'microphone selection', 'default')
+    .option('--device-role <role>', 'hardware role: combined | voice_vision | motor', 'combined')
+    .option('--no-vision', 'do not start RoboVision camera/audio/motion services')
+    .option('--foreground', 'keep logs in this terminal instead of ~/.robopark/logs')
+    .action(async (opts) => {
+    if (opts.lan && opts.tailscale)
+        throw new Error('choose exactly one of --lan or --tailscale');
+    if (!['combined', 'voice_vision', 'motor'].includes(opts.deviceRole))
+        throw new Error('device role must be combined, voice_vision, or motor');
+    await roboparkRobotRuntime({
+        name: opts.name,
+        hubUrl: opts.hubUrl,
+        schedulerUrl: opts.schedulerUrl ?? `${opts.hubUrl.replace(/\/+$/, '')}/robopark`,
+        token: opts.token,
+        port: opts.port,
+        network: opts.tailscale ? 'tailscale' : 'lan',
+        enrollmentToken: opts.enrollmentToken,
+        character: opts.character,
+        videoDevice: opts.videoDevice,
+        audioDevice: opts.audioDevice,
+        deviceRole: opts.deviceRole,
+        vision: opts.vision,
+        foreground: opts.foreground,
+    });
+});
+program
+    .command('stop')
+    .description('Stop every infinicode/robopark process on this device AND remove any supervisor (systemd/Task Scheduler/launchd) that would respawn it')
+    .action(async () => {
+    console.log(chalk.bold('\n  robopark stop\n  ' + '─'.repeat(48)));
+    try {
+        const result = await stopAll();
+        if (result.killedPids.length)
+            console.log(chalk.green(`  ✓ killed ${result.killedPids.length} process(es): ${result.killedPids.join(', ')}`));
+        else
+            console.log(chalk.dim('  no matching processes were running'));
+        if (result.removedUnits.length)
+            console.log(chalk.green(`  ✓ removed ${result.removedUnits.length} supervisor unit(s): ${result.removedUnits.join(', ')}`));
+        else
+            console.log(chalk.dim('  no supervisor units registered'));
+        for (const err of result.errors)
+            console.log(chalk.yellow(`  ! ${err}`));
+        console.log('');
+    }
+    catch (e) {
+        console.error('stop failed:', e instanceof Error ? (e.stack ?? e.message) : e);
+        process.exitCode = 1;
+    }
+});
+program
+    .command('doctor')
+    .description('Run a full fleet health check: hub, scheduler, LiveKit servers, device heartbeats, production mode')
+    .option('--hub-url <url>', 'hub federation URL, e.g. http://100.64.1.2:47913')
+    .option('--token <token>', 'mesh auth token')
+    .option('--scheduler-url <url>', 'scheduler base URL, e.g. http://100.64.1.2:8080')
+    .action(async (opts) => {
+    await roboparkDoctor(opts);
+});
+program
+    .command('server-add')
+    .description('Register a LiveKit server with the RoboPark scheduler')
+    .option('--hub-url <url>', 'hub federation URL, e.g. http://100.64.1.2:47913')
+    .option('--scheduler-url <url>', 'scheduler URL, e.g. http://100.64.1.2:8080 (derived from --hub-url if omitted)')
+    .option('--token <token>', 'mesh auth token (optional)')
+    .requiredOption('--id <id>', 'unique server id, e.g. livekit-hub-docker')
+    .option('--name <name>', 'display name (defaults to --id)')
+    .requiredOption('--url <url>', 'LiveKit ws:// URL, e.g. ws://100.64.1.2:7880')
+    .option('--webhook-url <url>', 'internal http URL for health/metrics (defaults to --url with ws->http)')
+    .option('--api-key <key>', "LiveKit API key (defaults to 'devkey')")
+    .option('--api-secret <secret>', "LiveKit API secret (defaults to 'secret')")
+    .option('--max-sessions <n>', 'max concurrent sessions', '8')
+    .action(async (opts) => {
+    const { roboparkServerAdd } = await import('./robopark/server-add.js');
+    await roboparkServerAdd(opts);
+});
+program
+    .command('llm-set')
+    .description('Upsert LLM_PROVIDER/OLLAMA_* keys into a ROBOVOICE .env file')
+    .requiredOption('--env-path <path>', 'path to the target .env file (e.g. a ROBOVOICE checkout)')
+    .requiredOption('--provider <name>', 'ollama | ollama-cloud | groq')
+    .option('--model <name>', 'model name (ollama providers only)')
+    .option('--host <url>', 'Ollama server URL (ollama providers only)')
+    .option('--api-key <key>', 'API key for cloud auth (ollama-cloud; currently unused by ROBOVOICE — see CLI warning)')
+    .action(async (opts) => {
+    const { roboparkLlmSet } = await import('./robopark/llm-set.js');
+    await roboparkLlmSet(opts);
+});
+program
+    .command('hub-use')
+    .description('Save hub/scheduler/token/site as defaults so other commands stop needing them repeated')
+    .option('--hub-url <url>', 'hub federation URL, e.g. http://100.64.1.2:47913')
+    .option('--token <token>', 'shared mesh token')
+    .option('--scheduler-url <url>', 'scheduler base URL, e.g. http://100.64.1.2:8080')
+    .option('--site <site>', 'physical location, e.g. "Tel Aviv"')
+    .option('--clear', 'wipe the saved hub profile')
+    .action(async (opts) => {
+    if (opts.clear) {
+        clearHubProfile();
+        console.log(chalk.green('  ✓ cleared saved hub profile'));
+        return;
+    }
+    saveHubProfile({ hubUrl: opts.hubUrl, token: opts.token, schedulerUrl: opts.schedulerUrl, site: opts.site });
+    console.log(chalk.green('  ✓ saved hub profile to ~/.robopark/hub-profile.json'));
+});
+program
+    .command('add-robot <name>')
+    .description('Mint a scheduler enrollment token and print (or run) the robot setup one-liner')
+    .option('--site <site>', 'physical location, e.g. "Tel Aviv"')
+    .option('--hub-url <url>', 'hub federation URL (defaults to saved hub profile / auto-discovery)')
+    .option('--token <token>', 'shared mesh token (defaults to saved hub profile / auto-discovery)')
+    .option('--scheduler-url <url>', 'scheduler base URL (defaults to saved hub profile / auto-discovery)')
+    .option('--character <id>', 'force a specific park-map pad/character preset id (default: fuzzy-matched from the robot name)')
+    .option('--lan', 'generate a robot command for the same local network (default)')
+    .option('--tailscale', 'generate a robot command for a Tailscale-reachable hub')
+    .option('--start', 'start the robot node on this machine now, instead of printing the one-liner')
+    .option('--auto-start', 'register the robot runtime to start on boot')
+    .option('--yes', 'non-interactive production setup')
+    .action(async (name, opts) => {
+    await roboparkAddRobot(config, { name, ...opts });
+});
+program
+    .command('agent-up')
+    .description('Start the ROBOVOICE docker stack and register its LiveKit server with the scheduler')
+    .requiredOption('--path <dir>', 'path to the ROBOVOICE checkout (contains docker-compose.yaml)')
+    .option('--scheduler-url <url>', 'scheduler URL (defaults to resolved hub context)')
+    .option('--hub-url <url>', 'hub URL (defaults to resolved hub context)')
+    .option('--token <token>', 'mesh token')
+    .option('--server-id <id>', "server id to register (default: 'robovoice-<hostname>')")
+    .option('--server-name <name>', 'server display name')
+    .option('--no-register', 'bring up docker only; skip scheduler registration')
+    .action(roboparkAgentUp);
+program
+    .command('agent-down')
+    .description('Stop the ROBOVOICE docker stack')
+    .requiredOption('--path <dir>', 'path to the ROBOVOICE checkout')
+    .action(roboparkAgentDown);
+program
+    .command('agent-logs')
+    .description('Tail ROBOVOICE docker compose logs')
+    .requiredOption('--path <dir>', 'path to the ROBOVOICE checkout')
+    .option('-f, --follow', 'follow log output')
+    .option('--service <name>', 'scope logs to one compose service (e.g. agent, livekit)')
+    .action(roboparkAgentLogs);
+program
+    .command('setup')
+    .description('Set up this device in one pass')
+    .option('--hub', 'this device is the on-site hub')
+    .option('--robot', 'this device is a robot')
+    .option('--control', 'this device is a control station')
+    .option('--voice-vision', 'this Windows device owns voice and vision')
+    .option('--motor-node', 'this Pi owns motors only')
+    .option('--role <role>', 'explicit role: hub | robot | voice-vision | motor | control')
+    .option('--name <name>', 'device name (defaults to hostname)')
+    .option('--site <site>', 'physical location, e.g. "Tel Aviv"')
+    .option('--hub-url <url>', 'hub base URL for robots/control')
+    .option('--token <token>', 'shared mesh token')
+    .option('--port <port>', 'mesh listen port', '47913')
+    .option('--gateway <url>', 'InfiniBot gateway ws:// URL')
+    .option('--gateway-token <token>', 'InfiniBot gateway token')
+    .option('--scheduler-port <port>', 'scheduler port on hub', '8080')
+    .option('--tailscale-auth <token>', 'Tailscale auth key for the hub')
+    .option('--tag <tag>', 'Tailscale tag filter')
+    .option('--enrollment-token <token>', 'one-time scheduler enrollment token for robots')
+    .option('--character <id>', 'character preset assigned during canonical device bootstrap')
+    .option('--lan', 'use LAN discovery and LAN hub/scheduler addresses (default for robots)')
+    .option('--tailscale', 'use Tailscale discovery and Tailscale hub/scheduler addresses')
+    .option('--video-device <dev>', 'default camera for robot preview agent', 'auto')
+    .option('--audio-device <dev>', 'default microphone for robot preview agent', 'default')
+    .option('--no-vision', 'do not start the vision (camera/motion trigger) agent for a robot — armed by default')
+    .option('--start', 'launch the node now')
+    .option('--auto-start', 'register to start on boot')
+    .option('--yes', 'non-interactive mode')
+    .action(async (opts) => {
+    const role = opts.role ?? (opts.hub ? 'hub' : opts.robot ? 'robot' : opts.voiceVision ? 'voice-vision' : opts.motorNode ? 'motor' : opts.control ? 'control' : undefined);
+    if (!role) {
+        console.log(chalk.red('  pass a role: --hub | --robot | --voice-vision | --motor-node | --control'));
+        process.exit(1);
+    }
+    if (!['hub', 'robot', 'voice-vision', 'motor', 'control'].includes(role))
+        throw new Error('invalid setup role');
+    await roboparkSetup(config, {
+        role,
+        name: opts.name,
+        site: opts.site,
+        hub: opts.hubUrl,
+        token: opts.token,
+        port: opts.port,
+        gateway: opts.gateway,
+        gatewayToken: opts.gatewayToken,
+        schedulerPort: opts.schedulerPort,
+        tailscaleAuth: opts.tailscaleAuth,
+        tag: opts.tag,
+        enrollmentToken: opts.enrollmentToken,
+        character: opts.character,
+        videoDevice: opts.videoDevice,
+        audioDevice: opts.audioDevice,
+        vision: opts.vision,
+        start: opts.start,
+        autoStart: opts.autoStart,
+        yes: opts.yes,
+        lan: opts.lan,
+        tailscale: opts.tailscale,
+    });
+});
+// Keep legacy fleet/run/apply/dashboard commands available while migrating.
+await program.parseAsync(process.argv);