List Command Details

Relevant source files

The following files were used as context for generating this wiki page:

• cron_ext/main.py
• cron_ext/extension.py
• cron_ext/entry.py
• cron_ext/stores/crontab.py
• cron_ext/stores/base.py
• cron_ext/stores/stdout.py
• README.md

The list command is a core utility of the cron-ext Meltano extension designed to display cron entries currently managed for the active project. It allows users to audit which schedules have been successfully installed into the system crontab and identify "orphaned" entries—schedules that exist in the crontab but are no longer defined in the meltano.yml configuration.

Sources: README.md:65-69, cron_ext/main.py:59-93

Command Architecture and Data Flow

The list command operates by interfacing with an EntryStore to retrieve raw crontab lines and then applying filters based on the project's current schedule definitions. The command logic is primarily housed in cron_ext/main.py, supported by the Cron extension class which provides project-specific metadata.

Execution Flow

1. The user invokes meltano invoke cron list.
2. The list_command function initializes a Cron extension instance with the specified target (defaulting to crontab).
3. It retrieves the current entries from the store (e.g., CrontabEntryStore).
4. It parses each entry using a regular expression to extract the schedule name.
5. It applies filtering logic to determine if the entry should be displayed based on orphaned status.
6. The resulting list is echoed to the terminal.

The diagram shows the sequence of operations from command invocation to final output display.
Sources: cron_ext/main.py:60-89, cron_ext/extension.py:33-46

Filtering and Orphaned Status

A key feature of the list command is the ability to filter schedules based on their relationship with the current Meltano project configuration.

• Orphaned Schedules: Entries found in the crontab that correspond to the project ID but do not have a matching schedule name in the current meltano.yml.
• Non-Orphaned Schedules: Entries in the crontab that successfully map to active Meltano schedules.

The _orphaned_filter_predicate function generates a lambda that checks the parsed name against ext.meltano_schedule_ids.

Parameter	Type	Default	Description
--name-only	Boolean	False	If true, only outputs the schedule name (e.g., daily) instead of the full cron line.
--orphaned	Boolean/None	None	Filters for orphaned schedules only.
--not-orphaned	Boolean/None	None	Filters for non-orphaned schedules only.
target	Enum	crontab	The source of entries (crontab or stdout).

Sources: cron_ext/main.py:48-57, cron_ext/main.py:60-75

Entry Parsing Logic

The command relies on the entry_pattern regular expression to extract identifying information from the crontab lines. This pattern is designed to find the shell script path and capture the filename (without extension) as the schedule name.

# cron_ext/entry.py
entry_pattern = re.compile(r"(?i)^.+?'(?P<path>/?(?:.*/)(?P<name>.*)\.sh)'.*$")

The list command uses the _get_name_entry_pairs helper to process raw strings into structured (name, full_entry) tuples.

Sources: cron_ext/entry.py:6, cron_ext/main.py:42-46

Integration with Entry Stores

The list command behaves differently depending on the Target store selected:

CrontabEntryStore

When using the default crontab target, the store executes crontab -l to fetch all system entries for the current user. It then isolates the section specific to the Meltano project using the project ID found in the MELTANO_PROJECT_ID environment variable.

StdoutEntryStore

The stdout store is considered "unmanaged." When the list command is called against stdout, it always returns an empty tuple because this store does not persist entries for later retrieval.

The class diagram illustrates the relationship between the base EntryStore and its specific implementations used by the command.
Sources: cron_ext/stores/base.py:10-27, cron_ext/stores/crontab.py:15-32, cron_ext/stores/stdout.py:12-25

Conclusion

The list command provides visibility into the state of cron job synchronization. By leveraging project-specific tagging in the crontab and cross-referencing with active Meltano metadata, it ensures developers can accurately track scheduled tasks and clean up obsolete entries.

Sources: README.md:65-69, cron_ext/main.py:77-93