0
# VDK Control CLI
1

2
VDK Control CLI is a command-line interface tool designed for Data Engineers to manage the complete lifecycle of Data Jobs in Kubernetes runtime environments. It provides comprehensive functionality for creating, deleting, deploying, and configuring Data Jobs through a unified console application.
3

4
## Package Information
5

6
- **Package Name**: vdk-control-cli
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install vdk-control-cli`
10
- **Console Command**: `vdkcli`
11

12
## Core Imports
13

14
For plugin development:
15

16
```python
17
from vdk.api.control.plugin.markers import hookimpl, hookspec, PROJECT_NAME
18
from vdk.api.control.plugin.specs import CliHookSpecs
19
```
20

21
For accessing internal functionality (advanced usage):
22

23
```python
24
from vdk.internal.control.main import run, cli
25
from vdk.internal.control.plugin.control_plugin_manager import Plugins
26
```
27

28
## Basic Usage
29

30
### Command-Line Interface
31

32
After installation, use the `vdkcli` command to interact with Data Jobs:
33

34
```bash
35
# Show help and available commands
36
vdkcli --help
37

38
# Authenticate with Control Service
39
vdkcli login
40

41
# Create a new Data Job
42
vdkcli create my-job --team my-team --cloud --local
43

44
# Deploy a Data Job
45
vdkcli deploy my-job --team my-team
46

47
# List Data Jobs
48
vdkcli list --team my-team
49

50
# Show Data Job details
51
vdkcli show my-job --team my-team
52

53
# Delete a Data Job
54
vdkcli delete my-job --team my-team
55

56
# Logout
57
vdkcli logout
58
```
59

60
### Environment Configuration
61

62
Configure CLI behavior using environment variables:
63

64
```bash
65
# Override configuration folder location
66
export VDK_BASE_CONFIG_FOLDER=/custom/config/path
67

68
# Set default Control Service URL
69
export VDK_CONTROL_SERVICE_REST_API_URL=https://control-service.example.com
70

71
# Set API token for authentication
72
export VDK_API_TOKEN=your-api-token
73
export VDK_API_TOKEN_AUTHORIZATION_URL=https://auth.example.com
74

75
# Override OAuth port for credential flow
76
export OAUTH_PORT=8080
77
```
78

79
## Capabilities
80

81
### Console Commands
82

83
Complete set of CLI commands for Data Job lifecycle management.
84

85
#### Authentication Commands
86

87
```python { .api }
88
# CLI commands (available via vdkcli):
89
# vdkcli login [OPTIONS]
90
# vdkcli logout [OPTIONS]
91
```
92

93
The `login` command authenticates with the Control Service using various methods:
94
- OAuth2 credentials flow (default)
95
- API token authentication
96
- Environment variable authentication
97

98
The `logout` command clears stored authentication credentials.
99

100
#### Job Management Commands
101

102
```python { .api }
103
# CLI commands (available via vdkcli):
104
# vdkcli create [OPTIONS] NAME
105
# vdkcli delete [OPTIONS] NAME
106
# vdkcli deploy [OPTIONS] NAME
107
# vdkcli list [OPTIONS]
108
# vdkcli show [OPTIONS] NAME
109
# vdkcli execute [OPTIONS] NAME
110
# vdkcli download-job [OPTIONS] NAME
111
# vdkcli download-key [OPTIONS] NAME
112
```
113

114
- `create`: Creates new Data Jobs locally and/or in the cloud
115
- `delete`: Removes Data Jobs from the cloud runtime
116
- `deploy`: Deploys Data Job source code to cloud runtime
117
- `list`: Lists Data Jobs for a team
118
- `show`: Displays detailed information about a specific Data Job
119
- `execute`: Runs Data Job locally or remotely
120
- `download-job`: Downloads Data Job source code
121
- `download-key`: Downloads Data Job deployment key
122

123
#### Configuration Commands
124

125
```python { .api }
126
# CLI commands (available via vdkcli):
127
# vdkcli properties [OPTIONS] NAME
128
# vdkcli secrets [OPTIONS] NAME
129
# vdkcli set-default [OPTIONS]
130
# vdkcli reset-default [OPTIONS]
131
```
132

133
- `properties`: Manages Data Job properties and configuration
134
- `secrets`: Manages Data Job secrets
135
- `set-default`: Sets default values for CLI options
136
- `reset-default`: Resets default values
137

138
#### Utility Commands
139

140
```python { .api }
141
# CLI commands (available via vdkcli):
142
# vdkcli info [OPTIONS]
143
# vdkcli version [OPTIONS]
144
```
145

146
- `info`: Displays system and environment information
147
- `version`: Shows version information
148

149
### Plugin System
150

151
Extensible plugin architecture for customizing CLI behavior.
152

153
#### Plugin Development Interface
154

155
```python { .api }
156
PROJECT_NAME = "vdk_control_cli.plugin"
157

