CLI Overview
Relevant source files
The following files were used as context for generating this wiki page:
The cron-ext CLI is a Meltano utility extension designed to manage job scheduling by converting Meltano schedules into standard cron entries. It allows users to install, list, and uninstall schedules within a system crontab or output them to stdout. The CLI acts as a wrapper around the Cron extension class, providing a user-friendly interface for managing periodic Meltano tasks.
Sources: README.md:3-10, cron_ext/main.py:20-25
Command Structure
The CLI is built using the typer library and exposes several primary commands to manage the lifecycle of cron-based schedules.
Primary Commands
| Command | Description | Supported Arguments/Options |
|---|---|---|
initialize | A no-op command intended for extension setup. | --force |
install | Installs Meltano schedules into the target store. | schedule_ids, --target |
list | Lists currently installed cron entries for the project. | --target, --name-only, --orphaned/--not-orphaned |
uninstall | Removes cron entries from the managed store. | schedule_ids, --all, --target |
describe | Describes available commands and capabilities. | --format (text, json, yaml) |
Sources: cron_ext/main.py:28-125, cron_ext/extension.py:145-156
Execution Flow
When a command is invoked, the CLI initializes the Cron extension class, which determines the target storage mechanism (crontab or stdout) and interacts with the Meltano project environment.
The diagram shows how user requests flow through the main.py entry point to the Cron extension logic and finally to the selected storage backend.
Sources: cron_ext/main.py:59-106, cron_ext/extension.py:35-46
Detailed Logic and Operations
Installation and Schedule Mapping
The install command fetches schedules from Meltano via meltano schedule list --format=json. For each schedule, it generates a shell script in .meltano/run/cron-ext/ that handles environment activation and directory context before executing the meltano run or meltano elt command.
Sources: cron_ext/extension.py:65-73, cron_ext/extension.py:83-108
Store Targets
The CLI supports two primary targets for its operations:
- crontab: Interacts directly with the system's
crontab -landcrontab -commands. It uses specific comment headers (# --- BEGIN MELTANO CRONTAB SECTION ...) to isolate project-specific entries. - stdout: A non-managed store that simply prints the generated cron entries to the console.
Sources: cron_ext/stores/crontab.py:21-65, cron_ext/stores/stdout.py:15-32, cron_ext/init.py:10-14
Entry Identification
Entries are identified and parsed using a specific regex pattern that looks for the generated .sh script path and extracts the schedule name.
# cron_ext/entry.py:6
entry_pattern = re.compile(r"(?i)^.+?'(?P<path>/?(?:.*/)(?P<name>.*)\.sh)'.*$")
Sources: cron_ext/entry.py:6
Uninstallation Logic
The uninstall command provides flexible removal options. It can remove specific named schedules, all schedules associated with the current Meltano project, or "orphaned" entries that exist in the crontab but are no longer defined in meltano.yml.
The sequence diagram illustrates the uninstallation process, specifically how the extension filters existing entries and updates the crontab while cleaning up local script files.
Sources: cron_ext/extension.py:133-154, cron_ext/stores/crontab.py:73-85
Environment and Path Handling
During the generation of cron entries, the extension captures the PATH and VIRTUAL_ENV variables from the environment where the install command was executed. These are embedded into the generated shell scripts to ensure the cron job runs in the same environment as the manual installation.
Sources: cron_ext/extension.py:84-95, README.md:15-20
The cron-ext CLI provides a robust mechanism for bridgeing Meltano's internal scheduling with the system's native cron daemon, ensuring environment consistency and project isolation within the crontab.