0
# CLI and Project Management
1

2
Kedro provides a comprehensive command-line interface for project creation, pipeline execution, and project management. The CLI integrates with project discovery, settings management, and plugin systems.
3

4
## Capabilities
5

6
### CLI Entry Point
7

8
Main command-line interface with extensible command structure.
9

10
```python { .api }
11
def main():
12
    """
13
    Main entry point for Kedro CLI.
14
    
15
    Provides access to all Kedro commands including:
16
    - kedro new: Create new project
17
    - kedro run: Execute pipelines  
18
    - kedro install: Install dependencies
19
    - kedro package: Package project
20
    - kedro catalog: Catalog operations
21
    - kedro pipeline: Pipeline management
22
    - kedro jupyter: Jupyter integration
23
    - kedro ipython: IPython integration
24
    """
25
```
26

27
### CLI Utilities
28

29
Utility functions for command creation and plugin loading.
30

31
```python { .api }
32
def command_with_verbosity(func):
33
    """
34
    Decorator to add verbosity options to CLI commands.
35
    
36
    Args:
37
        func (Callable): Command function to decorate
38
        
39
    Returns:
40
        Callable: Decorated command function with verbosity support
41
    """
42

43
def load_entry_points(group_name):
44
    """
45
    Load plugin entry points for CLI extensions.
46
    
47
    Args:
48
        group_name (str): Entry point group name (e.g., "kedro.line_magic")
49
        
50
    Returns:
51
        list: List of loaded entry point functions
52
    """
53
```
54

55
### Project Configuration
56

57
Project-level configuration and settings management.
58

59
```python { .api }
60
def configure_project(package_name):
61
    """
62
    Configure Kedro project with package settings.
63
    
64
    Args:
65
        package_name (str): Python package name for the project
66
        
67
    Side Effects:
68
        - Loads settings from {package_name}.settings module
69
        - Configures pipeline registry from {package_name}.pipeline_registry
70
        - Sets up project logging configuration
71
    """
72

73
settings: Any
74
    """
75
    Global settings object for project configuration.
76
    
77
    Provides access to:
78
    - CONF_SOURCE: Configuration source directory
79
    - HOOKS: Project hooks configuration
80
    - CONTEXT_CLASS: Context class to use
81
    - CONFIG_LOADER_CLASS: Configuration loader class
82
    - DATA_CATALOG_CLASS: Data catalog class
83
    """
84

85
pipelines: Any
86
    """
87
    Global pipelines registry for project pipelines.
88
    
89
    Lazy-loaded dictionary-like object providing access to:
90
    - Registered pipelines by name
91
    - Pipeline discovery and loading
92
    - Pipeline configuration management
93
    """
94
```
95

96
### Pipeline Discovery
97

98
Automatic pipeline registration and discovery functionality.
99

100
```python { .api }
101
def find_pipelines(raise_errors=False):
102
    """
103
    Automatically discover and register modular pipelines.
104
    
105
    Searches for pipelines in:
106
    - {package_name}.pipeline module (simplified structure)
107
    - {package_name}.pipelines.* modules (modular structure)
108
    
109
    Args:
110
        raise_errors (bool): Whether to raise errors on discovery failures
111
        
112
    Returns:
113
        dict: Mapping of pipeline names to Pipeline objects
114
        
115
    Raises:
116
        ImportError: When raise_errors=True and pipeline import fails
117
        
118
    Warns:
119
        UserWarning: When raise_errors=False and pipeline import fails
120
    """
121
```
122

123
### Logging Configuration
124

125
Project logging setup and configuration management.
126

127
```python { .api }
128
def configure_logging(logging_config):
129
    """
130
    Configure project logging according to configuration dictionary.
131
    
132
    Args:
133
        logging_config (dict): Logging configuration dictionary
134
        
135
    Side Effects:
136
        - Applies logging configuration using logging.config.dictConfig
137
        - Updates global LOGGING object with new configuration
138
    """
139

140
def validate_settings():
141
    """
142
    Validate project settings configuration.
143
    
144
    Performs eager validation of settings module to surface
145
    syntax errors, import errors, and configuration issues early.
146
    
147
    Raises:
148
        ValueError: If package name not configured
149
        ImportError: If settings module has import/syntax errors
150
        
151
    Warns:
152
        UserWarning: If no settings.py file found
153
    """
154
```
155

