gmuse.cli.main

CLI interface for gmuse.

This module provides the command-line interface using Typer. It handles:

• Argument parsing and validation

• Configuration loading and merging

• Error handling and user feedback

• Clipboard operations

Commands:

msg: Generate a commit message from staged changes. info: Display resolved configuration for debugging. git-completions: Shell completion utilities. git-completions-run: Runtime helper for shell completions.

Example:

>>> # From command line:
>>> # gmuse msg --hint "security fix" --copy

Module Contents

Functions

version_callback	Show version and exit.
main	gmuse: AI generated commit messages.
info	Print resolved LLM configuration and environment values for debugging.
msg	Generate a commit message from staged changes.
_load_config	Load and merge configuration from all sources.
_copy_to_clipboard	Copy message to clipboard with user feedback.
_error_exit	Display error message and exit with specified code.
_format_dry_run_output	Format the dry-run output for CLI display.

Data

logger
app

API

gmuse.cli.main.logger = 'get_logger(...)'

gmuse.cli.main.app = 'Typer(...)'

gmuse.cli.main.version_callback(value: bool) → None

Show version and exit.

Args:

value: True if –version flag was passed.

Raises:

typer.Exit: Always exits after printing version.

gmuse.cli.main.main(version: bool = typer.Option(None, '--version', help='Show the version and exit.', is_eager=True, callback=version_callback)) → None

gmuse: AI generated commit messages.

Generate commit messages from staged changes using AI.

Use ‘gmuse msg’ to create a commit message from your staged changes.

Examples:

gmuse msg # Generate message gmuse msg –hint “breaking change” # With hint gmuse msg –format conventional # Conventional commits gmuse msg –copy # Copy to clipboard gmuse info # Show configuration

For more information, visit: https://gmuse.readthedocs.io

gmuse.cli.main.info() → None

Print resolved LLM configuration and environment values for debugging.

Useful for diagnosing provider selection and which credentials are being used.

gmuse.cli.main.msg(hint: Optional[str] = typer.Option(None, '--hint', help="Additional guidance for message generation (e.g., 'emphasize security')"), copy: bool = typer.Option(False, '--copy', '-c', help='Copy generated message to clipboard'), model: Optional[str] = typer.Option(None, '--model', '-m', help="LLM model to use (e.g., 'gpt-4', 'claude-3-opus')"), format: Optional[str] = typer.Option(None, '--format', '-f', help="Message format: 'freeform' (default), 'conventional', or 'gitmoji'"), history_depth: Optional[int] = typer.Option(None, '--history-depth', help='Number of recent commits to use for style context (0-50)'), temperature: Optional[float] = typer.Option(None, '--temperature', help='LLM sampling temperature (0.0-2.0, default: 0.7)'), max_tokens: Optional[int] = typer.Option(None, '--max-tokens', help='Maximum tokens in LLM response (default: 500)'), max_diff_bytes: Optional[int] = typer.Option(None, '--max-diff-bytes', help='Maximum diff size in bytes before truncation (default: 20000)'), include_branch: bool = typer.Option(False, '--include-branch', help='Include current branch name as context for commit message generation'), dry_run: bool = typer.Option(False, '--dry-run', help='Print the assembled prompt without calling the LLM provider')) → None

Generate a commit message from staged changes.

This command analyzes your staged git changes and generates an appropriate commit message using AI. The message is printed to stdout and can optionally be copied to your clipboard.

Examples:

gmuse msg # Basic usage gmuse msg –hint “security fix” # Add context hint gmuse msg –format conventional # Use conventional commits format gmuse msg –copy # Auto-copy to clipboard gmuse msg –model claude-3-opus # Use specific model gmuse msg –temperature 0.3 # Lower temperature for more deterministic output gmuse msg –max-tokens 200 # Limit response length gmuse msg –include-branch # Include branch context gmuse msg –dry-run # Preview prompt without calling LLM

gmuse.cli.main._load_config(model: Optional[str] = None, copy: bool = False, format: Optional[str] = None, history_depth: Optional[int] = None, temperature: Optional[float] = None, max_tokens: Optional[int] = None, max_diff_bytes: Optional[int] = None, include_branch: bool = False) → gmuse.config.ConfigDict

Load and merge configuration from all sources.

Configuration is loaded from multiple sources with the following precedence (highest to lowest):

1. CLI arguments (passed to this function)

2. Environment variables (GMUSE_*)

3. Configuration file (.gmuse.toml or pyproject.toml)

4. Built-in defaults

Args:

model: CLI model override. copy: CLI copy to clipboard flag. format: CLI format override. history_depth: CLI history depth override. temperature: CLI temperature override. max_tokens: CLI max_tokens override. max_diff_bytes: CLI max_diff_bytes override. include_branch: CLI include branch flag.

Returns:

Merged and validated configuration dictionary.

Raises:

ConfigError: If the merged configuration is invalid.

gmuse.cli.main._copy_to_clipboard(message: str) → None

Copy message to clipboard with user feedback.

Attempts to copy using pyperclip. Displays success message or warning if pyperclip is not installed or clipboard operation fails.

Args:

message: The text to copy to clipboard.

gmuse.cli.main._error_exit(message: str, code: int = 1, hint: Optional[str] = None) → None

Display error message and exit with specified code.

Args:

message: The error message to display. code: Exit code (default: 1). hint: Optional helpful hint to display after the error.

Raises:

typer.Exit: Always raises to exit the application.

gmuse.cli.main._format_dry_run_output(model: Optional[str], format: str, truncated: bool, system_prompt: str, user_prompt: str) → str

Format the dry-run output for CLI display.

Produces a plain-text block containing a metadata header and labeled SYSTEM PROMPT / USER PROMPT sections so the user can inspect what would be sent to the LLM provider.

Args:

model: Resolved model name (or None if not configured). format: Message format (freeform, conventional, gitmoji). truncated: Whether the staged diff was truncated. system_prompt: The system prompt that would be sent. user_prompt: The user prompt that would be sent.

Returns:

Formatted string suitable for printing to stdout.

Example:

>>> output = _format_dry_run_output(
...     model="gpt-4",
...     format="conventional",
...     truncated=False,
...     system_prompt="You are a commit helper.",
...     user_prompt="Diff: ...",
... )
>>> print(output)
MODEL: gpt-4
FORMAT: conventional
TRUNCATED: false

SYSTEM PROMPT:
You are a commit helper.

USER PROMPT:
Diff: ...