0
# Command Line Interface
1

2
Comprehensive command line interface for Flink cluster operations including job submission, monitoring, cancellation, and savepoint management.
3

4
## Capabilities
5

6
### CliFrontend
7

8
Main command-line interface entry point for Flink client operations, providing a complete CLI for job and cluster management.
9

10
```java { .api }
11
/**
12
 * Main command-line interface for Flink client operations
13
 */
14
public class CliFrontend {
15
    /**
16
     * Creates a CLI frontend with default configuration directory
17
     */
18
    public CliFrontend();
19
    
20
    /**
21
     * Creates a CLI frontend with specific configuration directory
22
     * @param configDir Path to the configuration directory
23
     */
24
    public CliFrontend(String configDir);
25
    
26
    /**
27
     * Parses command line parameters and returns exit code
28
     * @param args Command line arguments
29
     * @return Exit code (0 for success, non-zero for error)
30
     */
31
    public int parseParameters(String[] args);
32
    
33
    /**
34
     * Gets the current configuration
35
     * @return Configuration object with current settings
36
     */
37
    public Configuration getConfiguration();
38
    
39
    /**
40
     * Executes the RUN command to submit and execute a Flink job
41
     * @param args Command line arguments for job execution
42
     * @return Exit code (0 for success, non-zero for error)
43
     */
44
    public int run(String[] args);
45
    
46
    /**
47
     * Executes the INFO command to display job information and execution plan
48
     * @param args Command line arguments for info command
49
     * @return Exit code (0 for success, non-zero for error)
50
     */
51
    public int info(String[] args);
52
    
53
    /**
54
     * Executes the LIST command to display running and completed jobs
55
     * @param args Command line arguments for list command
56
     * @return Exit code (0 for success, non-zero for error)
57
     */
58
    public int list(String[] args);
59
    
60
    /**
61
     * Executes the CANCEL command to cancel a running job
62
     * @param args Command line arguments for cancel command
63
     * @return Exit code (0 for success, non-zero for error)
64
     */
65
    public int cancel(String[] args);
66
    
67
    /**
68
     * Executes the STOP command to gracefully stop a running job
69
     * @param args Command line arguments for stop command
70
     * @return Exit code (0 for success, non-zero for error)
71
     */
72
    public int stop(String[] args);
73
    
74
    /**
75
     * Executes the SAVEPOINT command to create or manage savepoints
76
     * @param args Command line arguments for savepoint command
77
     * @return Exit code (0 for success, non-zero for error)
78
     */
79
    public int savepoint(String[] args);
80
    
81
    /**
82
     * Gets the configuration directory from environment variables
83
     * @return Path to configuration directory or null if not set
84
     */
85
    public static String getConfigurationDirectoryFromEnv();
86
    
87
    /**
88
     * Gets the list of available custom command line interfaces
89
     * @return List of CustomCommandLine implementations
90
     */
91
    public static List<CustomCommandLine> getCustomCommandLineList();
92
    
93
    /**
94
     * Gets the active custom command line interface for given parameters
95
     * @param commandLine Parsed command line arguments
96
     * @return Active CustomCommandLine implementation
97
     */
98
    public CustomCommandLine getActiveCustomCommandLine(CommandLine commandLine);
99
    
100
    /**
101
     * Main entry point for CLI execution
102
     * @param args Command line arguments
103
     */
104
    public static void main(String[] args);
105
}
106
```
107

108
### Command Line Parsers
109

110
Parsers for different CLI command options and arguments.
111