156
## Usage Examples
157

158
### Basic CLI Usage
159

160
```bash
161
# Create new Kedro project
162
kedro new
163

164
# Run default pipeline
165
kedro run
166

167
# Run specific pipeline
168
kedro run --pipeline data_processing
169

170
# Run with tags
171
kedro run --tags preprocessing,training
172

173
# Run with parallel execution
174
kedro run --runner ParallelRunner
175

176
# Run from specific nodes
177
kedro run --from-nodes preprocess_data
178

179
# Run to specific outputs
180
kedro run --to-outputs model_metrics
181

182
# List available pipelines
183
kedro registry list
184

185
# Describe pipeline
186
kedro registry describe --pipeline training_pipeline
187
```
188

189
### Programmatic CLI Access
190

191
```python
192
from kedro.framework.cli import main
193
import sys
194

195
# Simulate CLI call programmatically
196
def run_kedro_command(command_args):
197
    """Run Kedro CLI command programmatically."""
198
    original_argv = sys.argv
199
    try:
200
        sys.argv = ["kedro"] + command_args
201
        main()
202
    finally:
203
        sys.argv = original_argv
204

205
# Run pipeline programmatically via CLI
206
run_kedro_command(["run", "--pipeline", "data_processing"])
207

208
# Package project programmatically
209
run_kedro_command(["package"])
210
```
211

212
### Project Configuration Setup
213

214
```python
215
from kedro.framework.project import configure_project, settings, pipelines
216

217
# Configure project
218
configure_project("my_project")
219

220
# Access global settings
221
conf_source = settings.CONF_SOURCE
222
hooks = settings.HOOKS
223
context_class = settings.CONTEXT_CLASS
224

225
# Access pipelines registry
226
available_pipelines = list(pipelines.keys())
227
data_pipeline = pipelines["data_processing"]
228

229
print(f"Configuration source: {conf_source}")
230
print(f"Available pipelines: {available_pipelines}")
231
```
232

233
### Custom Settings Configuration
234

235
```python
236
# In my_project/settings.py
237
from kedro.config import OmegaConfigLoader
238
from kedro.framework.context import KedroContext
239
from kedro.io import DataCatalog
240

241
# Custom configuration loader
242
CONFIG_LOADER_CLASS = OmegaConfigLoader
243
CONFIG_LOADER_ARGS = {
244
    "base_env": "base",
245
    "default_run_env": "local",
246
    "config_patterns": {
247
        "catalog": ["catalog*", "catalog*/**", "**/catalog*"],
248
        "parameters": ["parameters*", "parameters*/**", "**/parameters*"]
249
    }
250
}
251

252
# Custom context class
253
CONTEXT_CLASS = KedroContext
254

255
# Custom data catalog class  
256
DATA_CATALOG_CLASS = DataCatalog
257

258
# Project hooks
259
HOOKS = (
260
    "my_project.hooks.ProjectHooks",
261
)
262

263
# Configuration source
264
CONF_SOURCE = "conf"
265

266
# Hook plugins to disable
267
DISABLE_HOOKS_FOR_PLUGINS = (
268
    "kedro-telemetry",
269
)
270
```
271

272
### Pipeline Registry Configuration
273

274
```python
275
# In my_project/pipeline_registry.py
276
from kedro.pipeline import Pipeline
277
from my_project.pipelines import data_processing, feature_engineering, model_training
278

279
def register_pipelines():
280
    """Register project pipelines."""
281
    data_processing_pipeline = data_processing.create_pipeline()
282
    feature_pipeline = feature_engineering.create_pipeline()
283
    training_pipeline = model_training.create_pipeline()
284
    
285
    return {
286
        "data_processing": data_processing_pipeline,
287
        "feature_engineering": feature_pipeline,
288
        "model_training": training_pipeline,
289
        "__default__": data_processing_pipeline + feature_pipeline + training_pipeline
290
    }
291
```
292

