@rocon/cli — rocon

ROC ON's personal-worker CLI. Installed per technician on their own laptop; holds the technician's personal LLM credentials in the OS keychain.

M4.2 v0.1. This release adds personal-worker connection + task execution. The CLI can now connect to a paired runner and execute tasks via the @rocon/worker core. Pairing flow (rocon login) arrives in M4.3.

Install

npm install -g @rocon/cli

Once published. For local development:

pnpm --filter @rocon/cli build
npm install -g ./packages/cli/rocon-cli-0.1.0.tgz   # after `npm pack`

After install, smoke-check it:

rocon --version
rocon doctor

rocon doctor verifies that the @napi-rs/keyring native module loads on this platform and that a store/read/delete round-trip against the OS keychain succeeds.

Configure a runtime

rocon configure

Interactive wizard — pick one of the 8 supported runtimes (architecture-decisions.md §7) and enter what it needs. Non-interactive form:

rocon configure anthropic-api

You'll be prompted only for that runtime's fields.

Supported runtimes

| Runtime | Type | What you provide | |---|---|---| | Claude Code | Subscription | (optional) path to the claude CLI | | Codex CLI | Subscription | (optional) path to the codex CLI | | Gemini CLI | Subscription | (optional) path to the gemini CLI | | Anthropic API | API key | Anthropic API key (stored in the OS keychain) | | OpenAI API | API key | OpenAI API key (stored in the OS keychain) | | Google API | API key | Google API key (stored in the OS keychain) | | Custom | Endpoint + (optional) key | Azure OpenAI / Bedrock / vLLM endpoint URL, optional key | | Local | Local endpoint | Ollama / LM Studio URL (default http://localhost:11434) |

Credential-handling boundary

| Datum | Lives where | Never goes to | |---|---|---| | Personal LLM credentials (API keys) | OS keychain, service rocon-cli | Runner, cloud, log files, config.json | | Connect token (M4.2/M4.3) | OS keychain, account __pw_binding__:connectToken | Cloud storage (transits once during pairing) | | Runner websocket URL | OS keychain, account __pw_binding__:runnerWsUrl | — | | Endpoint URLs / CLI binary paths | ~/.rocon/config.json | Anywhere else | | Active-runtime label + per-runtime metadata | ~/.rocon/config.json | — | | Task logs / results | Transient in-memory; streamed to runner | Disk, cloud storage | | Anything else | nowhere — this CLI does not store task content or audit data | — |

Backed by @napi-rs/keyring (Windows Credential Manager / macOS Keychain Services / Linux Secret Service). See knowledge/P2-project/M4-0-foundation-design.md §3 for the decision, and spikes/m4-0-keychain/ for the original Windows spike.

Override the config directory by setting ROCON_HOME=<path>. Useful for portable installs and tests; the OS keychain entries are global per user regardless.

Commands

| Command | What it does | Since | |---|---|---| | rocon configure [runtimeId] | Pick a runtime, prompt for credentials, store them | M4.1 | | rocon doctor | Verify keychain + config + configured runtimes | M4.1 | | rocon connect | Start the personal worker and keep it connected to the runner | M4.2 | | rocon status | Show connection state and pairing info | M4.2 | | rocon run [--prompt=<text>] | Exercise a local test task (smoke-test / debugging) | M4.2 | | rocon --version | Print the CLI version | M4.1 | | rocon --help | Print usage | M4.1 |

M4.2 workflow

1. (M4.3) Pair with your runner: rocon login — device-code flow, stores the connect token in the OS keychain.
2. Start the worker: rocon connect — opens an outbound websocket to the runner, receives tasks, executes them via @rocon/worker, streams results back. Blocks until interrupted (Ctrl+C) or the binding is revoked.
3. Check status: rocon status — shows pairing state, runtime config, and last-connected timestamp.

Task execution uses the same @rocon/worker core as the service-account worker (architecture-decisions.md §12). No persistent state beyond the keychain — transient task data only.

Tests

pnpm --filter @rocon/cli typecheck
pnpm --filter @rocon/cli test
pnpm --filter @rocon/cli test:keychain-live   # talks to the real OS keychain

Unit tests use an in-memory keychain backend; the live test exercises the real OS keychain. Manual install verification on Windows is captured in WINDOWS-VERIFICATION.md.