Command-Line Interface (CLI)

Relevant source files

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

• monitor/main.py
• pyproject.toml
• README.md
• WARP.md
• monitor/config.py
• DEMO.md

The technical-blog-monitor is executed and controlled through its command-line interface. The primary entry point is the monitor script, which is an alias for the main function within the monitor.main module. This CLI allows users to run the application as a persistent daemon or for a single execution, specify which feeds to process, and override configuration settings like the log level.

The script is defined in the project's pyproject.toml file, making it accessible after installation via tools like poetry or uv. The core logic for parsing arguments and orchestrating the application's lifecycle based on those arguments resides in monitor/main.py.

Sources: pyproject.toml:27, monitor/main.py

Usage

The application is typically run using a project-specific runner like uv or poetry.

# Using uv
uv run monitor [OPTIONS]

# Using poetry
poetry run monitor [OPTIONS]

These commands execute the main function in monitor/main.py, which serves as the application's entry point.

Sources: README.md:58, WARP.md:21, pyproject.toml:27

Command-Line Arguments

The CLI accepts several arguments to control its behavior. These are parsed using Python's argparse module.

Argument	Type	Description
--config	string	Path to a configuration file.
--once	boolean	If present, the application runs once and then exits. If omitted, it runs in daemon mode.
--feed	string	The name of a specific feed to process. If provided, only this feed will be processed.
--log-level	string	Overrides the log level. Choices are DEBUG, INFO, WARNING, ERROR, CRITICAL.

Sources: monitor/main.py:530-553

The arguments are defined in the parse_args function:

# monitor/main.py:530-553
def parse_args() -> argparse.Namespace:
    """Parse command line arguments."""
    parser = argparse.ArgumentParser(
        description=_("Technical Blog Monitor - Track and embed technical blog posts")
    )
    
    parser.add_argument(
        "--config",
        help="Path to configuration file",
        default=None
    )
    
    parser.add_argument(
        "--once",
        action="store_true",
        help="Run once and exit (don't run as daemon)"
    )
    
    parser.add_argument(
        "--feed",
        help="Process only the specified feed (by name)",
        default=None
    )
    
    parser.add_argument(
        "--log-level",
        choices=[level.value for level in LogLevel],
        default=None,
        help="Set the log level"
    )
    
    return parser.parse_args()

Sources: monitor/main.py:530-553

Execution Modes

The application can run in two primary modes, determined by the presence of the --once flag.

Daemon Mode (Default)

When run without the --once flag, the application starts in daemon mode. This is the default behavior for production or continuous monitoring.

• The run_daemon function is invoked.
• It initializes all application components within the app_lifecycle context manager.
• It sets up signal handlers for SIGINT and SIGTERM to ensure graceful shutdown.
• The application runs indefinitely, waiting for a shutdown signal, while the APScheduler instance triggers feed processing jobs at their configured intervals.

Sources: monitor/main.py:488-511, monitor/main.py:586-587

The following diagram illustrates the lifecycle of the daemon mode.

One-Shot Mode (--once)

When the --once flag is provided, the application performs a single run and then exits. This mode is useful for testing, debugging, or for environments where monitoring is triggered by an external scheduler like a cron job.

• The run_once function is invoked.
• It initializes all application components, just like daemon mode.
• It creates and awaits tasks to process each enabled feed once.
• After all feed processing tasks are complete, the application gracefully shuts down and exits.

Sources: monitor/main.py:514-528, monitor/main.py:583-584

The following diagram shows the execution flow for the one-shot mode.

Application Startup Flow

The main() function in monitor/main.py orchestrates the entire startup process.

1. Parse Arguments: It calls parse_args() to read any command-line flags.
2. Load Settings: It calls load_settings() to load configuration from the .env file and environment variables.
3. Override Settings: It overrides settings with values from CLI arguments. For example, --log-level updates settings.metrics.log_level.
4. Setup Logging: It initializes the structlog logger with the configured level and format.
5. Filter Feeds: If the --feed argument is used, it filters the list of feeds to be processed to only the one specified.
6. Select Mode: Based on the --once flag, it calls either run_daemon() or run_once() to start the application.
7. Handle Shutdown: It includes try...except blocks to catch KeyboardInterrupt and other exceptions for a clean exit.

Sources: monitor/main.py:556-596

This sequence diagram illustrates the startup process.

Practical Examples

The following are common commands used to run the monitor.

Run once in debug mode:
This is useful for testing changes and seeing detailed logs.

poetry run monitor --once --log-level DEBUG

Sources: WARP.md:21-23, DEMO.md:71-73

Run a specific feed:
This isolates processing to a single feed, which is helpful for debugging a problematic feed.

uv run monitor --feed "Google Cloud Blog" --once

Sources: README.md:91-93, WARP.md:25-26

Run as a daemon:
This is the standard command for continuous monitoring in a production environment.

uv run monitor

Sources: README.md:63