help react-native recommends open --metro-host/--metro-port, but open rejects both flags

[wenchenyu-jhs]

Summary

agent-device help react-native in agent-device 0.19.3 recommends passing --metro-host and --metro-port to agent-device open, but the same CLI rejects both flags before app or device resolution.

Reproduction

$ agent-device --version
0.19.3

$ agent-device help react-native
Multiple local worktrees can reuse one native iOS simulator build by running each worktree's dev server on a different port and opening the same installed app on different simulators with explicit runtime hints:
  agent-device open "React Navigation Example" --platform ios --device "iPhone 17" --session rn-a --metro-host 127.0.0.1 --metro-port 8081 --relaunch

$ agent-device open com.example.app --platform ios --device "iPhone 17" --session rn-a --metro-host 127.0.0.1 --metro-port 8081
Error (INVALID_ARGS): Flags --metro-host, --metro-port are not supported for command open.
Hint: Check command arguments and run --help for usage examples.

agent-device open --help also omits both flags, so the command help and topic help disagree.

Expected behavior

Every command printed by help react-native should be accepted by the CLI parser. Either:

1. open should accept and apply the documented runtime-hint flags; or
2. the topic help should stop recommending unsupported flags and point to the supported runtime setup flow.

Suggested patch

If the current public contract intentionally excludes these flags from open, the minimum documentation patch is:

- agent-device open "React Navigation Example" --platform ios --device "iPhone 17" --session rn-a --metro-host 127.0.0.1 --metro-port 8081 --relaunch
- agent-device open "React Navigation Example" --platform ios --device "iPhone 17 Pro" --session rn-b --metro-host 127.0.0.1 --metro-port 8082 --relaunch
+ # Configure each simulator's Metro endpoint through the supported project/session runtime flow first.
+ agent-device open "React Navigation Example" --platform ios --device "iPhone 17" --session rn-a --relaunch
+ agent-device open "React Navigation Example" --platform ios --device "iPhone 17 Pro" --session rn-b --relaunch

For project-owned RN debug shells, that preceding flow can be the shell's per-simulator runtime config. If --metro-host / --metro-port are intended to remain the generic agent-device mechanism, the parser/schema should instead be repaired and the existing help kept.

A regression test that parses every command example emitted by help react-native would prevent the help surface from getting ahead of the released CLI schema again.

Related

• Support session-scoped runtime hints and remote artifact retrieval in native remote daemon mode #197 introduced session-scoped runtime hints and explicitly discussed flags on open.
• iOS Metro hint doesn't reach expo-dev-client apps (writes bare-RN RCT_jsLocation only) #1245 assumes open --metro-host/--metro-port is available while describing a separate Expo dev-client limitation.