158
# Decorator for marking hook specifications
159
hookspec: pluggy.HookspecMarker
160

161
# Decorator for marking hook implementations  
162
hookimpl: pluggy.HookimplMarker
163

164
class CliHookSpecs:
165
    """Hook specifications for CLI plugins."""
166
    
167
    @hookspec(firstresult=True)
168
    def get_default_commands_options(self):
169
        """
170
        Hook for setting default CLI command options.
171
        
172
        Returns:
173
            dict: Default options matching click default_map format.
174
                  Example: {"login": {"oauth2_authorize_uri": "https://auth.example.com"}}
175
        """
176
```
177

178
#### Plugin Management
179

180
```python { .api }
181
class Plugins:
182
    """Plugin management system for VDK Control CLI."""
183
    
184
    def __init__(self, project_name=PROJECT_NAME, load_registered=True):
185
        """
186
        Initialize plugin manager.
187
        
188
        Args:
189
            project_name: Plugin project name for entry point discovery
190
            load_registered: Whether to load registered plugins (True by default)
191
        """
192
    
193
    def load_builtin_plugin(self, builtin_plugin_module):
194
        """
195
        Register a built-in plugin module.
196
        
197
        Args:
198
            builtin_plugin_module: Module containing plugin implementations
199
        """
200
    
201
    def hook(self) -> PluginHookRelay:
202
        """
203
        Get hook relay for executing plugin hooks.
204
        
205
        Returns:
206
            PluginHookRelay: Interface for executing plugin hooks
207
        """
208

209
class PluginHookRelay:
210
    """Helper for executing plugin hooks with type safety."""
211
    
212
    def __init__(self, pm: pluggy.PluginManager):
213
        """Initialize with plugin manager."""
214
    
215
    def get_default_commands_options(self):
216
        """Execute default options hook, returns array of results from all plugins."""
217
```
218

219
#### Creating Custom Plugins
220

221
To create a VDK Control CLI plugin:
222

223
1. **Implement Hook Functions**:
224

225
```python
226
from vdk.api.control.plugin.markers import hookimpl
227

228
@hookimpl
229
def get_default_commands_options():
230
    """Set default CLI options."""
231
    return {
232
        "login": {
233
            "auth_type": "api-token",
234
            "api_token_authorization_url": "https://custom-auth.example.com"
235
        }
236
    }
237
```
238

239
2. **Register Plugin Entry Point** in `setup.py`:
240

241
```python
242
setup(
243
    name="vdk-control-cli-custom",
244
    entry_points={
245
        'vdk_control_cli.plugin': [
246
            'custom_plugin = my_package.plugin_module'
247
        ]
248
    }
249
)
250
```
251

252
3. **Install Plugin**:
253

254
```bash
255
pip install vdk-control-cli-custom
256
```
257

258
### Main Entry Points
259

260
Core application entry points for advanced usage.
261

262
```python { .api }
263
def run():
264
    """
265
    Main entry point for the CLI application.
266
    Sets up all CLI commands and executes the click interface.
267
    """
268

269
@click.group(help="Command line tool for Data Jobs lifecycle management.")
270
@click.option("-d", "--dev", is_flag=True, help="Run in developer mode")
271
@click_log.simple_verbosity_option(logging.getLogger())
272
@click.version_option()
273
@click.pass_context
274
def cli(ctx: click.Context, dev: bool):
275
    """
276
    Main CLI group function that initializes the application.
277
    
278
    Args:
279
        ctx: Click context object
280
        dev: Enable developer mode for extra logging
281
    """
282
```
283

284
## Environment Variables
285

286
The CLI recognizes these environment variables for configuration:
287

288
```python { .api }
289
# Configuration environment variables:
290
VDK_BASE_CONFIG_FOLDER: str
291
    # Override local base configuration folder (default: $HOME/.vdk.internal)
292
    
293
VDK_CONTROL_SERVICE_REST_API_URL: str
294
    # Default Control Service URL if not specified as command line argument
295
    
296
VDK_API_TOKEN: str
297
    # Default API Token for authentication
298
    
299
VDK_API_TOKEN_AUTHORIZATION_URL: str
300
    # Default API token authorization URL
301
    
302
OAUTH_PORT: str
303
    # Port for OAuth2 credential flow (default: 31113)
304
```
305

306
## Types
307

308
```python { .api }
309
# Plugin system types
310
PluginManager = pluggy.PluginManager
311
HookspecMarker = pluggy.HookspecMarker
312
HookimplMarker = pluggy.HookimplMarker
313

314
# Click context for CLI commands
315
Context = click.Context
316
```