gitwebhooks 2.2.0__py3-none-any.whl → 2.3.0__py3-none-any.whl

gitwebhooks/__init__.py

@@ -3,7 +3,7 @@
 Automated deployment server supporting GitHub, Gitee, GitLab, and custom webhooks.
 """
 
-__version__ = '2.2.0'
+__version__ = '2.3.0'
 
 # Export main classes for convenient import paths
 from .server import WebhookServer

gitwebhooks/cli/__init__.py

@@ -5,6 +5,8 @@ Provides subcommand registration and implementation for gitwebhooks-cli.
 
 from gitwebhooks.cli.service import cmd_install, cmd_uninstall
 from gitwebhooks.cli.config import cmd_init, cmd_view
+from gitwebhooks.cli.help import cmd_help
+from gitwebhooks.cli.serve import cmd_serve
 
 
 def register_subparsers(subparsers):
@@ -16,15 +18,101 @@ def register_subparsers(subparsers):
     Returns:
         None
     """
-    # Register service subcommand
-    register_service_subparser(subparsers)
+    # Register help subcommand
+    register_help_subparser(subparsers)
+
+    # Register serve subcommand
+    register_serve_subparser(subparsers)
 
     # Register config subcommand
     register_config_subparser(subparsers)
 
+    # Register service subcommand (deprecated, for backward compatibility)
+    register_service_subparser(subparsers)
+
+
+def register_serve_subparser(subparsers):
+    """Register serve subcommand and its actions
+
+    Args:
+        subparsers: argparse subparsers object
+
+    Returns:
+        None
+    """
+    serve_parser = subparsers.add_parser(
+        'serve',
+        add_help=False,
+        help='Start webhook server or manage systemd service'
+    )
+    serve_parser.add_argument(
+        '-c', '--config',
+        dest='config',
+        help='Path to configuration file (default: auto-discover)'
+    )
+    serve_subparsers = serve_parser.add_subparsers(dest='serve_action')
+
+    # install action
+    install_parser = serve_subparsers.add_parser('install', add_help=False)
+    install_parser.add_argument(
+        '--force',
+        action='store_true',
+        help='Force overwrite existing service'
+    )
+    install_parser.add_argument(
+        '--verbose',
+        action='count',
+        default=0,
+        help='Increase verbosity'
+    )
+    install_parser.add_argument(
+        '--dry-run',
+        action='store_true',
+        help='Preview mode without making changes'
+    )
+    install_parser.add_argument(
+        '--config-level',
+        choices=['user', 'local', 'system'],
+        help='Configuration file level (user/local/system)'
+    )
+    install_parser.set_defaults(func=cmd_serve)
+
+    # uninstall action
+    uninstall_parser = serve_subparsers.add_parser('uninstall', add_help=False)
+    uninstall_parser.add_argument(
+        '--purge',
+        action='store_true',
+        help='Also remove configuration file'
+    )
+    uninstall_parser.set_defaults(func=cmd_serve)
+
+    # Set default function for serve (when no action specified)
+    serve_parser.set_defaults(func=cmd_serve)
+
+
+def register_help_subparser(subparsers):
+    """Register help subcommand
+
+    Args:
+        subparsers: argparse subparsers object
+
+    Returns:
+        None
+    """
+    help_parser = subparsers.add_parser(
+        'help',
+        add_help=False
+    )
+    help_parser.add_argument(
+        'topic',
+        nargs='?',
+        help='Subcommand to show help for (serve, config)'
+    )
+    help_parser.set_defaults(func=cmd_help)
+
 
 def register_service_subparser(subparsers):
-    """Register service subcommand and its actions
+    """Register service subcommand and its actions (deprecated)
 
     Args:
         subparsers: argparse subparsers object
@@ -34,12 +122,13 @@ def register_service_subparser(subparsers):
     """
     service_parser = subparsers.add_parser(
         'service',
-        help='Manage systemd service installation'
+        add_help=False,
+        help='Manage systemd service installation (deprecated, use "serve" instead)'
     )
     service_subparsers = service_parser.add_subparsers(dest='service_action')
 
     # install action
-    install_parser = service_subparsers.add_parser('install')
+    install_parser = service_subparsers.add_parser('install', add_help=False)
     install_parser.add_argument(
         '--force',
         action='store_true',
@@ -56,10 +145,15 @@ def register_service_subparser(subparsers):
         action='store_true',
         help='Preview service file without installing'
     )
+    install_parser.add_argument(
+        '--config-level',
+        choices=['user', 'local', 'system'],
+        help='Configuration file level (user/local/system). If not specified, will be prompted.'
+    )
     install_parser.set_defaults(func=cmd_install)
 
     # uninstall action
-    uninstall_parser = service_subparsers.add_parser('uninstall')
+    uninstall_parser = service_subparsers.add_parser('uninstall', add_help=False)
     uninstall_parser.add_argument(
         '--purge',
         action='store_true',
@@ -79,6 +173,7 @@ def register_config_subparser(subparsers):
     """
     config_parser = subparsers.add_parser(
         'config',
+        add_help=False,
         help='Manage gitwebhooks configuration'
     )
     config_subparsers = config_parser.add_subparsers(dest='config_action')