112
```java { .api }
113
/**
114
 * Command-line argument parser for Flink CLI commands
115
 */
116
public class CliFrontendParser {
117
    /**
118
     * Parses arguments for the RUN command
119
     * @param args Command line arguments
120
     * @return RunOptions containing parsed options
121
     * @throws CliArgsException if parsing fails
122
     */
123
    public static RunOptions parseRunCommand(String[] args) throws CliArgsException;
124
    
125
    /**
126
     * Parses arguments for the LIST command
127
     * @param args Command line arguments
128
     * @return ListOptions containing parsed options
129
     * @throws CliArgsException if parsing fails
130
     */
131
    public static ListOptions parseListCommand(String[] args) throws CliArgsException;
132
    
133
    /**
134
     * Parses arguments for the CANCEL command
135
     * @param args Command line arguments
136
     * @return CancelOptions containing parsed options
137
     * @throws CliArgsException if parsing fails
138
     */
139
    public static CancelOptions parseCancelCommand(String[] args) throws CliArgsException;
140
    
141
    /**
142
     * Parses arguments for the STOP command
143
     * @param args Command line arguments
144
     * @return StopOptions containing parsed options
145
     * @throws CliArgsException if parsing fails
146
     */
147
    public static StopOptions parseStopCommand(String[] args) throws CliArgsException;
148
    
149
    /**
150
     * Parses arguments for the SAVEPOINT command
151
     * @param args Command line arguments
152
     * @return SavepointOptions containing parsed options
153
     * @throws CliArgsException if parsing fails
154
     */
155
    public static SavepointOptions parseSavepointCommand(String[] args) throws CliArgsException;
156
    
157
    /**
158
     * Parses arguments for the INFO command
159
     * @param args Command line arguments
160
     * @return InfoOptions containing parsed options
161
     * @throws CliArgsException if parsing fails
162
     */
163
    public static InfoOptions parseInfoCommand(String[] args) throws CliArgsException;
164
    
165
    /**
166
     * Prints general help information
167
     */
168
    public static void printHelp();
169
    
170
    /**
171
     * Prints help information for the RUN command
172
     */
173
    public static void printHelpForRun();
174
    
175
    /**
176
     * Prints help information for the INFO command
177
     */
178
    public static void printHelpForInfo();
179
    
180
    /**
181
     * Prints help information for the LIST command
182
     */
183
    public static void printHelpForList();
184
    
185
    /**
186
     * Prints help information for the CANCEL command
187
     */
188
    public static void printHelpForCancel();
189
    
190
    /**
191
     * Prints help information for the STOP command
192
     */
193
    public static void printHelpForStop();
194
    
195
    /**
196
     * Prints help information for the SAVEPOINT command
197
     */
198
    public static void printHelpForSavepoint();
199
}
200
```
201

202
### Command Line Options
203

204
Option classes for different CLI commands and their parameters.
205

206
```java { .api }
207
/**
208
 * Base class for all command-line option parsers
209
 */
210
public abstract class CommandLineOptions {
211
    /**
212
     * Gets the parsed command line
213
     * @return CommandLine object with parsed options
214
     */
215
    public CommandLine getCommandLine();
216
    
217
    /**
218
     * Checks if help should be printed
219
     * @return true if help was requested
220
     */
221
    public boolean isPrintHelp();
222
    
223
    /**
224
     * Gets the JobManager address from options
225
     * @return JobManager address string
226
     */
227
    public String getJobManagerAddress();
228
}
229

230
/**
231
 * Base class for options that reference JAR file programs
232
 */
233
public abstract class ProgramOptions extends CommandLineOptions {
234
    /**
235
     * Gets the path to the JAR file
236
     * @return JAR file path string
237
     */
238
    public String getJarFilePath();
239
    
240
    /**
241
     * Gets the entry point class name
242
     * @return Fully qualified class name
243
     */
244
    public String getEntryPointClassName();
245
    
246
    /**
247
     * Gets additional classpath URLs
248
     * @return List of classpath URLs
249
     */
250
    public List<URL> getClasspaths();
251
    
252
    /**
253
     * Gets program arguments
254
     * @return Array of program arguments
255
     */
256
    public String[] getProgramArgs();
257
    
258
    /**
259
     * Gets the parallelism level
260
     * @return Parallelism value or -1 if not specified
261
     */
262
    public int getParallelism();
263
    
264
    /**
265
     * Checks if stdout logging is enabled
266
     * @return true if stdout logging is enabled
267
     */
268
    public boolean getStdoutLogging();
269
    
270
    /**
271
     * Checks if detached mode is enabled
272
     * @return true if detached mode is requested
273
     */
274
    public boolean getDetachedMode();
275
    
276
    /**
277
     * Gets savepoint restore settings
278
     * @return SavepointRestoreSettings for job restoration
279
     */
280
    public SavepointRestoreSettings getSavepointRestoreSettings();
281
}
282

283
/**
284
 * Command-line options for the RUN command
285
 */
286
public class RunOptions extends ProgramOptions {
287
    // Inherits all methods from ProgramOptions
288
}
289

290
/**
291
 * Command-line options for the LIST command
292
 */
293
public class ListOptions extends CommandLineOptions {
294
    /**
295
     * Checks if only running jobs should be listed
296
     * @return true if filtering for running jobs
297
     */
298
    public boolean getRunning();
299
    
300
    /**
301
     * Checks if only scheduled jobs should be listed
302
     * @return true if filtering for scheduled jobs
303
     */
304
    public boolean getScheduled();
305
}
306

307
/**
308
 * Command-line options for the CANCEL command
309
 */
310
public class CancelOptions extends CommandLineOptions {
311
    // Inherits methods from CommandLineOptions
312
}
313

314
/**
315
 * Command-line options for the STOP command
316
 */
317
public class StopOptions extends CommandLineOptions {
318
    // Inherits methods from CommandLineOptions
319
}
320

321
/**
322
 * Command-line options for the SAVEPOINT command
323
 */
324
public class SavepointOptions extends CommandLineOptions {
325
    // Inherits methods from CommandLineOptions
326
}
327

328
/**
329
 * Command-line options for the INFO command
330
 */
331
public class InfoOptions extends ProgramOptions {
332
    // Inherits all methods from ProgramOptions
333
}
334
```
335

