Command Line Interface
Relevant source files
The following files were used as context for generating this wiki page:
The Command Line Interface (CLI) in the Meltano Singer SDK provides a standardized entry point for interacting with Singer taps, targets, and mappers. It enables developers and users to configure, discover, and execute data extraction and loading pipelines through a consistent set of commands and arguments.
The CLI is built primarily using the click library, ensuring that all plugins built with the SDK inherit a uniform interface compliant with the Singer specification. This includes support for configuration via JSON files or environment variables, as well as metadata discovery and version reporting.
Sources: pyproject.toml:50, CLAUDE.md:73-77, cookiecutter/tap-template/{{cookiecutter.tap_id}}/README.md:68-72
Architecture and Core Components
The CLI architecture is centered around a decorator-based approach that injects standard Singer options into the plugin's execution flow.
The CLI Decorator
The plugin_cli decorator is the primary mechanism for generating the command-line interface for any SDK-based plugin. It wraps the plugin class and provides the necessary click boilerplate to handle arguments like --config, --version, and --about.
Execution Flow
When a plugin is executed via its script entry point, the CLI parses the provided arguments and initializes the plugin class with the resolved configuration.
Standard CLI Commands and Options
All SDK plugins support a common set of options that facilitate integration with orchestrators like Meltano.
| Option | Description | Context |
|---|---|---|
--config | Path to a JSON configuration file or ENV to use environment variables. | All Plugins |
--version | Display the version of the plugin. | All Plugins |
--about | Output detailed information about the plugin, settings, and capabilities. | All Plugins |
--format | Used with --about to specify output format (e.g., markdown). | All Plugins |
--discover | Run the tap in discovery mode to generate a catalog. | Taps Only |
--catalog | Path to a catalog file for selecting streams and fields. | Taps Only |
--state | Path to a state file for incremental syncs. | Taps Only |
| Sources: cookiecutter/tap-template/{{cookiecutter.tap_id}}/README.md:41-43, 68-72, singer_sdk/cli/_decorator.py |
Configuration Handling
The CLI supports dual-source configuration. It can read from a provided JSON file via the --config flag or automatically import environment variables if --config=ENV is specified. Environment variables are matched against the plugin's setting names.
Sources: cookiecutter/tap-template/{{cookiecutter.tap_id}}/README.md:46-51
Entry Point Definition
Plugins define their CLI entry point in their pyproject.toml file. This maps a terminal command to the cli property of the plugin class.
[project.scripts]
tap-dummyjson = 'tap_dummyjson.tap:TapDummyJSON.cli'
Sources: packages/meltano-tap-dummyjson/pyproject.toml:34-35
Developer Tools and Integration
The CLI is designed to work seamlessly with the uv package manager and the Meltano orchestrator.
Direct Execution with uv
During development, the CLI can be invoked without installing the package globally by using uv run.
uv run tap-my-source --help
uv run tap-my-source --config config.json --discover > catalog.json
Sources: cookiecutter/tap-template/{{cookiecutter.tap_id}}/README.md:88-92, 68-72
Meltano Integration
Meltano uses the CLI's --about and discovery capabilities to automatically configure the plugin within a project.
meltano invoke tap-my-source --version
meltano run tap-my-source target-jsonl
Sources: cookiecutter/tap-template/{{cookiecutter.tap_id}}/README.md:107-113
Summary
The Command Line Interface is a fundamental part of the Meltano Singer SDK, providing the standard "plumbing" required for Singer compliance. By using the plugin_cli decorator, developers ensure their taps and targets support critical operational features such as configuration via environment variables, automated metadata discovery, and standardized help output, allowing them to focus on data extraction and loading logic.
Sources: README.md:10-15, CLAUDE.md:73-77