0
# CLI Usage
1

2
The Relay Compiler command-line interface provides powerful tools for compiling GraphQL files, running in watch mode, validating changes, and managing LSP integration.
3

4
## Installation
5

6
```bash
7
# Install globally
8
npm install -g relay-compiler
9

10
# Install locally
11
npm install relay-compiler
12
```
13

14
## Platform Binary Resolution
15

16
The relay-compiler package automatically detects your platform and uses the appropriate binary:
17

18
```javascript
19
const relayBinary = require('relay-compiler');
20
console.log(relayBinary); // Returns path to platform-specific binary or null
21
```
22

23
**Supported Platforms:**
24
- macOS x64: `macos-x64/relay`
25
- macOS ARM64: `macos-arm64/relay`
26
- Linux x64: `linux-x64/relay`
27
- Linux ARM64: `linux-arm64/relay`
28
- Windows x64: `win-x64/relay.exe`
29

30
## Main Compiler Command
31

32
The default command compiles Relay files and writes generated files.
33

34
```bash
35
{ .api }
36
relay-compiler [OPTIONS]
37
```
38

39
### Options
40

41
```bash
42
{ .api }
43
--watch, -w                    # Compile and watch for changes
44
--project, -p <PROJECT>        # Compile specific project (repeatable)
45
--config <PATH>                # Use specific config file
46
--src <PATH>                   # Path to source directory
47
--schema <PATH>                # Path to schema file
48
--artifact-directory <PATH>    # Output directory for artifacts
49
--repersist                    # Force re-persistence of queries
50
--output <KIND>                # Verbosity level
51
--validate                     # Check for changes without writing
52
```
53

54
### Output Levels
55

56
```typescript
57
{ .api }
58
type OutputKind = "debug" | "quiet" | "quiet-with-errors" | "verbose";
59
```
60

61
### Usage Examples
62

63
```bash
64
# Basic compilation
65
relay-compiler --src ./src --schema ./schema.graphql
66

67
# Watch mode for development
68
relay-compiler --watch --src ./src --schema ./schema.graphql
69

70
# Compile specific projects
71
relay-compiler --project web --project mobile
72

73
# Validation mode (no file writes)
74
relay-compiler --validate --src ./src --schema ./schema.graphql
75

76
# Custom artifact directory
77
relay-compiler --src ./src --schema ./schema.graphql --artifact-directory ./generated
78

79
# Verbose output with re-persistence
80
relay-compiler --output verbose --repersist --src ./src --schema ./schema.graphql
81
```
82

83
## Language Server Command
84

85
Run the LSP server for IDE integration.
86

87
```bash
88
{ .api }
89
relay-compiler lsp [OPTIONS]
90
```
91

92
### LSP Options
93

94
```bash
95
{ .api }
96
--config <PATH>              # Config file path
97
--output <KIND>              # Verbosity level (default: quiet-with-errors)
98
--locate-command <SCRIPT>    # Script for GraphQL entity location lookup
99
```
100

101
### Usage Examples
102

103
```bash
104
# Start LSP server
105
relay-compiler lsp
106

107
# Start with custom config
108
relay-compiler lsp --config ./relay.config.json
109

110
# Start with entity location script
111
relay-compiler lsp --locate-command "./scripts/find-graphql-entity.sh"
112

113
# Start with debug output
114
relay-compiler lsp --output debug
115
```
116

117
## Configuration Schema Command
118

119
Print the JSON schema for Relay compiler configuration.
120

121
```bash
122
{ .api }
123
relay-compiler config-json-schema
124
```
125

126
This outputs the complete JSON schema definition for configuration validation and IDE support.
127

128
```bash
129
# Output schema to file
130
relay-compiler config-json-schema > relay-config.schema.json
131
```
132

133
## Codemod Commands
134

135
Apply automated code transformations with safety controls.
136

137
```bash
138
{ .api }
139
relay-compiler codemod <CODEMOD> [OPTIONS]
140
```
141

142
### Available Codemods
143

144
#### Mark Dangerous Conditional Fragment Spreads
145

146
```bash
147
{ .api }
148
relay-compiler codemod mark-dangerous-conditional-fragment-spreads [OPTIONS]
149
```
150

151
**Options:**
152
- `--rollout-percentage, -r <PERCENT>`: Percentage or range (e.g., "50" or "20-30")
153
- `--project, -p <PROJECT>`: Target specific projects
154
- `--config <PATH>`: Use specific config file
155

156
**Usage Examples:**
157
```bash
158
# Apply to 50% of files
159
relay-compiler codemod mark-dangerous-conditional-fragment-spreads --rollout-percentage 50
160

161
# Apply to percentage range
162
relay-compiler codemod mark-dangerous-conditional-fragment-spreads -r 20-30
163

164
# Apply to specific project
165
relay-compiler codemod mark-dangerous-conditional-fragment-spreads --project web
166
```
167

168
#### Remove Unnecessary Required Directives
169

170
```bash
171
{ .api }
172
relay-compiler codemod remove-unnecessary-required-directives [OPTIONS]
173
```
174

175
**Options:**
176
- `--project, -p <PROJECT>`: Target specific projects
177
- `--config <PATH>`: Use specific config file
178

179
**Usage Examples:**
180
```bash
181
# Apply to all projects
182
relay-compiler codemod remove-unnecessary-required-directives
183

184
# Apply to specific project
185
relay-compiler codemod remove-unnecessary-required-directives --project mobile
186
```
187

188
## Configuration File Discovery
189

190
When no `--config` option is provided, the compiler searches for configuration in this order:
191

192
1. `relay.config.json` in current directory
193
2. `relay.config.js` in current directory  
194
3. `relay` key in `package.json`
195
4. Walks up directory tree repeating the search
196

197
## Error Handling
198

199
The CLI provides detailed error messages for common issues:
200

201
```typescript
202
{ .api }
203
interface CLIErrors {
204
  ProjectFilterError: string;    // Invalid project selection
205
  ConfigError: string;          // Configuration validation failures
206
  CompilerError: string;        // Compilation failures
207
  CodemodError: string;         // Codemod application failures
208
}
209
```
210

211
**Common Error Scenarios:**
212
- Unsupported platform: Clear message with platform information
213
- Missing configuration: Guidance on config file creation
214
- Invalid project names: List of available projects
215
- Schema file not found: Path resolution assistance
216
- Permission errors: File system access issues
217

218
## Environment Variables
219

220
```bash
221
{ .api }
222
FORCE_NO_WATCHMAN=1    # Disable Watchman integration, use filesystem watching
223
```
224

225
## Exit Codes
226

227
```typescript
228
{ .api }
229
type ExitCodes = {
230
  0: "Success";
231
  1: "General error";
232
  2: "Validation failures (--validate mode)";
233
}
234
```