336
### Custom Command Line Interface
337

338
Extension point for custom command-line interfaces and cluster-specific implementations.
339

340
```java { .api }
341
/**
342
 * Extension point for custom command-line interfaces
343
 */
344
public interface CustomCommandLine<ClusterType> {
345
    /**
346
     * Checks if this command line interface is active for the given parameters
347
     * @param commandLine Parsed command line arguments
348
     * @param configuration Current configuration
349
     * @return true if this interface should handle the command
350
     */
351
    boolean isActive(CommandLine commandLine, Configuration configuration);
352
    
353
    /**
354
     * Gets the unique identifier for this command line interface
355
     * @return String identifier for this CLI
356
     */
357
    String getId();
358
    
359
    /**
360
     * Adds run-specific options to the base options
361
     * @param baseOptions Base options to extend
362
     */
363
    void addRunOptions(Options baseOptions);
364
    
365
    /**
366
     * Adds general options to the base options
367
     * @param baseOptions Base options to extend
368
     */
369
    void addGeneralOptions(Options baseOptions);
370
    
371
    /**
372
     * Retrieves an existing cluster based on command line parameters
373
     * @param commandLine Parsed command line arguments
374
     * @param config Configuration object
375
     * @return Cluster client instance
376
     * @throws Exception if cluster retrieval fails
377
     */
378
    ClusterType retrieveCluster(CommandLine commandLine, Configuration config) throws Exception;
379
    
380
    /**
381
     * Creates a new cluster based on command line parameters
382
     * @param applicationName Name for the application/cluster
383
     * @param commandLine Parsed command line arguments
384
     * @param config Configuration object
385
     * @param userJarFiles List of user JAR files
386
     * @return Cluster client instance
387
     * @throws Exception if cluster creation fails
388
     */
389
    ClusterType createCluster(String applicationName, CommandLine commandLine, Configuration config, List<URL> userJarFiles) throws Exception;
390
}
391

392
/**
393
 * Default command-line interface for standalone clusters
394
 */
395
public class DefaultCLI implements CustomCommandLine<StandaloneClusterClient> {
396
    // Implements all CustomCommandLine methods for standalone clusters
397
}
398
```
399

400
**Usage Examples:**
401

402
```java
403
import org.apache.flink.client.CliFrontend;
404
import org.apache.flink.client.cli.CliFrontendParser;
405
import org.apache.flink.client.cli.RunOptions;
406

407
// Basic CLI usage - run a Flink job
408
String[] args = {
409
    "run",
410
    "-p", "4",                           // parallelism
411
    "-c", "com.example.MyFlinkJob",      // entry class
412
    "/path/to/my-job.jar",               // JAR file
413
    "arg1", "arg2", "arg3"               // program arguments
414
};
415

416
CliFrontend cli = new CliFrontend();
417
int exitCode = cli.parseParameters(args);
418
System.exit(exitCode);
419

420
// Parse run command options programmatically
421
RunOptions runOptions = CliFrontendParser.parseRunCommand(args);
422
System.out.println("JAR file: " + runOptions.getJarFilePath());
423
System.out.println("Entry class: " + runOptions.getEntryPointClassName());
424
System.out.println("Parallelism: " + runOptions.getParallelism());
425
System.out.println("Program args: " + Arrays.toString(runOptions.getProgramArgs()));
426

427
// CLI commands examples:
428
// flink run -p 4 -c com.example.Job job.jar arg1 arg2
429
// flink list
430
// flink cancel <job-id>
431
// flink stop <job-id>
432
// flink savepoint <job-id> [target-directory]
433
// flink info -c com.example.Job job.jar
434
```
435

436
### CLI Exception Types
437

438
Exception types for command-line parsing errors.
439

440
```java { .api }
441
/**
442
 * Exception indicating command-line parsing failures
443
 */
444
public class CliArgsException extends Exception {
445
    /**
446
     * Creates exception with error message
447
     * @param message Error description
448
     */
449
    public CliArgsException(String message);
450
}
451
```