0
# CLI Interface
1

2
Command line tool for quickly starting an inspector proxy server with configurable options. The CLI provides a simple way to launch a complete debugging infrastructure for React Native development.
3

4
## Capabilities
5

6
### Command Line Options
7

8
The CLI accepts the following options for configuring the inspector proxy server:
9

10
```javascript { .api }
11
interface CLIOptions {
12
  port: number;    // Port to run inspector proxy on
13
  root: string;    // Root folder of metro project
14
}
15
```
16

17
### CLI Usage
18

19
```bash
20
# Install globally to use as command
21
npm install -g metro-inspector-proxy
22

23
# Start with default settings (port 8081, current directory as root)
24
metro-inspector-proxy
25

26
# Specify custom port
27
metro-inspector-proxy --port 9090
28
metro-inspector-proxy -p 9090
29

30
# Specify project root directory
31
metro-inspector-proxy --root /path/to/my/react/native/project
32
metro-inspector-proxy -r /path/to/my/react/native/project
33

34
# Combined options
35
metro-inspector-proxy --port 9090 --root /path/to/project
36
```
37

38
### Option Details
39

40
#### --port, -p (number)
41
- **Description**: Port to run inspector proxy on
42
- **Default**: 8081
43
- **Usage**: Specifies which port the HTTP server will listen on for both HTTP endpoints and WebSocket connections
44

45
#### --root, -r (string)  
46
- **Description**: Root folder of metro project
47
- **Default**: Empty string (current directory)
48
- **Usage**: Sets the project root directory used for resolving relative source file paths during debugging
49

50
### CLI Implementation
51

52
The CLI is implemented using the yargs library for argument parsing:
53

54
```javascript
55
const yargs = require('yargs');
56
const { runInspectorProxy } = require('./index');
57

58
const argv = yargs
59
  .option('port', {
60
    alias: 'p',
61
    describe: 'port to run inspector proxy on',
62
    type: 'number',
63
    default: 8081,
64
  })
65
  .option('root', {
66
    alias: 'r', 
67
    describe: 'root folder of metro project',
68
    type: 'string',
69
    default: '',
70
  })
71
  .parseSync();
72

73
runInspectorProxy(argv.port, argv.root);
74
```
75

76
### Server Startup
77

78
When started via CLI, the inspector proxy server automatically:
79

80
1. **Creates HTTP server** on the specified port binding to 127.0.0.1
81
2. **Sets up HTTP endpoints**:
82
   - `GET /json` - List of inspectable pages
83
   - `GET /json/list` - Alternative pages endpoint  
84
   - `GET /json/version` - Chrome DevTools protocol version
85
3. **Creates WebSocket endpoints**:
86
   - `/inspector/device` - For React Native devices to connect
87
   - `/inspector/debug` - For Chrome DevTools to connect
88
4. **Enables device discovery** with automatic page polling
89
5. **Handles debugger sessions** with message forwarding and protocol translation
90

91
### Integration with Development Workflow
92

93
The CLI tool integrates seamlessly with React Native development:
94

95
```bash
96
# Terminal 1: Start Metro bundler
97
npx react-native start
98

99
# Terminal 2: Start inspector proxy (if not using Metro's built-in proxy)
100
metro-inspector-proxy --port 8081 --root /path/to/MyReactNativeApp
101

102
# Terminal 3: Start React Native app
103
npx react-native run-ios
104
# or
105
npx react-native run-android
106
```
107

108
Once running, developers can:
109
1. Open Chrome and navigate to `chrome://inspect`
110
2. Click "Configure..." and add `localhost:8081` to the target discovery settings
111
3. The React Native app should appear in the "Remote Target" list
112
4. Click "inspect" to open Chrome DevTools for debugging
113

114
### Process Management
115

116
The CLI tool runs as a persistent process that:
117
- Listens for device connections from React Native apps
118
- Manages multiple simultaneous debugger sessions
119
- Handles app reloads and reconnections gracefully
120
- Provides console output for connection events and errors
121

122
To stop the server, use `Ctrl+C` (SIGINT) in the terminal where it's running.
123

124
### Error Handling
125

126
The CLI provides basic error handling:
127
- Invalid port numbers are handled by yargs validation
128
- Network binding errors are logged to console
129
- WebSocket connection errors are managed per-connection
130
- File system errors for source resolution are reported to debugger console
131

132
### Environment Considerations
133

134
The inspector proxy CLI is designed for development environments and:
135
- Only binds to localhost (127.0.0.1) for security
136
- Should not be used in production environments
137
- Requires Node.js version 18 or higher
138
- Works with both iOS Simulator/device and Android emulator/device