{"record":{"id":"0641146b560be99c","repo":"ruvnet/ruflo","slug":"cannot-locate-the-ruflo-cli-entrypoint-for-supervi","errorCode":null,"errorMessage":"cannot locate the ruflo CLI entrypoint for supervised service mode","messagePattern":"cannot locate the ruflo CLI entrypoint for supervised service mode","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/cli/src/proxy/lifecycle.ts","lineNumber":222,"sourceCode":" * `ruflo` invocation, redirecting stdout/stderr to a real log file (not\n * buffered in-process). Returns once the child's PID is confirmed written,\n * without waiting for the process to exit.\n */\nexport async function startBackground(): Promise<{ pid: number }> {\n  requireBinary();\n  const status = getProxyStatus();\n  if (status.running && status.pid) throw new ProxyAlreadyRunningError(status.pid);\n\n  const lockFd = acquireStartLock();\n  try {\n    // Re-check under the lock — the dedup above raced a concurrent starter.\n    const rechecked = getProxyStatus();\n    if (rechecked.running && rechecked.pid) throw new ProxyAlreadyRunningError(rechecked.pid);\n    if (rechecked.stalePidFile) clearStalePidFile();\n\n    const logFd = fs.openSync(proxyLogFilePath(), 'a');\n    const cliEntry = process.argv[1];\n    if (!cliEntry) throw new Error('cannot locate the ruflo CLI entrypoint for supervised service mode');\n    const child = spawn(process.execPath, [cliEntry, 'proxy', 'supervise'], {\n      stdio: ['ignore', logFd, logFd],\n      detached: true,\n      windowsHide: true,\n    });\n    fs.closeSync(logFd); // the child holds its own duplicated fd; safe to close ours\n\n    if (!child.pid) throw new Error('ruflo proxy supervisor failed to spawn — no PID returned');\n    writePidFile(child.pid);\n    child.unref();\n    return { pid: child.pid };\n  } finally {\n    releaseStartLock(lockFd);\n  }\n}\n\nexport interface StopResult {\n  wasRunning: boolean;","sourceCodeStart":204,"sourceCodeEnd":240,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/cli/src/proxy/lifecycle.ts#L204-L240","documentation":"startBackground() re-execs the CLI as `node <cliEntry> proxy supervise`, taking the entrypoint from process.argv[1]. When argv[1] is empty — Node invoked without a script path — the CLI cannot locate itself for supervised service mode and aborts. This indicates ruflo is being driven through a non-standard entrypoint rather than its bin.","triggerScenarios":"Calling startBackground() programmatically from code embedding the CLI as a library where process.argv[1] is undefined; launch contexts like `node -e`, REPLs, or wrappers that strip argv entries.","commonSituations":"Custom automation importing lifecycle functions directly instead of shelling out to `ruflo`; test harnesses that stub or truncate process.argv; patched runtimes/bundlers altering argv.","solutions":["Invoke the CLI the normal way: run `ruflo proxy start --service` from a shell","If calling programmatically, set process.argv[1] to the resolved ruflo bin path before calling startBackground()","Prefer spawning `ruflo proxy start --service` as a subprocess from host code rather than importing internals"],"exampleFix":"// before (argv[1] missing, e.g. node -e / library context)\nawait startBackground(); // throws 'cannot locate the ruflo CLI entrypoint'\n// after\nprocess.argv[1] = createRequire(import.meta.url).resolve('@claude-flow/cli/bin/ruflo');\nawait startBackground();","handlingStrategy":"validation","validationCode":"if (!process.argv[1]) {\n  throw new Error('startBackground needs a CLI entrypoint — run `ruflo proxy start --service` instead');\n}\nawait startBackground();","typeGuard":"const isMissingEntrypoint = (e: unknown): e is Error =>\n  e instanceof Error && /cannot locate the ruflo CLI entrypoint/.test(e.message);","tryCatchPattern":"try {\n  await startBackground();\n} catch (e) {\n  if (isMissingEntrypoint(e)) {\n    // fall back to spawning the CLI as a subprocess instead of embedding\n    spawnSync('ruflo', ['proxy', 'start', '--service'], { stdio: 'inherit' });\n  } else throw e;\n}","preventionTips":["Prefer shelling out to `ruflo proxy start --service` over importing lifecycle internals","In embedded contexts, set process.argv[1] to the resolved bin path before calling startBackground()","Avoid REPL / `node -e` entrypoints for service-mode operations"],"tags":["proxy","service-mode","node-argv","embedded-usage"],"backgroundTag":"missing-cli-entrypoint","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","contentChangedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}