cli

RUDI CLI — Agent Instructions

Local capability CLI, daemon lifecycle manager, and MCP router for RUDI. Node.js, plain JavaScript. Package: @learnrudi/cli.

RUDI owns local tools, secrets, package/index state, MCP access, durable artifacts, safe workspaces, and bounded detached-launch lifecycle. Claude, Codex, Gemini, and other native hosts own normal model execution, sessions, transcripts, and provider-native orchestration.

Command Surface

The default help is deliberately divided into four groups. Keep new commands in the narrowest appropriate group and update the command-surface contract tests when the grouping changes.

Core

Advanced

Internal

Retired names

apply, db, database, import, logs, par, parallel, project, projects, run-group, run-groups, session, and sessions are bounded migration notices. They exit nonzero and never load retired runtime code. Do not reintroduce implementations or compatibility routes behind these names.

Architecture

src/index.js
├── src/commands/                 CLI validation, dispatch, presentation
├── src/agent-host/               provider adapters and launch/workspace core
├── src/daemon/                   loopback HTTP API and lifecycle runtime
├── src/router-mcp.js             installed-stack MCP router
└── packages/*                    reusable installer/runner/env/MCP packages

Important boundaries:

The active home connection files are ~/.rudi/daemon.port and ~/.rudi/daemon.token. The loopback API uses x-rudi-token; never put tokens in URLs or logs.

Daemon Contract

Canonical sources:

Retained route families are:

Removed /agent/*, /sessions/*, filesystem, shell, terminal, analytics, notes, projects, plans, and WebSocket sidecar contracts must return the normal authenticated 404. Do not add compatibility adapters.

Agent Integration

MCP config, managed instructions, and native skill projections are separate:

Discover installed stacks with rudi list stacks --json or inspect ~/.rudi/cache/tool-index.json. Rebuild with rudi index --json. Do not use or document rudi mcp --list; it is unsupported.

Registry

Verification

Use the repository commands, not ad hoc substitutes:

pnpm test
pnpm build
node scripts/agent-debt-runner.mjs --changed-since origin/main --no-log
npm pack --dry-run

After editing JS/TS, run the focused debt scan described by the global instructions. Build output under dist/ is tracked; refresh it in a dedicated build commit. CI in .github/workflows/quality.yml enforces tests, build reproducibility, changed-file debt scanning, and package contents.

Documentation maintenance

The change author owns documentation impact; the reviewer checks it before acceptance. Update the current guide in the same change as observable behavior, commands, contracts, schema, configuration or operating procedures. A dated compliance record is evidence, not a replacement for current guidance.

Changed surface Current documentation to review
Commands, flags, installation, runtime requirements README.md, docs/cli-layout-and-installation.md, package.json
Native hosts, registered tasks, permissions docs/frontier-agent-hosts.md, docs/agent-task-execution.md, docs/compute-trusted-access.md
Daemon routes docs/rudi-local-daemon-architecture.md; generate docs/daemon/openapi.json from src/contracts/daemon-openapi.js
Registry/runtime or Compute bridge compatibility The owning Registry/Compute contract and the affected CLI guide; record the peer revision inspected