Command Line Interface (CLI)
Relevant source files
The following files were used as context for generating this wiki page:
The Command Line Interface (CLI) for FLEXT Meltano serves as a flat public facade for orchestrating data integration operations. It provides a unified entry point to manage ELT pipelines, discover plugins, execute DBT transformations, and monitor system health. The CLI is designed to wrap underlying Meltano and Singer functionality into a structured, enterprise-ready interface using the railway-oriented programming (r) pattern for consistent error handling.
Sources: src/flext_meltano/cli.py:12-14, src/flext_meltano/README.md
Architecture and Design
The CLI architecture centers around the FlextMeltanoCLI class, which inherits from the core FlextMeltano application class. It utilizes a command routing pattern to delegate specific operations to specialized handlers or managers.
Command Routing Flow
The route_command method acts as the central dispatcher. It maps input arguments to specific handler functions, ensuring that help requests are intercepted and banners are displayed appropriately.
The CLI uses a command_map to link string commands (like pipeline, tap, target) to their respective methods.
Sources: src/flext_meltano/cli.py:108-132
Core Command Handlers
The CLI organizes functionality into distinct command groups, each managed by dedicated handlers.
Pipeline Management
Managed by FlextMeltanoPipelineManager, this section handles the lifecycle of data pipelines, including creation, execution, and deletion.
| Command | Action | Implementation |
|---|---|---|
create | Persists a new pipeline configuration | PipelineCommand.CREATE |
run | Executes a defined pipeline | PipelineCommand.RUN |
stop | Terminates a running pipeline via PID file | PipelineCommand.STOP |
status | Checks if a pipeline is 'running' or 'stopped' | PipelineCommand.STATUS |
list | Lists all stored pipelines | PipelineCommand.LIST |
Sources: src/flext_meltano/cli.py:30-32, tests/unit/tests_pipeline_cli_managers.py:65-102, tests/unit/tests_pipeline_cli_managers.py:126-155
Plugin Discovery and Information
The handle_plugin_command allows users to interact with the Meltano plugin ecosystem. It supports listing installed plugins and fetching detailed information about specific plugin entities.
Sources: src/flext_meltano/cli.py:53-100
System Status and Health
The status group provides visibility into the operational state of the FLEXT Meltano environment.
- Show: Returns a JSON payload representing the current project status (e.g.,
READY). - Health: Executes health checks and returns diagnostic data in JSON format.
- Version: Directly returns the version string of the underlying Meltano and bridge implementation.
Sources: src/flext_meltano/cli.py:91-105, tests/unit/test_cli_small_managers.py:23-42
Data Models and Parameter Integration
The CLI integrates tightly with Pydantic models to ensure type-safe parameter passing from the command line to the internal service layer. The u.Cli.cli_args_to_model utility is used to convert raw dictionary arguments into structured objects like TapRunParams.
Common CLI Parameters
| Parameter | Type | Description |
|---|---|---|
tap_name | str | Required identifier for the extractor plugin |
discover | bool | Whether to run the tap in discovery mode |
config_file | str | Path to a custom settings JSON file |
catalog_file | str | Path to a Singer catalog file |
state_file | str | Path to a state file for incremental syncs |
Sources: tests/unit/test_cli_integration.py:28-76, src/flext_meltano/_protocols/services.py:25-50
Implementation Details
Protocols
The CLI structure is governed by several Protocol definitions to maintain decoupling and support dependency injection. Key protocols include:
MeltanoExecutor: Defines requirements for executing Meltano and DBT commands.CLIManager: Base protocol for handlers.CLI: A composite protocol that avoids circular imports by defining the required handler methods (e.g.,handle_pipeline_command,handle_dbt_command).
Sources: src/flext_meltano/_protocols/services.py:16-160
Standard Options and Constants
The CLI adheres to standard Meltano CLI flags defined in the base constants.
# Constants used for command generation and routing
CMD_BINARY = "meltano"
CMD_ENVIRONMENT_OPTION = "--environment"
CMD_HELP_OPTION = "--help"
CMD_VERSION_OPTION = "--version"
PIPELINE_DEFAULT_ROOT_ENV = "FLEXT_PIPELINES_ROOT"
Sources: src/flext_meltano/_constants/base.py:50-70, tests/unit/tests_pipeline_cli_managers.py:18-22
Summary
The Command Line Interface (CLI) provides a robust, typed interface for managing the FLEXT Meltano environment. By centralizing command routing and leveraging Pydantic models for validation, it ensures that interactions with underlying data tools—such as Meltano, Singer, and DBT—are handled consistently and safely. The use of railway-oriented programming ensures that errors are propagated as structured results, making the CLI suitable for both interactive use and automated orchestration.