0
# Command-Line Interface
1

2
Complete CLI frontend for Flink operations providing comprehensive command-line access to job submission, cancellation, savepoint management, cluster monitoring, and administrative functions.
3

4
## Capabilities
5

6
### CLI Frontend Entry Point
7

8
Main entry point for the Flink command-line interface, handling argument parsing and command dispatch.
9

10
```java { .api }
11
/**
12
 * Main command-line frontend for executing Flink programs and managing clusters
13
 */
14
public class CliFrontend {
15
    /**
16
     * Main entry point for CLI operations
17
     * @param args Command-line arguments
18
     */
19
    public static void main(String[] args);
20
    
21
    /**
22
     * Parse command-line arguments and execute the corresponding action
23
     * @param args Command-line arguments
24
     * @return Exit code (0 for success, non-zero for failure)
25
     */
26
    public int parseAndRun(String[] args);
27
    
28
    /**
29
     * Create CLI frontend with default configuration
30
     */
31
    public CliFrontend();
32
    
33
    /**
34
     * Create CLI frontend with custom configuration and command-line implementations
35
     * @param config Flink configuration
36
     * @param customCommandLines Custom command-line implementations
37
     */
38
    public CliFrontend(Configuration config, List<CustomCommandLine> customCommandLines);
39
}
40
```
41

42
**Usage Examples:**
43

44
```bash
45
# Submit a job
46
flink run -c com.mycompany.MyJob /path/to/job.jar --input input.txt
47

48
# List running jobs
49
flink list
50

51
# Cancel a job
52
flink cancel <job-id>
53

54
# Create a savepoint
55
flink savepoint <job-id> [target-directory]
56

57
# Stop a job with savepoint
58
flink stop <job-id> [--savepointPath <path>]
59
```
60

61
### Command-Line Parser
62

63
Parser for CLI frontend commands and options, handling argument validation and help generation.
64

65
```java { .api }
66
/**
67
 * Parser for CLI frontend commands and options
68
 */
69
public class CliFrontendParser {
70
    /**
71
     * Parse run command arguments
72
     * @param args Command arguments
73
     * @return Parsed program options
74
     * @throws CliArgsException if parsing fails
75
     */
76
    public static ProgramOptions parseRunCommand(String[] args) throws CliArgsException;
77
    
78
    /**
79
     * Parse cancel command arguments
80
     * @param args Command arguments
81
     * @return Parsed cancel options
82
     * @throws CliArgsException if parsing fails
83
     */
84
    public static CancelOptions parseCancelCommand(String[] args) throws CliArgsException;
85
    
86
    /**
87
     * Parse savepoint command arguments
88
     * @param args Command arguments
89
     * @return Parsed savepoint options
90
     * @throws CliArgsException if parsing fails
91
     */
92
    public static SavepointOptions parseSavepointCommand(String[] args) throws CliArgsException;
93
    
94
    /**
95
     * Parse list command arguments
96
     * @param args Command arguments
97
     * @return Parsed list options
98
     * @throws CliArgsException if parsing fails
99
     */
100
    public static ListOptions parseListCommand(String[] args) throws CliArgsException;
101
}
102
```
103

104
### Custom Command Line Interface
105

106
Interface for implementing custom command-line options and deployment-specific configurations.
107

108
```java { .api }
109
/**
110
 * Interface for custom command-line implementations
111
 */
112
public interface CustomCommandLine {
113
    /**
114
     * Check if this command line handles the given options
115
     * @param commandLine Parsed command line
116
     * @return true if this implementation handles the options
117
     */
118
    boolean isActive(CommandLine commandLine);
119
    
120
    /**
121
     * Get the command line options for this implementation
122
     * @return Apache Commons CLI Options
123
     */
124
    Options getOptions();
125
    
126
    /**
127
     * Create cluster descriptor from parsed command line
128
     * @param commandLine Parsed command line
129
     * @return Cluster descriptor
130
     * @throws FlinkException if creation fails
131
     */
132
    ClusterDescriptor<?> createClusterDescriptor(CommandLine commandLine) throws FlinkException;
133
    
134
    /**
135
     * Get cluster ID from parsed command line
136
     * @param commandLine Parsed command line
137
     * @return Cluster ID or null if not applicable
138
     */
139
    @Nullable
140
    String getClusterId(CommandLine commandLine);
141
}
142
```
143