@@ -86,6 +181,7 @@ def register_config_subparser(subparsers):
     # init action
     init_parser = config_subparsers.add_parser(
         'init',
+        add_help=False,
         help='Initialize configuration file using interactive wizard'
     )
     init_parser.add_argument(
@@ -97,7 +193,7 @@ def register_config_subparser(subparsers):
     init_parser.set_defaults(func=cmd_init)
 
     # view action
-    view_parser = config_subparsers.add_parser('view')
+    view_parser = config_subparsers.add_parser('view', add_help=False)
     view_parser.add_argument(
         '-c',
         '--config',

gitwebhooks/cli/help.py

@@ -0,0 +1,155 @@
+"""Help command module
+
+Provides help information display functionality for gitwebhooks-cli.
+"""
+
+import argparse
+import sys
+
+
+def cmd_help(args: argparse.Namespace) -> int:
+    """Handle help subcommand.
+
+    Displays main help or subcommand-specific help depending on the topic.
+
+    Args:
+        args: Parsed command-line arguments
+            - topic: Optional subcommand name to show help for
+
+    Returns:
+        Exit code (0 = success)
+
+    Examples:
+        >>> args = argparse.Namespace(topic=None)
+        >>> cmd_help(args)  # doctest: +SKIP
+        0
+        >>> args = argparse.Namespace(topic='serve')
+        >>> cmd_help(args)  # doctest: +SKIP
+        0
+    """
+    # Import here to avoid circular dependency
+    from gitwebhooks.main import get_parser
+
+    parser = get_parser()
+
+    if hasattr(args, 'topic') and args.topic:
+        # Show subcommand help
+        show_subcommand_help(parser, args.topic)
+    else:
+        # Show main help
+        show_main_help(parser)
+
+    return 0
+
+
+def show_main_help(parser: argparse.ArgumentParser) -> None:
+    """Display main help information.
+
+    Args:
+        parser: The main argument parser
+
+    Returns:
+        None
+    """
+    # Custom help output
+    help_text = """Git Webhooks Server - Automated deployment webhook handler
+
+Usage:
+  gitwebhooks-cli [-v] [-c CONFIG] <command> [<args>]
+
+Commands:
+  serve       Start webhook server or manage systemd service
+  config      Manage configuration file
+  help        Show help information
+
+Options:
+  -v, --version  Show version information
+  -c, --config   Path to configuration file (default: auto-discover)
+
+Examples:
+  gitwebhooks-cli serve                    # Start server
+  gitwebhooks-cli serve install            # Install systemd service
+  gitwebhooks-cli config init              # Initialize configuration
+  gitwebhooks-cli help serve               # Show serve command help
+
+For more information on a specific command:
+  gitwebhooks-cli help <command>
+"""
+    print(help_text)
+
+
+def show_subcommand_help(parser: argparse.ArgumentParser, topic: str) -> None:
+    """Display help for a specific subcommand.
+
+    Args:
+        parser: The main argument parser
+        topic: Subcommand name
+
+    Returns:
+        None
+    """
+    # Map topic to help text
+    help_texts = {
+        'serve': """Command: serve
+Start webhook server or manage systemd service
+
+Usage:
+  gitwebhooks-cli serve [-c CONFIG]
+  gitwebhooks-cli serve install [--force] [--dry-run] [--verbose]
+  gitwebhooks-cli serve uninstall [--purge]
+
+Subcommands:
+  (none)        Start the webhook server
+  install       Install systemd service
+  uninstall     Uninstall systemd service
+
+Options:
+  -c, --config   Path to configuration file
+
+Install options:
+  --force        Force overwrite existing service
+  --dry-run      Preview mode, don't make changes
+  --verbose      Increase verbosity
+
+Uninstall options:
+  --purge        Also remove configuration file
+
+Examples:
+  gitwebhooks-cli serve                         # Start server
+  gitwebhooks-cli serve -c /etc/webhooks.ini    # Start with custom config
+  gitwebhooks-cli serve install                 # Install service
+  gitwebhooks-cli serve install --force         # Force overwrite
+  gitwebhooks-cli serve uninstall               # Uninstall service
+""",
+        'config': """Command: config
+Manage configuration file
+
+Usage:
+  gitwebhooks-cli config init [level]
+  gitwebhooks-cli config view [-c CONFIG]
+
+Subcommands:
+  init          Initialize configuration file
+  view          View configuration file
+
+Init arguments:
+  level         Configuration level (system, local, user)
+
+View options:
+  -c, --config  Path to configuration file
+
+Examples:
+  gitwebhooks-cli config init              # Interactive init
+  gitwebhooks-cli config init user         # User-level config
+  gitwebhooks-cli config init system       # System-level config (requires sudo)
+  gitwebhooks-cli config view              # View current config
+""",
+    }
+
+    if topic in help_texts:
+        print(help_texts[topic])
+    else:
+        print(f"Error: Unknown command '{topic}'", file=sys.stderr)
+        print("Available commands: serve, config", file=sys.stderr)
+        print()
+        print("Use 'gitwebhooks-cli help' to see main help", file=sys.stderr)

gitwebhooks/cli/prompts.py

@@ -4,7 +4,9 @@ Provides functions for interactive user input and validation.
 """
 
 import sys
-from typing import Any, Callable, Optional, Dict, List
+from typing import Any, Callable, Optional, Dict, List, Tuple
+
+from gitwebhooks.utils.constants import ConfigLevel
 
 
 # Question template for configuration initialization
@@ -273,3 +275,48 @@ def validate_text(value: str) -> str:
     if not value:
         raise ValueError('Input cannot be empty')
     return value
+
+
+def ask_config_level() -> ConfigLevel:
+    """Ask user to select configuration file level
+
+    Displays an interactive menu for selecting configuration file level
+    with descriptions of each option.
+
+    Returns:
+        Selected ConfigLevel enum value
+
+    Raises:
+        KeyboardInterrupt: If user confirms exit on Ctrl+C
+    """
+    print('Select configuration file level for the service:')
+    print('  1. User level (~/.gitwebhooks.ini) - Single user, highest priority')
+    print('  2. Local level (/usr/local/etc/gitwebhooks.ini) - Local system, medium priority')
+    print('  3. System level (/etc/gitwebhooks.ini) - Global system, lowest priority')
+    print()
+
+    choice_map = {
+        '1': ConfigLevel.USER,
+        '2': ConfigLevel.LOCAL,
+        '3': ConfigLevel.SYSTEM,
+    }
+
+    while True:
+        try:
+            response = input('Enter choice [1-3] (default: 1): ').strip()
+
+            # Use default if empty input
+            if not response:
+                return ConfigLevel.USER
+
+            # Validate and map response
+            if response in choice_map:
+                return choice_map[response]
+
+            # Invalid input
+            print('Invalid choice. Please enter a number between 1 and 3.')
+
+        except KeyboardInterrupt:
+            if ask_yes_no('Confirm exit? (y/N) ', default=False):
+                print('\nService installation cancelled')
+                sys.exit(0)

gitwebhooks/cli/serve.py

@@ -0,0 +1,151 @@
+"""Serve command module
+
+Provides server startup and systemd service management functionality.
+"""
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Optional
+
+from gitwebhooks.server import WebhookServer
+from gitwebhooks.utils.exceptions import ConfigurationError
+from gitwebhooks.utils.constants import CONFIG_SEARCH_PATHS
+
+# Import service management functions
+from gitwebhooks.cli.service import (
+    cmd_install as service_cmd_install,
+    cmd_uninstall as service_cmd_uninstall,
+    install_service,
+    uninstall_service,
+)
+
+# Import version display
+from gitwebhooks import __version__
+
+
+def cmd_serve(args: argparse.Namespace) -> int:
+    """Handle serve subcommand.
+
+    This function dispatches to the appropriate serve action:
+    - No action: Start the webhook server
+    - install: Install systemd service
+    - uninstall: Uninstall systemd service
+
+    Args:
+        args: Parsed command-line arguments
+            - serve_action: The serve sub-action (install, uninstall, or None)
+            - config: Configuration file path (from global -c argument)
+            - force: Force overwrite existing service (install action)
+            - dry_run: Preview mode (install action)
+            - verbose: Verbosity level (install action)
+            - purge: Also remove config file (uninstall action)
+
+    Returns:
+        Exit code (0 = success, 1 = error)
+    """
+    # Get serve_action from args
+    serve_action = getattr(args, 'serve_action', None)
+
+    if serve_action == 'install':
+        # Delegate to service install command
+        return service_cmd_install(args)
+    elif serve_action == 'uninstall':
+        # Delegate to service uninstall command
+        return service_cmd_uninstall(args)
+    else:
+        # Start server
+        return start_server(args)
+
+
+def start_server(args: argparse.Namespace) -> int:
+    """Start the webhook server.
+
+    Args:
+        args: Parsed command-line arguments
+            - config: Configuration file path (from global -c argument)
+
+    Returns:
+        Exit code (0 = success, 1 = error)
+    """
+    # Get config path from args
+    config_file = getattr(args, 'config', None)
+
+    # Print version
+    print(f'gitwebhooks-cli {__version__}')
+
+    # Auto-discover config file if not specified
+    if config_file is None:
+        config_file = find_config_file()
+        if config_file is None:
+            # No config found - format error with all search paths
+            searched_paths = [Path(p).expanduser().resolve() for p in CONFIG_SEARCH_PATHS]
+            error_msg = format_config_error(searched_paths)
+            print(error_msg, file=sys.stderr)
+            return 1
+
+    # Expand user path
+    config_path = Path(config_file).expanduser()
+
+    # Check configuration file exists
+    if not config_path.exists():
+        print(f'Error: Configuration file not found: {config_path}', file=sys.stderr)
+        return 1
+
+    # Print configuration file being used
+    print(f'Using configuration file: {config_path}')
+    print('Starting server...')
+
+    # Create and run server
+    try:
+        server = WebhookServer(config_path=str(config_path))
+        server.run()
+        return 0
+    except ConfigurationError as e:
+        print(f'Configuration error: {e}', file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        print('\nServer stopped by user')
+        return 0
+    except Exception as e:
+        print(f'Error: {e}', file=sys.stderr)
+        return 1
+
+
+def find_config_file() -> Optional[str]:
+    """Find configuration file by priority order.
+
+    Searches for configuration files in the following order:
+    1. User level: ~/.gitwebhooks.ini
+    2. Local level: /usr/local/etc/gitwebhooks.ini
+    3. System level: /etc/gitwebhooks.ini
+
+    Returns:
+        Path string of the first existing configuration file, or None if not found.
+    """
+    for config_path in CONFIG_SEARCH_PATHS:
+        expanded_path = Path(config_path).expanduser().resolve()
+        if expanded_path.exists():
+            return str(expanded_path)
+    return None
+
+
+def format_config_error(searched_paths: list) -> str:
+    """Format user-friendly error message for missing configuration file.
+
+    Args:
+        searched_paths: List of paths that were searched.
+
+    Returns:
+        Formatted error message string.
+    """
+    lines = [
+        'Error: Configuration file not found.',
+        'Searched paths:'
+    ]
+    for i, path in enumerate(searched_paths, 1):
+        lines.append(f'  {i}. {path}')
+    lines.append('')
+    lines.append('You can create a configuration file using:')
+    lines.append('  gitwebhooks-cli config init')
+    return '\n'.join(lines)

gitwebhooks/cli/service.py

@@ -7,6 +7,7 @@ import argparse
 import subprocess
 import sys
 from pathlib import Path
+from typing import Optional
 
 from gitwebhooks.utils.systemd import (
     check_systemd,
@@ -16,7 +17,8 @@ from gitwebhooks.utils.systemd import (
     detect_installation_type,
     InstallationType,
 )
-from gitwebhooks.cli.prompts import ask_yes_no
+from gitwebhooks.utils.constants import ConfigLevel
+from gitwebhooks.cli.prompts import ask_yes_no, ask_config_level
 
 
 # Error codes
@@ -26,21 +28,39 @@ E_EXISTS = 1
 
 
 def cmd_install(args: argparse.Namespace) -> int:
-    """Install systemd service
+    """Install systemd service (deprecated, use 'serve install' instead)
 
     Args:
         args: Parsed command-line arguments
             - force: Force overwrite existing service
             - verbose: Verbosity level (0=normal, 1=verbose, 2=extra verbose)
             - dry_run: Preview mode without actual installation
+            - config: Path to configuration file (from global -c argument)
+            - config_level: Config level from --config-level argument
 
     Returns:
         Exit code (0 = success, 1 = error)
     """
+    # Show deprecation warning
+    print('Warning: "service install" is deprecated. Use "serve install" instead.', file=sys.stderr)
+    print()
     # Get verbose and dry_run from args
     verbose = getattr(args, 'verbose', 0)
     dry_run = getattr(args, 'dry_run', False)
 
+    # Get config path from global -c argument (backward compatibility)
+    config_path = getattr(args, 'config', None)
+    config_level = getattr(args, 'config_level', None)
+
+    # Check for conflicting options
+    if config_path and config_level:
+        print('Error: Conflicting options: --config-level and -c cannot be used together.', file=sys.stderr)
+        print()
+        print('Please use either:', file=sys.stderr)
+        print('  - gitwebhooks-cli service install --config-level <level>', file=sys.stderr)
+        print('  - gitwebhooks-cli service install -c <config-file>', file=sys.stderr)
+        return 1
+
     # For dry-run mode, skip root check
     if not dry_run:
         # Check root permission
@@ -76,16 +96,30 @@ def cmd_install(args: argparse.Namespace) -> int:
             print()
 
     # Perform installation
-    return install_service(force=args.force, verbose=verbose, dry_run=dry_run)
+    return install_service(
+        force=args.force,
+        verbose=verbose,
+        dry_run=dry_run,
+        config_level_override=config_level,
+        config_path_override=config_path
+    )
 
 
-def install_service(force: bool = False, verbose: int = 0, dry_run: bool = False) -> int:
+def install_service(
+    force: bool = False,
+    verbose: int = 0,
+    dry_run: bool = False,
+    config_level_override: Optional[str] = None,
+    config_path_override: Optional[str] = None
+) -> int:
     """Execute service installation logic
 
     Args:
         force: Force overwrite existing service
         verbose: Verbosity level (0=normal, 1=verbose, 2=extra verbose)
         dry_run: Preview mode without actual installation
+        config_level_override: Config level from command line argument (user/local/system)
+        config_path_override: Config path from -c argument (for backward compatibility)
 
     Returns:
         Exit code (0 = success, 1 = error)
@@ -124,13 +158,43 @@ def install_service(force: bool = False, verbose: int = 0, dry_run: bool = False
         print('Consider using pipx or venv for better isolation.', file=sys.stderr)
         print()
 
+    # Determine configuration level and path
+    config_level: ConfigLevel
+    config_path: str
+
+    if config_path_override:
+        # Backward compatibility: -c parameter takes precedence
+        config_path = config_path_override
+        # Map path to config level for display purposes
+        expanded_path = Path(config_path).expanduser()
+        if str(expanded_path) == str(Path('~/.gitwebhooks.ini').expanduser()):
+            config_level = ConfigLevel.USER
+        elif str(expanded_path) == '/usr/local/etc/gitwebhooks.ini':
+            config_level = ConfigLevel.LOCAL
+        elif str(expanded_path) == '/etc/gitwebhooks.ini':
+            config_level = ConfigLevel.SYSTEM
+        else:
+            # Custom path, default to USER for display
+            config_level = ConfigLevel.USER
+    elif config_level_override:
+        # Command-line --config-level parameter
+        try:
+            config_level = ConfigLevel.from_string(config_level_override)
+        except ValueError as e:
+            print(f'Error: {e}', file=sys.stderr)
+            return 1
+        config_path = str(config_level.get_config_path())
+    else:
+        # Interactive selection
+        config_level = ask_config_level()
+        config_path = str(config_level.get_config_path())
+
     # Get paths
     service_path = get_service_path()
-    config_path = '~/.gitwebhook.ini'
 
     # Generate service file based on installation type
     # For pipx: use cli_path directly
-    # For others: use python -m gitwebhooks.cli
+    # For others: use python -m gitwebhooks.main
     use_python_module = env.type != InstallationType.PIPX
 
     service_content = generate_service_file(
@@ -147,6 +211,9 @@ def install_service(force: bool = False, verbose: int = 0, dry_run: bool = False
         print(service_content)
         print('---')
         print()
+        if config_level_override or not config_path_override:
+            print(f'Configuration level: {config_level.value}')
+        print(f'Configuration path: {config_path}')
         print(f'Service file would be written to: {service_path}')
         print('Dry-run complete: No changes made.')
         return 0
@@ -174,6 +241,10 @@ def install_service(force: bool = False, verbose: int = 0, dry_run: bool = False
         print(f'Warning: systemctl daemon-reload failed: {e}', file=sys.stderr)
         # Continue anyway
 
+    # Display configuration file information
+    print()
+    print(f'Using configuration file: {config_path}')
+
     # Enable and start service
     return enable_and_start_service()
 
@@ -240,7 +311,7 @@ def enable_and_start_service() -> int:
 
 
 def cmd_uninstall(args: argparse.Namespace) -> int:
-    """Uninstall systemd service
+    """Uninstall systemd service (deprecated, use 'serve uninstall' instead)
 
     Args:
         args: Parsed command-line arguments
@@ -249,6 +320,9 @@ def cmd_uninstall(args: argparse.Namespace) -> int:
     Returns:
         Exit code (0 = success, 1 = error)
     """
+    # Show deprecation warning
+    print('Warning: "service uninstall" is deprecated. Use "serve uninstall" instead.', file=sys.stderr)
+    print()
     # Check root permission
     if not check_root_permission():
         print('Error: This operation requires root privileges', file=sys.stderr)

gitwebhooks/main/__init__.py

@@ -19,6 +19,57 @@ try:
 except ImportError:
     HAS_SUBCOMMANDS = False
 
+# Global parser reference for help command
+_parser = None
+
+
+def get_parser() -> argparse.ArgumentParser:
+    """Get the main argument parser instance.
+
+    Returns:
+        The main ArgumentParser instance
+
+    Examples:
+        >>> parser = get_parser()
+        >>> isinstance(parser, argparse.ArgumentParser)
+        True
+    """
+    global _parser
+    if _parser is None:
+        _parser = create_parser()
+    return _parser
+
+
+def create_parser() -> argparse.ArgumentParser:
+    """Create and configure the main argument parser.
+
+    Returns:
+        Configured ArgumentParser instance
+
+    Examples:
+        >>> parser = create_parser()
+        >>> isinstance(parser, argparse.ArgumentParser)
+        True
+    """
+    # Create main argument parser (help disabled)
+    parser = argparse.ArgumentParser(
+        prog='gitwebhooks-cli',
+        description='Git Webhooks Server - Automated deployment webhook handler',
+        add_help=False
+    )
+    parser.add_argument(
+        '-c', '--config',
+        default=None,
+        help='Path to INI configuration file (default: auto-discover)'
+    )
+
+    # Add subcommands if available
+    if HAS_SUBCOMMANDS:
+        subparsers = parser.add_subparsers(dest='command', help='Subcommands')
+        register_subparsers(subparsers)
+
+    return parser
+
 
 def find_config_file() -> Optional[str]:
     """Find configuration file by priority order.
@@ -83,10 +134,11 @@ def main(argv: List[str] = None) -> int:
         SystemExit: Exit on error
 
     Command Line Arguments:
-        -h, --help      Show help message and exit
-        -c, --config    Specify configuration file path (optional)
-        service         Service management subcommands
-        config          Configuration management subcommands
+        -v, --version   Show version information and exit
+        -c, --config     Specify configuration file path (optional)
+        serve            Start webhook server or manage systemd service
+        config           Configuration management subcommands
+        help             Show help information
 
     Config Discovery:
         When -c is not specified, searches in order:
@@ -95,38 +147,58 @@ def main(argv: List[str] = None) -> int:
         3. /etc/gitwebhooks.ini (system level)
 
     Examples:
-        python3 -m gitwebhooks.main
-        python3 -m gitwebhooks.main -c /path/to/config.ini
-        gitwebhooks-cli --config /etc/webhooks.ini
-        gitwebhooks-cli service install
+        python3 -m gitwebhooks.main -v
+        python3 -m gitwebhooks.main serve
+        python3 -m gitwebhooks.main serve -c /path/to/config.ini
+        gitwebhooks-cli serve install
         gitwebhooks-cli config init
+        gitwebhooks-cli help
     """
     if argv is None:
         argv = sys.argv[1:]
 
-    # Create main argument parser
-    parser = argparse.ArgumentParser(
-        prog='gitwebhooks-cli',
-        description='Git Webhooks Server - Automated deployment webhook handler',
-        add_help=True
-    )
-    parser.add_argument(
-        '-c', '--config',
-        default=None,
-        help='Path to INI configuration file (default: auto-discover)'
-    )
+    # Pre-check for -v/--version parameters (takes priority over everything)
+    if '-v' in argv or '--version' in argv:
+        from gitwebhooks.main.version import print_version
+        print_version()
+        return 0
 
-    # Add subcommands if available
-    if HAS_SUBCOMMANDS:
-        subparsers = parser.add_subparsers(dest='command', help='Subcommands')
-        register_subparsers(subparsers)
+    # Check for -h/--help parameters and show error
+    if '-h' in argv or '--help' in argv:
+        print('Error: -h/--help parameters are not supported.', file=sys.stderr)
+        print('Use \'gitwebhooks-cli help\' or \'gitwebhooks-cli help <subcommand>\' instead.', file=sys.stderr)
+        return 1
+
+    # Create parser and parse arguments
+    parser = create_parser()
+
+    # Check if user provided a command (first argument without leading dash)
+    command = None
+    for i, arg in enumerate(argv):
+        if not arg.startswith('-'):
+            command = arg
+            break
 
-    # Parse arguments
-    args = parser.parse_args(argv)
+    # Try to parse arguments
+    try:
+        args = parser.parse_args(argv)
+    except SystemExit as e:
+        # argparse will call sys.exit on error, catch it to provide better error
+        if e.code != 0:
+            # Parsing failed, check if it's an unknown command
+            if command and command not in ['serve', 'config', 'help', 'service']:
+                print(f"Error: Unknown command '{command}'", file=sys.stderr)
+                print("Available commands: serve, config, help", file=sys.stderr)
+                print()
+                print("Use 'gitwebhooks-cli help' to see usage information", file=sys.stderr)
+            return 1
+        raise
 
-    # If no subcommand, run server (backward compatible behavior)
-    if not hasattr(args, 'func'):
-        return run_server(args.config)
+    # If no subcommand specified, show help (new default behavior)
+    if not hasattr(args, 'func') or args.func is None:
+        from gitwebhooks.cli.help import show_main_help
+        show_main_help(parser)
+        return 0
 
     # Execute subcommand
     return args.func(args)

gitwebhooks/main/version.py

@@ -0,0 +1,24 @@
+"""Version display module
+
+Provides version information display functionality for gitwebhooks-cli.
+"""
+
+import sys
+
+
+def print_version() -> None:
+    """Print version information and exit.
+
+    Displays version in the format: gitwebhooks-cli x.x.x
+
+    Returns:
+        None
+
+    Examples:
+        >>> print_version()  # doctest: +SKIP
+        gitwebhooks-cli 2.2.0
+    """
+    # Import __version__ from package
+    from gitwebhooks import __version__
+
+    print(f'gitwebhooks-cli {__version__}')

gitwebhooks/models/__init__.py

@@ -6,9 +6,11 @@ Defines core data types and enumerations.
 from .provider import Provider
 from .request import WebhookRequest
 from .result import SignatureVerificationResult
+from .config import ServiceInstallContext
 
 __all__ = [
     'Provider',
     'WebhookRequest',
     'SignatureVerificationResult',
+    'ServiceInstallContext',
 ]

gitwebhooks/models/config.py

@@ -0,0 +1,74 @@
+"""Configuration-related data models
+
+Provides data classes for configuration and service installation contexts.
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+from gitwebhooks.utils.constants import ConfigLevel
+from gitwebhooks.utils.systemd import InstallationType
+
+
+@dataclass
+class ServiceInstallContext:
+    """Service installation context
+
+    Contains all information needed for service installation,
+    including configuration level, paths, and installation type.
+
+    Attributes:
+        config_level: Configuration file level (user/local/system)
+        config_path: Full path to configuration file
+        install_type: Installation type (pipx/venv/virtualenv/system)
+        use_python_module: Whether to use 'python -m' format
+        cli_path: Path to gitwebhooks-cli executable
+        python_path: Python interpreter path (required when use_python_module=True)
+    """
+
+    config_level: ConfigLevel
+    config_path: Path
+    install_type: InstallationType
+    use_python_module: bool
+    cli_path: str
+    python_path: Optional[str] = None
+
+    def __post_init__(self):
+        """Validate the service installation context
+
+        Raises:
+            ValueError: If validation fails
+        """
+        # Ensure config_path is a Path object
+        if isinstance(self.config_path, str):
+            self.config_path = Path(self.config_path)
+
+        # Validate use_python_module requires python_path
+        if self.use_python_module and not self.python_path:
+            raise ValueError(
+                "python_path is required when use_python_module is True"
+            )
+
+        # Validate config_path is not empty
+        if not self.config_path or str(self.config_path) == '.':
+            raise ValueError("config_path cannot be empty")
+
+    def get_exec_start_command(self) -> str:
+        """Generate the ExecStart command for systemd service file
+
+        Returns:
+            Complete ExecStart command string
+        """
+        if self.use_python_module and self.python_path:
+            return f"{self.python_path} -m gitwebhooks.main -c {self.config_path}"
+        else:
+            return f"{self.cli_path} -c {self.config_path}"
+
+    def get_config_path_str(self) -> str:
+        """Get configuration file path as string
+
+        Returns:
+            Configuration file path as string
+        """
+        return str(self.config_path)

gitwebhooks/utils/constants.py

@@ -3,6 +3,9 @@
 Defines all constants used in the project.
 """
 
+from enum import Enum
+from pathlib import Path
+
 # HTTP Status Codes
 HTTP_OK = 200
 HTTP_BAD_REQUEST = 400
@@ -53,3 +56,49 @@ SENSITIVE_KEYWORDS = {"secret", "password", "token", "key", "passphrase"}
 # ANSI color codes for sensitive field highlighting
 COLOR_SENSITIVE = "\033[33m"  # Yellow
 COLOR_RESET = "\033[0m"
+
+
+class ConfigLevel(Enum):
+    """Configuration file level for service installation
+
+    Represents the three configuration file levels supported by gitwebhooks,
+    ordered by priority (highest to lowest).
+    """
+
+    USER = "user"          # ~/.gitwebhooks.ini (highest priority)
+    LOCAL = "local"        # /usr/local/etc/gitwebhooks.ini
+    SYSTEM = "system"      # /etc/gitwebhooks.ini (lowest priority)
+
+    def get_config_path(self) -> Path:
+        """Get the configuration file path for this level
+
+        Returns:
+            Path object pointing to the configuration file
+        """
+        paths = {
+            ConfigLevel.USER: Path(CONFIG_PATH_USER).expanduser(),
+            ConfigLevel.LOCAL: Path(CONFIG_PATH_LOCAL),
+            ConfigLevel.SYSTEM: Path(CONFIG_PATH_SYSTEM),
+        }
+        return paths[self]
+
+    @classmethod
+    def from_string(cls, value: str) -> 'ConfigLevel':
+        """Create ConfigLevel from string value
+
+        Args:
+            value: String value ('user', 'local', or 'system')
+
+        Returns:
+            ConfigLevel enum value
+
+        Raises:
+            ValueError: If value is not a valid config level
+        """
+        try:
+            return cls(value.lower())
+        except ValueError:
+            valid_values = ', '.join([e.value for e in cls])
+            raise ValueError(
+                f"Invalid config level '{value}'. Valid values are: {valid_values}"
+            )

gitwebhooks/utils/systemd.py

@@ -223,15 +223,15 @@ def generate_service_file(
         cli_path: Path to gitwebhooks-cli executable
         config_path: Path to configuration file
         python_path: Python interpreter path (if using python -m mode)
-        use_python_module: If True, use 'python -m gitwebhooks.cli' format
+        use_python_module: If True, use 'python -m gitwebhooks.main' format
 
     Returns:
         Service file content as string
     """
     if use_python_module and python_path:
-        exec_start = f"{python_path} -m gitwebhooks.cli -c {config_path}"
+        exec_start = f"{python_path} -m gitwebhooks.main serve -c {config_path}"
     else:
-        exec_start = f"{cli_path} -c {config_path}"
+        exec_start = f"{cli_path} serve -c {config_path}"
 
     return SERVICE_TEMPLATE.format(
         exec_start=exec_start

{gitwebhooks-2.2.0.dist-info → gitwebhooks-2.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitwebhooks
-Version: 2.2.0
+Version: 2.3.0
 Summary: A lightweight Git webhook server for automated deployment supporting GitHub, Gitee, GitLab, and custom webhooks
 Author-email: Troy Tse <troy@holyhi.net>
 Maintainer-email: Troy Tse <troy@holyhi.net>
@@ -169,28 +169,40 @@ This will create a configuration file with secure permissions (0600).
 The service installation command automatically detects your installation type (pipx, venv, or system) and generates the appropriate service file.
 
 ```bash
-# Install and start as a systemd service
-sudo gitwebhooks-cli service install
+# Install and start as a systemd service (interactive config level selection)
+sudo gitwebhooks-cli serve install
+
+# Install with specific config level (skip interactive selection)
+sudo gitwebhooks-cli serve install --config-level user    # User level (~/.gitwebhooks.ini)
+sudo gitwebhooks-cli serve install --config-level local   # Local level (/usr/local/etc/gitwebhooks.ini)
+sudo gitwebhooks-cli serve install --config-level system   # System level (/etc/gitwebhooks.ini)
+
+# Use custom config file (backward compatibility)
+sudo gitwebhooks-cli serve install -c /path/to/config.ini
 
 # Preview service file without installing (dry-run mode)
-sudo gitwebhooks-cli service install --dry-run
+sudo gitwebhooks-cli serve install --dry-run
+sudo gitwebhooks-cli serve install --config-level local --dry-run  # Preview specific level
 
 # Install with verbose output
-sudo gitwebhooks-cli service install --verbose
-sudo gitwebhooks-cli service install -v      # Basic verbosity
-sudo gitwebhooks-cli service install -vv     # Extra verbosity
+sudo gitwebhooks-cli serve install --verbose
 
 # Force overwrite existing service
-sudo gitwebhooks-cli service install --force
+sudo gitwebhooks-cli serve install --force
 
 # Uninstall the service
-sudo gitwebhooks-cli service uninstall
+sudo gitwebhooks-cli serve uninstall
 ```
 
+**Configuration levels**:
+- **user**: `~/.gitwebhooks.ini` - Single user configuration, highest priority
+- **local**: `/usr/local/etc/gitwebhooks.ini` - Local system configuration, medium priority
+- **system**: `/etc/gitwebhooks.ini` - Global system configuration, lowest priority
+
 **Service file auto-detection**:
 - **pipx installation**: Uses `gitwebhooks-cli` command directly
-- **venv/virtualenv**: Uses `python -m gitwebhooks.cli` with environment's Python
-- **System pip**: Uses system Python with `python -m gitwebhooks.cli`
+- **venv/virtualenv**: Uses `python -m gitwebhooks.main` with environment's Python
+- **System pip**: Uses system Python with `python -m gitwebhooks.main`
 - **conda**: Not supported - installation will be refused with clear error message
 
 ### Manual Installation
@@ -208,7 +220,14 @@ sudo ln "$(pwd)/gitwebhooks-cli" /usr/local/bin/gitwebhooks-cli
 ### Verify Installation
 
 ```bash
-gitwebhooks-cli --help
+# Show version
+gitwebhooks-cli -v
+
+# Show help
+gitwebhooks-cli help
+
+# View configuration
+gitwebhooks-cli config view
 ```
 
 ## Migrating from System pip Installation

{gitwebhooks-2.2.0.dist-info → gitwebhooks-2.3.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-gitwebhooks/__init__.py,sha256=KUi3jpqSom1NA9r8du8t2kG1mZ0NN8Jtdbl9wlxr5bg,422
+gitwebhooks/__init__.py,sha256=mwkwwmLU4XQc5li5wJQkU4XRdOwlNvqcgi3dmdWwxuo,422
 gitwebhooks/__main__.py,sha256=DW1lmngPDSFHJKSyaG2Dd5k3UguGSuYPUM2xKR8DhTo,189
 gitwebhooks/server.py,sha256=keQcfOysoitx7cINcTkaDvhe6nScIFL2K8dCCViFF-o,3986
 gitwebhooks/auth/__init__.py,sha256=Hu88BS6aOickrWBBWM2ppTzy2xOJfWODYkp752bPTPM,532
@@ -8,11 +8,13 @@ gitwebhooks/auth/gitee.py,sha256=8o_tKugZrW2or-uoRzjCo3h-WRlm3zbYmkTNbf5zL6s,324
 gitwebhooks/auth/github.py,sha256=sY3xPwfYvD3tID5b26qHhTI1E9EW2VNHaFEygmsZYCg,1619
 gitwebhooks/auth/gitlab.py,sha256=Aoz77VbYRASxNXqOAnK5__9hkGgaf9kLMoCgOnvFMNE,862
 gitwebhooks/auth/verifier.py,sha256=onIvbmFVWpk7vkdEiyF48S4KrtbP48NH3FLz0fE24XE,971
-gitwebhooks/cli/__init__.py,sha256=o81CV1rggR_YqSW80JP_CSKMGBQkQYJqDjsiUtvvW-I,2891
+gitwebhooks/cli/__init__.py,sha256=A8GyUtejo5qtzD9K_0mvuWGcs1WWYmeSQrJwoLz4b70,5657
 gitwebhooks/cli/config.py,sha256=rVq7qh2KB9Z4Up2bc9zWDvGpf28iALdnu1pGIJ0p6-8,6373
+gitwebhooks/cli/help.py,sha256=zjWrpKfs4GdvoxR9awy4Hc-pc6Lgyb-RFMV-bO1_TG8,4284
 gitwebhooks/cli/init_wizard.py,sha256=7nJHFrXsqC5FS79CE3xyftP9_KW9Q5FO2Duuj8nuO4M,23926
-gitwebhooks/cli/prompts.py,sha256=slbAcjEUY83lanuXbfyt7BP4m1ZrgQEcgkjI96hsw60,7167
-gitwebhooks/cli/service.py,sha256=6w8jlOOkHAURWKTbqPqW83lC8qbgDuxM_0W0IXhLo24,11001
+gitwebhooks/cli/prompts.py,sha256=8XDUyplQqvcqDEARI3XI5qGh5PpJLYwHGCNuqERn4UI,8655
+gitwebhooks/cli/serve.py,sha256=MP58IuuZpva0soMR34zxv-856XsMBkHJnF-VLETSK6w,4665
+gitwebhooks/cli/service.py,sha256=cpMOTwjU58Nurjo5zBpsMJTNLo7GHixHe4CSPpmifdc,14175
 gitwebhooks/config/__init__.py,sha256=CnU2ybNi8Yf5YqGWe7uls98ditREEuxuj5mW0t1ti0s,413
 gitwebhooks/config/loader.py,sha256=fbuIPeDFx5f6-HjPuo35U5CMYxeH1ZWPD18vZJRpSiE,5774
 gitwebhooks/config/models.py,sha256=oZ0ISLxh0zq5U7fqpAk2as7qHsOcbwj257BZEaK1zO8,4758
@@ -28,20 +30,22 @@ gitwebhooks/handlers/gitlab.py,sha256=UkK3R_KSKSt0s7XAtH1_G_uid85tqiL12qND8_Pnos
 gitwebhooks/handlers/request.py,sha256=GsKH-R7L7j7h9GKEAse-O4tnmXeQMkbsT8WK_J8ACl8,9184
 gitwebhooks/logging/__init__.py,sha256=CmL5WD2RgZ76uhrxzwnIfOEd_HgTZMTtTjjqYSY06GA,146
 gitwebhooks/logging/setup.py,sha256=scu4nfEJTLR6QpmO4exXbKaMcTU11qHR2Jv8fEpEMD8,2095
-gitwebhooks/main/__init__.py,sha256=kg7QtoWHljnEkysei5XoIwXMjveNHf_bdPwfei5Vypw,5559
+gitwebhooks/main/__init__.py,sha256=WV4io9b8qJ4_v6GExq_w-fF0v0eoEeL8fCpdT-aYAgk,7920
 gitwebhooks/main/__main__.py,sha256=qE-72BSpj15NeV6-oWpMXR3ARmATeSGUO8VUB98sxF8,223
-gitwebhooks/models/__init__.py,sha256=DmZBPoNeh7eB9Ntr6d4T9QY6-LckvrHNGg8FVcpuvP0,273
+gitwebhooks/main/version.py,sha256=u0iDPU2FE132Bq2s-fManXjDcoBxJ0jnRP77flN5Mug,497
+gitwebhooks/models/__init__.py,sha256=3uS3rYD5EG2F8Vc-pJ02ufmMreL6sIcJ_fTjRh7V398,344
+gitwebhooks/models/config.py,sha256=7T8vE-eNMRcd4dNPDwNNmB0NkTlh_Rk00XcgMIAy7bo,2419
 gitwebhooks/models/provider.py,sha256=lmjJvGjklD1VTKB6UF9V-gZCPwXhiip8DR8qXs_A-F8,451
 gitwebhooks/models/request.py,sha256=UkdTiBpX4-XipeOnhE0SvAaR53bFFh8EKftSVFjNBLM,1838
 gitwebhooks/models/result.py,sha256=0M3fjeUH3CM4Mjpc9e4ZxBdfPO9xlODRRdlshVomQYQ,1020
 gitwebhooks/utils/__init__.py,sha256=qZcrINToHF8qAtIIDAjOlzfKcohCVyYe2ZaKYsWbOxY,219
-gitwebhooks/utils/constants.py,sha256=V_SFYrHpkX-fKSfVwx8fXwBjZe2f4EjoVz925RZryrs,1729
+gitwebhooks/utils/constants.py,sha256=PGmwV9lkH8VP8XblEopdm2lr71ZaNISXzuWcU0KfcAU,3220
 gitwebhooks/utils/exceptions.py,sha256=Mfz-FOCiHZiYmpSQDw36S9HarLE2wPLfFbkeHfWJnkk,627
 gitwebhooks/utils/executor.py,sha256=-zQUV5t-eq0JF6T4EvsUlvg4lnBtahRGrV8N3iVgx_c,923
-gitwebhooks/utils/systemd.py,sha256=00k55_vcstkTmJi99RrSfx-RIuI1dwTlggCPRPfbhNU,7901
-gitwebhooks-2.2.0.dist-info/licenses/LICENSE,sha256=NV5F0xpN-DVJuhc0qzOsXtLjf3l8X18zehW_7F4qI50,1083
-gitwebhooks-2.2.0.dist-info/METADATA,sha256=gPht52jk7aXxx3AhQEZCHNpij_IrFY97UUYHEIvOyLM,14346
-gitwebhooks-2.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-gitwebhooks-2.2.0.dist-info/entry_points.txt,sha256=kcbGwiZPNGnfEYlsrOaNQinGC1rTkiaDOF2NJ6S_5MU,58
-gitwebhooks-2.2.0.dist-info/top_level.txt,sha256=9a6CxnHxBD53HL38GUeZETIvnUhUKcgDRIGJkCqwc3o,12
-gitwebhooks-2.2.0.dist-info/RECORD,,
+gitwebhooks/utils/systemd.py,sha256=1g2-oByu-XTgZZI_FzsyLl7A1b-NKcwWqtzapvoVGUs,7915
+gitwebhooks-2.3.0.dist-info/licenses/LICENSE,sha256=NV5F0xpN-DVJuhc0qzOsXtLjf3l8X18zehW_7F4qI50,1083
+gitwebhooks-2.3.0.dist-info/METADATA,sha256=v521rAHS_nift5U89wwgElSumqjxcjAHnMV50_N6E58,15188
+gitwebhooks-2.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+gitwebhooks-2.3.0.dist-info/entry_points.txt,sha256=kcbGwiZPNGnfEYlsrOaNQinGC1rTkiaDOF2NJ6S_5MU,58
+gitwebhooks-2.3.0.dist-info/top_level.txt,sha256=9a6CxnHxBD53HL38GUeZETIvnUhUKcgDRIGJkCqwc3o,12
+gitwebhooks-2.3.0.dist-info/RECORD,,