Command Line Interface Guide
Relevant source files
The following files were used as context for generating this wiki page:
The Meltano Command Line Interface (CLI) serves as the primary entry point for managing data integration pipelines, project configuration, and plugin execution. It is built using the click library and structured into a primary meltano group with specialized subcommands for various lifecycle tasks such as installation, configuration, and orchestration.
Meltano's CLI follows a declarative approach where commands interact with the meltano.yml project file and the project's system database to manage state and environments.
CLI Architecture and Entry Point
The CLI entry point is defined in src/meltano/cli/cli.py. It initializes the project context, handles global options like logging levels and environment selection, and routes execution to specific subcommands.
Global Configuration Flow
When any meltano command is executed, the CLI performs several setup steps:
- Environment Detection: Determines the active Meltano environment (e.g., dev, prod) via the
--environmentflag orMELTANO_ENVIRONMENTvariable. - Project Initialization: Locates and loads the
Projectcontext. - Telemetry and Logging: Configures structured logging and anonymous usage statistics.
Core Orchestration Commands
The run Command
The meltano run command is the primary tool for executing blocks of plugins in sequence. It supports complex blocks including extractors, loaders, and mappers.
| Option | Description | Environment Variable |
|---|---|---|
--dry-run | List blocks without executing them | MELTANO_RUN_DRY_RUN |
--no-install | Skip automatic installation of missing plugins | MELTANO_RUN_NO_INSTALL |
--state-id | Specify a custom ID for state persistence | MELTANO_RUN_STATE_ID |
--timeout | Maximum execution time in seconds | MELTANO_RUN_TIMEOUT |
Sources: src/meltano/cli/run.py:50-120
The invoke Command
The meltano invoke command allows direct execution of a specific plugin's executable. This is used for running maintenance tasks, debugging, or using utility plugins like dbt or airflow directly.
Sources: src/meltano/cli/invoke.py:10-80
Configuration Management
Configuration can be managed via the meltano config subcommand, which provides interfaces for viewing, setting, and testing settings for the project or specific plugins.
Interactive Configuration
Meltano provides an interactive mode for configuration, implemented in src/meltano/cli/interactive/config.py. This mode guides users through settings one by one, providing descriptions and documentation links.
Meltano resolves configuration values using the following precedence:
- Environment variables
meltano.ymlproject file- Project system database
- Default values in plugin metadata
Sources: src/meltano/cli/interactive/config.py:30-60
Config Subcommands Summary
- list: Lists all settings for a plugin with their current values and sources.
- set: Updates a setting value in a specified store (e.g.,
meltano.ymlordotenv). - unset: Removes a configuration override.
- test: Validates the current configuration against the plugin (supported for extractors and loaders).
Sources: src/meltano/cli/config.py:1-100
CLI Environment and Settings Schema
The CLI's behavior and the valid structure of the project configuration it manages are governed by a JSON schema.
| Property | Type | Default | Description |
|---|---|---|---|
database_uri | string | sqlite:///.meltano/meltano.db | System database location |
send_anonymous_usage_stats | boolean | true | Usage telemetry toggle |
auto_install | boolean | true | Toggle for automatic plugin installation |
venv.backend | enum | virtualenv | Virtualenv backend (virtualenv or uv) |
Sources: src/meltano/schemas/meltano.schema.json:15-150
Error Handling and Validation
The CLI utilizes meltano.core service classes to validate commands before execution. For instance, the run command validates that extractors and loaders are correctly paired and that mappers are positioned between them when necessary. Known CLI-level errors are caught to avoid displaying Python tracebacks unless the --debug flag is provided.
Sources: src/meltano/cli/run.py:150-250, CHANGELOG.md:140-150
Summary
The Meltano CLI is a comprehensive toolset for declarative ELT. It centralizes project lifecycle management through the meltano.yml manifest, provides orchestration via the run command, and offers both CLI and interactive interfaces for complex plugin configuration. Key features like environment-specific overrides and automatic plugin installation through the uv or virtualenv backends ensure consistency across development and production environments.