144
### Command Option Classes
145

146
Type-safe option classes for different CLI commands.
147

148
```java { .api }
149
/**
150
 * Base class for command-line options
151
 */
152
public abstract class CommandLineOptions {
153
    public String getCommandLine();
154
}
155

156
/**
157
 * Options for program execution commands
158
 */
159
public class ProgramOptions extends CommandLineOptions {
160
    public String getJarFilePath();
161
    public String getEntryPointClassName();
162
    public String[] getProgramArgs();
163
    public int getParallelism();
164
    public boolean getDetachedMode();
165
    public SavepointRestoreSettings getSavepointRestoreSettings();
166
}
167

168
/**
169
 * Options for job cancellation commands
170
 */
171
public class CancelOptions extends CommandLineOptions {
172
    public String getJobId();
173
    public boolean isWithSavepoint();
174
    public String getTargetDirectory();
175
}
176

177
/**
178
 * Options for savepoint management commands
179
 */
180
public class SavepointOptions extends CommandLineOptions {
181
    public String getJobId();
182
    public String getSavepointPath();
183
    public boolean isDispose();
184
    public SavepointFormatType getFormatType();
185
}
186

187
/**
188
 * Options for job listing commands
189
 */
190
public class ListOptions extends CommandLineOptions {
191
    public boolean getShowRunning();
192
    public boolean getShowScheduled();
193
    public boolean getShowAll();
194
}
195

196
/**
197
 * Options for job stop commands
198
 */
199
public class StopOptions extends CommandLineOptions {
200
    public String getJobId();
201
    public boolean isWithDrain();
202
    public String getSavepointPath();
203
}
204
```
205

206
### Application Deployer
207

208
CLI deployer for application clusters, handling application-mode specific deployment workflows.
209

210
```java { .api }
211
/**
212
 * CLI deployer for application clusters
213
 */
214
public class ApplicationDeployer {
215
    /**
216
     * Deploy application to cluster
217
     * @param config Flink configuration
218
     * @param applicationConfiguration Application configuration
219
     * @param programOptions Program options from CLI
220
     * @param customCommandLines Available custom command lines
221
     * @return Cluster client provider
222
     * @throws Exception if deployment fails
223
     */
224
    public static ClusterClientProvider<?> deploy(
225
        Configuration config,
226
        ApplicationConfiguration applicationConfiguration,
227
        ProgramOptions programOptions,
228
        List<CustomCommandLine> customCommandLines
229
    ) throws Exception;
230
}
231
```
232

233
### Utility Classes
234

235
Utility classes for common CLI operations and configuration handling.
236

237
```java { .api }
238
/**
239
 * Utilities for working with program options
240
 */
241
public class ProgramOptionsUtils {
242
    /**
243
     * Create packaged program from options
244
     * @param options Program options
245
     * @param config Flink configuration
246
     * @return Packaged program
247
     * @throws Exception if creation fails
248
     */
249
    public static PackagedProgram createPackagedProgram(
250
        ProgramOptions options, 
251
        Configuration config
252
    ) throws Exception;
253
}
254

255
/**
256
 * Utilities for dynamic property handling
257
 */
258
public class DynamicPropertiesUtil {
259
    /**
260
     * Parse dynamic properties from command line
261
     * @param dynamicProperties Array of property strings
262
     * @return Configuration with parsed properties
263
     */
264
    public static Configuration parseFlinkProperties(String[] dynamicProperties);
265
}
266

267
/**
268
 * Exception for CLI argument parsing errors
269
 */
270
public class CliArgsException extends Exception {
271
    public CliArgsException(String message);
272
    public CliArgsException(String message, Throwable cause);
273
}
274
```
275

276
## Error Handling
277

278
The CLI frontend handles various error conditions and provides meaningful error messages:
279

280
- **Invalid Arguments**: `CliArgsException` for malformed command-line arguments
281
- **Program Errors**: `ProgramInvocationException` for program execution failures  
282
- **Cluster Errors**: `ClusterDeploymentException` and `ClusterRetrieveException` for deployment issues
283
- **File Errors**: `FileNotFoundException` for missing JAR files or configuration
284

285
Common error patterns include validation of required arguments, file existence checks, and cluster connectivity verification before attempting operations.