[Feature]: ocx link add to add a Home-initiated Remote Link Child from the CLI #6941

Area

CLI

What are you trying to accomplish?

Link several machines as Children of one Home from a terminal or an agent session, right after installing OpenCodex on each of them over SSH. In this session the install, version checks, PATH fixes and post-link verification were all scriptable; adding each Child was the only step that needed a browser.

What prevents this today?

The Add Child steps are management routes that accept only a dashboard session: /api/link/probe, /api/link/confirm-host and /api/link/apply all call auth(ctx, "dashboard") in src/server/management/link-routes.ts. The CLI has ocx link port|issue|status|revoke|reconnect, but nothing that performs the SSH handoff. ocx link issue prints the link key in plaintext and is marked human-only, so it is not a substitute. Each Child therefore takes four dialog steps in the dashboard, or browser automation.

What should OpenCodex do?

Add a CLI path for the same flow with the same safety gates:

• ocx link probe <alias> [--json] prints the offered host key fingerprint, key type and the Child's ocx --version.
• ocx link add <alias> --expect-fingerprint SHA256:... [--json] probes again, refuses on mismatch, confirms the host, applies, and reports the result. Without --expect-fingerprint it requires an interactive TTY confirmation, and refuses when stdin is not a TTY.
• It uses the same loopback admin authority as ocx link revoke and never prints the link key.
• It reports success only once the Child's data plane relays to the Home (see the separate bug about the Child runtime not restarting after a Home-initiated apply).

Example usage or interface

$ ocx link probe child-a --json
{"alias":"child-a","fingerprint":"SHA256:…","keyType":"ED25519","ocxVersion":"2.83.0"}

$ ocx link add child-a --expect-fingerprint SHA256:… --json
{"linkId":"lnk_…","alias":"child-a","state":"connected","childRole":"client"}

Alternatives or workarounds

Drive #remote with browser automation, which is what this session did.

Additional context

Fingerprint confirmation stays mandatory; the CLI only changes how the operator supplies it.

Checks

• I searched existing issues and documentation.
• This request describes a concrete OpenCodex workflow rather than merely naming a desired technology.
• I removed secrets and personal data.