293
### Automatic Pipeline Discovery
294

295
```python
296
from kedro.framework.project import find_pipelines
297

298
# Discover pipelines automatically
299
discovered_pipelines = find_pipelines(raise_errors=False)
300

301
print("Discovered pipelines:")
302
for name, pipeline in discovered_pipelines.items():
303
    print(f"  {name}: {len(pipeline.nodes)} nodes")
304

305
# Discover with error handling
306
try:
307
    strict_pipelines = find_pipelines(raise_errors=True)
308
except ImportError as e:
309
    print(f"Pipeline discovery failed: {e}")
310
```
311

312
### Custom CLI Commands
313

314
```python
315
from kedro.framework.cli.utils import command_with_verbosity
316
import click
317

318
@click.command()
319
@click.option("--env", "-e", default="local", help="Environment to use")
320
@command_with_verbosity
321
def custom_command(env, **kwargs):
322
    """Custom CLI command with verbosity support."""
323
    from kedro.framework.session import KedroSession
324
    
325
    with KedroSession.create(env=env) as session:
326
        context = session.load_context()
327
        # Custom command logic here
328
        print(f"Running custom command in {env} environment")
329
        print(f"Available pipelines: {list(context.pipelines.keys())}")
330

331
# Register custom command (typically done in plugin setup)
332
# This would be registered via entry points in setup.py/pyproject.toml
333
```
334

335
### CLI Plugin Development
336

337
```python
338
# In plugin package
339
import click
340
from kedro.framework.cli.utils import load_entry_points
341

342
@click.group(name="my-plugin")
343
def cli():
344
    """My custom Kedro plugin commands."""
345
    pass
346

347
@cli.command()
348
@click.option("--param", help="Custom parameter")
349
def custom_action(param):
350
    """Custom plugin action."""
351
    print(f"Executing custom action with param: {param}")
352

353
# Plugin entry point configuration in setup.py:
354
# entry_points={
355
#     "kedro.project_commands": [
356
#         "my-plugin = my_plugin.cli:cli"
357
#     ]
358
# }
359

360
# Load and register plugin commands
361
def load_plugins():
362
    """Load CLI plugins."""
363
    plugin_commands = load_entry_points("kedro.project_commands")
364
    for command in plugin_commands:
365
        # Register command with main CLI
366
        pass
367
```
368

369
### Project Validation and Health Checks
370

371
```python
372
from kedro.framework.project import validate_settings, configure_project
373
from kedro.utils import find_kedro_project
374
from pathlib import Path
375

376
def validate_project_health(project_path):
377
    """Validate project configuration and health."""
378
    project_path = Path(project_path)
379
    
380
    # Check if valid Kedro project
381
    if not find_kedro_project(project_path):
382
        raise ValueError(f"Not a valid Kedro project: {project_path}")
383
    
384
    # Change to project directory
385
    import os
386
    os.chdir(project_path)
387
    
388
    # Configure project
389
    package_name = project_path.name
390
    configure_project(package_name)
391
    
392
    # Validate settings
393
    try:
394
        validate_settings()
395
        print("✓ Settings validation passed")
396
    except Exception as e:
397
        print(f"✗ Settings validation failed: {e}")
398
        return False
399
    
400
    # Check pipelines
401
    try:
402
        from kedro.framework.project import pipelines
403
        pipeline_count = len(pipelines)
404
        print(f"✓ Found {pipeline_count} pipelines")
405
    except Exception as e:
406
        print(f"✗ Pipeline loading failed: {e}")
407
        return False
408
    
409
    return True
410

411
# Usage
412
is_healthy = validate_project_health("/path/to/project")
413
```
414

415
## Types
416

417
```python { .api }
418
from typing import Dict, List, Any, Callable, Optional
419
from kedro.pipeline import Pipeline
420

421
CommandFunction = Callable[..., Any]
422
SettingsDict = Dict[str, Any]
423
PipelineRegistry = Dict[str, Pipeline]
424
EntryPointGroup = str
425
PackageName = str
426
LoggingConfig = Dict[str, Any]
427
```