0
# Command-Line Interface
1
2
The Flink Scala Shell provides a comprehensive command-line interface for starting interactive Scala sessions with different Flink cluster configurations.
3
4
## Imports
5
6
```scala
7
import org.apache.flink.api.scala.FlinkShell.Config
8
```
9
10
## Capabilities
11
12
### Main Entry Point
13
14
Entry point that parses command-line arguments and starts the shell.
15
16
```scala { .api }
17
/**
18
* Main entry point for the Flink Scala Shell
19
* @param args Command-line arguments specifying execution mode and options
20
*/
21
def main(args: Array[String]): Unit
22
```
23
24
**Usage Examples:**
25
26
```bash
27
# Start with local cluster
28
start-scala-shell.sh local
29
30
# Start with remote cluster
31
start-scala-shell.sh remote localhost 8081
32
33
# Start with YARN cluster
34
start-scala-shell.sh yarn --jobManagerMemory 1024m --taskManagerMemory 2048m
35
```
36
37
### Shell Startup
38
39
Initializes and starts the interactive shell with the provided configuration.
40
41
```scala { .api }
42
/**
43
* Starts the Flink Scala Shell with the given configuration
44
* @param config Configuration object containing cluster and execution settings
45
*/
46
def startShell(config: Config): Unit
47
```
48
49
### Execution Mode Commands
50
51
The shell supports three primary execution modes, each with specific command syntax:
52
53
#### Local Mode
54
55
Starts a local Flink mini-cluster for development and testing.
56
57
```bash
58
start-scala-shell.sh local [options]
59
```
60
61
**Options:**
62
- `--addclasspath/-a <path/to/jar>` - Add external JARs (colon-separated paths)
63
64
**Example:**
65
```bash
66
start-scala-shell.sh local --addclasspath /path/to/my-lib.jar:/path/to/other-lib.jar
67
```
68
69
#### Remote Mode
70
71
Connects to an existing remote Flink cluster.
72
73
```bash
74
start-scala-shell.sh remote <host> <port> [options]
75
```
76
77
**Required Arguments:**
78
- `<host>` - Remote JobManager host address
79
- `<port>` - Remote JobManager port number
80
81
**Options:**
82
- `--addclasspath/-a <path/to/jar>` - Add external JARs (colon-separated paths)
83
84
**Example:**
85
```bash
86
start-scala-shell.sh remote flink-cluster.example.com 8081 --addclasspath /path/to/deps.jar
87
```
88
89
#### YARN Mode
90
91
Connects to or creates a YARN cluster for Flink execution.
92
93
```bash
94
start-scala-shell.sh yarn [options]
95
```
96
97
**YARN-Specific Options:**
98
- `--jobManagerMemory/-jm <memory>` - Memory allocation for JobManager container (e.g., "1024m", "2g")
99
- `--taskManagerMemory/-tm <memory>` - Memory allocation per TaskManager container
100
- `--name/-nm <name>` - Custom application name on YARN
101
- `--queue/-qu <queue>` - YARN queue for job submission
102
- `--slots/-s <slots>` - Number of slots per TaskManager
103
- `--addclasspath/-a <path/to/jar>` - Add external JARs (colon-separated paths)
104
105
**Example:**
106
```bash
107
start-scala-shell.sh yarn \
108
--jobManagerMemory 1024m \
109
--taskManagerMemory 2048m \
110
--name "My Flink Shell Session" \
111
--queue production \
112
--slots 4 \
113
--addclasspath /path/to/dependencies.jar
114
```
115
116
### Global Options
117
118
Options available across all execution modes:
119
120
```scala { .api }
121
/**
122
* Global configuration options available for all execution modes
123
*/
124
case class GlobalOptions(
125
configDir: Option[String], // Configuration directory path
126
addclasspath: Option[String], // External JAR dependencies
127
help: Boolean // Show help information
128
)
129
```
130
131
**Global Command-Line Options:**
132
- `--configDir <directory>` - Specify Flink configuration directory path
133
- `--help/-h` - Display usage information and exit
134
135
### Command-Line Parsing
136
137
The shell uses scopt library for robust command-line argument parsing with built-in validation and help generation.
138
139
```scala { .api }
140
/**
141
* Command-line parser configuration with subcommands and options
142
*/
143
private val parser: scopt.OptionParser[Config] = new scopt.OptionParser[Config]("start-scala-shell.sh") {
144
head("Flink Scala Shell")
145
146
cmd("local").action((_, c) => c.copy(executionMode = ExecutionMode.LOCAL))
147
cmd("remote").action((_, c) => c.copy(executionMode = ExecutionMode.REMOTE))
148
cmd("yarn").action((_, c) => c.copy(executionMode = ExecutionMode.YARN))
149
}
150
```
151
152
### Error Handling
153
154
The command-line interface provides comprehensive error handling for common configuration issues:
155
156
- **Missing required arguments**: Clear error messages for missing host/port in remote mode
157
- **Invalid execution mode**: Guidance on correct usage when mode is unspecified
158
- **Configuration errors**: Detailed error information for cluster connection failures
159
- **Help display**: Automatic help text generation with usage examples
160
161
**Example Error Messages:**
162
```
163
Error: <host> or <port> is not specified!
164
Error: please specify execution mode: [local | remote <host> <port> | yarn]
165
Could not parse program arguments
166
```
167
168
### Configuration Directory
169
170
The shell automatically locates Flink configuration using:
171
172
1. `--configDir` command-line option (highest priority)
173
2. `FLINK_CONF_DIR` environment variable
174
3. Default Flink configuration directory resolution
175
176
```scala { .api }
177
/**
178
* Resolves configuration directory from command-line options or environment
179
* @param config Configuration object with optional configDir
180
* @return Path to configuration directory
181
*/
182
private def getConfigDir(config: Config): String
183
184
/**
185
* Loads global Flink configuration from resolved directory
186
* @param config Configuration object
187
* @return Loaded Configuration instance
188
*/
189
private def getGlobalConfig(config: Config): Configuration
190
```