mygh 0.1.4

A comprehensive GitHub CLI tool built with Python and Typer

MyGH - A Comprehensive GitHub CLI Tool

MyGH is a modern, feature-rich command-line interface for GitHub that provides comprehensive user insights and repository management capabilities. Built with Python, Typer, and the GitHub REST API, it offers a beautiful and intuitive developer experience.

✨ Features

🔍 User Information

• User Profiles: Get detailed information about any GitHub user
• Starred Repositories: List and filter starred repositories by language with commit age tracking
• Gists Management: Browse and manage user gists

📦 Repository Management

• Repository Listing: List repositories with flexible filtering and sorting
• Repository Details: Get comprehensive information about specific repositories
• Issue Tracking: Browse repository issues with advanced filtering
• Repository Creation: Create new repositories with full configuration options
• Repository Updates: Modify repository settings, visibility, and features
• Repository Deletion: Safely delete repositories with confirmation prompts
• Repository Forking: Fork repositories to your account or organizations

🔄 Pull Request Management

• PR Listing: List and filter pull requests by state, branch, and author
• PR Creation: Create pull requests with interactive prompts and draft support
• PR Updates: Modify titles, descriptions, and other PR attributes
• PR Merging: Merge pull requests with different strategies (merge, squash, rebase)
• PR Details: View comprehensive PR information with diffs and statistics

🚀 GitHub Actions Integration

• Workflow Listing: Browse repository workflows and their configurations
• Workflow Runs: Monitor workflow runs with status and conclusion filtering
• Real-time Status: Track CI/CD pipeline execution and results

🏢 Organization Management

• Organization Listing: View your organization memberships
• Member Management: List organization members with role filtering
• Team Overview: Browse organization teams and their descriptions

🔍 Advanced Search

• Repository Search: Find repositories using GitHub's powerful search syntax
• User Search: Discover users with advanced filtering and sorting
• Search Operators: Support for all GitHub search qualifiers and operators

🔔 Notification Management

• Notification Listing: View unread and participating notifications
• Bulk Operations: Mark notifications as read globally or per repository
• Filtering Options: Focus on relevant notifications with various filters

👥 Team Management

• Team Listing: Browse organization teams with member counts
• Member Details: View team membership and roles
• Team Privacy: Support for public and private team visibility

🖥️ Interactive Browser

• Repository Browser: Navigate repositories with keyboard shortcuts
• Real-time Filtering: Search and filter repositories interactively
• Detailed Views: Inspect repository details without leaving the terminal

🎨 Output Formats

• Rich Tables: Beautiful, colorized terminal output with commit age indicators (default)
• JSON Export: Machine-readable format for automation
• CSV Export: Data analysis-friendly format for repositories

⚙️ Configuration

• Flexible Authentication: Multiple authentication methods
• Persistent Settings: Save preferences with TOML configuration
• Environment Variables: Override settings with environment variables

🚀 Quick Start

Prerequisites

• Python 3.10 or higher
• uv package manager
• GitHub account and access token

Installation

1. Clone the repository:

   git clone https://github.com/ryancheley/MyGH.git
   cd MyGH
   

2. Install dependencies with uv:

   uv sync --dev
   

3. Set up GitHub authentication:

   Option A: Environment Variable

   export GITHUB_TOKEN="your_personal_access_token"
   

   Option B: GitHub CLI Integration

   gh auth login
   

4. Test the installation:

   uv run mygh --help
   

Creating a GitHub Personal Access Token

1. Go to GitHub → Settings → Developer settings → Personal access tokens
2. Click "Generate new token (classic)"
3. Select scopes: repo, user, gist
4. Copy the generated token
5. Set it as the GITHUB_TOKEN environment variable

📖 Usage Guide

User Commands

Get User Information

# Get your own user information
uv run mygh user info

# Get information about a specific user
uv run mygh user info octocat

# Export as JSON
uv run mygh user info --format json --output user.json

List Starred Repositories

# List your starred repositories
uv run mygh user starred

# Filter by programming language
uv run mygh user starred --language python

# Limit results and export as CSV
uv run mygh user starred --limit 50 --format csv --output starred.csv

# List another user's starred repositories
uv run mygh user starred octocat --language javascript

Browse User Gists

# List your gists
uv run mygh user gists

# Show only public gists
uv run mygh user gists --public

# List another user's gists
uv run mygh user gists octocat --format json

Repository Commands

List Repositories

# List your repositories
uv run mygh repos list

# Filter by type and sort
uv run mygh repos list --type public --sort updated

# List another user's repositories
uv run mygh repos list octocat --limit 20

# Export as CSV
uv run mygh repos list --format csv --output repos.csv

Get Repository Information

# Get detailed repository information
uv run mygh repos info octocat/Hello-World

# Export repository details as JSON
uv run mygh repos info microsoft/vscode --format json

Browse Repository Issues

# List open issues
uv run mygh repos issues octocat/Hello-World

# Filter by state and assignee
uv run mygh repos issues microsoft/vscode --state closed --assignee @me

# Filter by labels
uv run mygh repos issues facebook/react --labels "bug,help wanted"

# Export issues as JSON
uv run mygh repos issues vuejs/vue --format json --output issues.json

Repository Management (Extended)

Create Repositories

# Create a new repository
uv run mygh repos create my-new-repo --description "My awesome project"

# Create with interactive prompts
uv run mygh repos create my-repo --interactive

# Create private repository with custom settings
uv run mygh repos create my-private-repo --private --no-wiki --no-projects

Update Repository Settings

# Update repository description
uv run mygh repos update myuser/my-repo --description "Updated description"

# Change repository visibility
uv run mygh repos update myuser/my-repo --private

# Enable/disable features
uv run mygh repos update myuser/my-repo --issues --no-wiki

Delete and Fork Repositories

# Delete a repository (with confirmation)
uv run mygh repos delete myuser/old-repo

# Fork a repository
uv run mygh repos fork microsoft/vscode

# Fork to an organization
uv run mygh repos fork microsoft/vscode --org myorg

Pull Request Management

List Pull Requests

# List open pull requests
uv run mygh pulls list microsoft/vscode

# Filter by state and branch
uv run mygh pulls list microsoft/vscode --state closed --base main

# Sort by creation date
uv run mygh pulls list microsoft/vscode --sort created --direction asc

Create Pull Requests

# Create a new pull request
uv run mygh pulls create myuser/my-repo --title "Add new feature" --head feature-branch --base main

# Create with interactive prompts
uv run mygh pulls create myuser/my-repo --interactive

# Create as draft
uv run mygh pulls create myuser/my-repo --title "WIP: New feature" --head feature --draft

Manage Pull Requests

# Show pull request details
uv run mygh pulls show microsoft/vscode 123

# Show with diff
uv run mygh pulls show microsoft/vscode 123 --diff

# Update pull request
uv run mygh pulls update microsoft/vscode 123 --title "Updated title" --body "New description"

# Merge pull request
uv run mygh pulls merge microsoft/vscode 123 --method squash --delete-branch

# Close without merging
uv run mygh pulls close microsoft/vscode 123

GitHub Actions Integration

List Workflows

# List repository workflows
uv run mygh actions workflows microsoft/vscode

# Export as JSON
uv run mygh actions workflows microsoft/vscode --format json

Monitor Workflow Runs

# List recent workflow runs
uv run mygh actions runs microsoft/vscode

# Filter by workflow and status
uv run mygh actions runs microsoft/vscode --workflow ci.yml --status failure

# Limit results
uv run mygh actions runs microsoft/vscode --limit 10

Organization Management

List Organizations

# List your organizations
uv run mygh orgs list

Manage Organization Members

# List organization members
uv run mygh orgs members myorg

# Filter by role
uv run mygh orgs members myorg --role admin

Advanced Search

Search Repositories

# Search repositories by keyword
uv run mygh search repos "machine learning"

# Search with filters and sorting
uv run mygh search repos "language:python stars:>1000" --sort stars --order desc

# Limit results
uv run mygh search repos "react" --limit 10

Search Users

# Search users
uv run mygh search users "location:London"

# Sort by followers
uv run mygh search users "repos:>50" --sort followers --order desc

Notification Management

List Notifications

# List unread notifications
uv run mygh notifications list

# Include read notifications
uv run mygh notifications list --all

# Show only participating notifications
uv run mygh notifications list --participating

Mark as Read

# Mark all notifications as read
uv run mygh notifications mark-read

# Mark notifications for specific repository as read
uv run mygh notifications mark-read --repo microsoft/vscode

Team Management

List Teams

# List organization teams
uv run mygh teams list myorg

Manage Team Members

# List team members
uv run mygh teams members myorg developers

# Show team member details
uv run mygh teams members myorg developers

Interactive Repository Browser

Launch Browser

# Browse your repositories interactively
uv run mygh browse repos

# Browse another user's repositories
uv run mygh browse repos octocat

Browser Controls:

• j/down: Move down
• k/up: Move up
• n/next: Next page
• p/prev: Previous page
• f/filter: Filter repositories
• c/clear: Clear filter
• enter: View repository details
• q/quit: Exit browser

Configuration Management

List Current Configuration

uv run mygh config list

Set Configuration Values

# Set default output format
uv run mygh config set output-format json

# Set default results per page
uv run mygh config set default-per-page 50

Get Specific Configuration Value

uv run mygh config get output-format

🔧 Configuration

MyGH uses a TOML configuration file located at ~/.config/mygh/config.toml. Here's an example:

output-format = "table"
default-per-page = 30

Configuration Options

Option	Description	Default	Environment Variable
output-format	Default output format (table, json, csv)	table	MYGH_OUTPUT_FORMAT
default-per-page	Default number of results per page	30	MYGH_DEFAULT_PER_PAGE
github-token	GitHub personal access token	-	GITHUB_TOKEN

Environment Variables

Environment variables take precedence over configuration file settings:

• GITHUB_TOKEN or GH_TOKEN: GitHub authentication token
• MYGH_OUTPUT_FORMAT: Default output format
• MYGH_DEFAULT_PER_PAGE: Default pagination limit

🏗️ Development

Project Structure

mygh/
├── src/mygh/               # Main package
│   ├── cli/               # CLI commands
│   │   ├── main.py        # Main CLI entry point
│   │   ├── user.py        # User-related commands
│   │   └── repos.py       # Repository commands
│   ├── api/               # GitHub API integration
│   │   ├── client.py      # HTTP client
│   │   └── models.py      # Pydantic models
│   ├── utils/             # Utilities
│   │   ├── config.py      # Configuration management
│   │   └── formatting.py  # Output formatting
│   └── exceptions.py      # Custom exceptions
├── tests/                 # Test suite
├── pyproject.toml        # Project configuration
├── uv.lock              # Dependency lock file
└── README.md            # This file

Setting Up Development Environment

1. Clone and setup:

   git clone https://github.com/ryancheley/MyGH.git
   cd MyGH
   uv sync --dev
   

2. Run tests:

   uv run pytest
   

3. Code formatting and linting:

   uv run ruff check
   uv run ruff format
   uv run mypy src/
   

4. Install in development mode:

   uv sync
   

Running Tests

MyGH includes a comprehensive test suite with 97% code coverage that exceeds industry standards:

# Run all tests
uv run pytest

# Run with coverage reporting
uv run pytest --cov=src/mygh --cov-report=term-missing

# Run tests with coverage requirement (95%+)
uv run pytest --cov=src/mygh --cov-fail-under=95

# Run specific test file
uv run pytest tests/test_api_client.py

# Run tests with verbose output
uv run pytest -v

# Generate HTML coverage report
uv run pytest --cov=src/mygh --cov-report=html

Multi-Python Testing with Tox

MyGH supports Python 3.10 through Python 3.14 (beta) and uses tox for comprehensive testing across all versions:

# Install tox (if not already installed)
uv sync --dev

# Test across all Python versions (3.10-3.14)
uv run tox

# Test specific Python version
uv run tox -e py311

# Test Python 3.14 beta specifically
uv run tox -e py314-dev

# Test multiple specific versions
uv run tox -e py310,py311,py312

# Run linting across all versions
uv run tox -e lint

# Run type checking
uv run tox -e type

# Run coverage with detailed reporting
uv run tox -e coverage

# List all available test environments
uv run tox -l

# Run tests in parallel (faster)
uv run tox -p auto

# Clean and recreate all environments
uv run tox --recreate

Expected Tox Results

When running uv run tox, you should see results similar to:

py310: OK (5.80=setup[4.16]+cmd[1.64] seconds)
py311: OK (6.98=setup[5.09]+cmd[1.89] seconds)  
py312: OK (1.91=setup[0.35]+cmd[1.55] seconds)
py313: OK (5.92=setup[4.00]+cmd[1.92] seconds)
py314-dev: SKIP (0.00 seconds)  # May be skipped if Python 3.14 beta not installed
lint: FAIL/OK depending on code style
type: FAIL/OK depending on type annotations
coverage: OK (5.85=setup[3.91]+cmd[1.94] seconds)

• Core Python versions (3.10-3.13): Should consistently pass
• Python 3.14 beta: May be skipped if not installed (this is expected)
• Lint environment: May fail with style violations that need fixing
• Type environment: May fail with type annotation issues
• Coverage environment: Should pass with 97%+ coverage

Tox Environments

Environment	Description	Python Versions
py310	Tests on Python 3.10	3.10
py311	Tests on Python 3.11	3.11
py312	Tests on Python 3.12	3.12
py313	Tests on Python 3.13	3.13
py314-dev	Tests on Python 3.14 (beta)	3.14 beta*
lint	Code linting with ruff	All
type	Type checking with mypy	All
coverage	Detailed coverage report (97%+)	All

Note: *Python 3.14 beta may not be available on all systems and will be skipped if not installed.

Test Coverage Details

The test suite achieves 97% coverage across all components:

Component	Coverage	Focus Areas
api/models.py	100%	Pydantic data validation and serialization
exceptions.py	100%	Custom exception handling
cli/user.py	100%	User command implementations
utils/formatting.py	98%	Output formatting (table, JSON, CSV)
utils/config.py	97%	Configuration management
cli/repos.py	96%	Repository command implementations
cli/main.py	95%	Main CLI entry point and decorators
api/client.py	92%	GitHub API client and HTTP handling

Test Suite Features

• 🔄 Async Testing: Full async/await support with pytest-asyncio
• 🌐 HTTP Mocking: Complete API mocking with respx for reliable tests
• 🎭 CLI Testing: Comprehensive CLI command testing with Typer's test runner
• 📊 Edge Cases: Extensive edge case coverage including error scenarios
• ⚡ Performance: Fast test execution with parallel capabilities
• 🔧 Integration: End-to-end testing of complete workflows

Test Categories

# API client tests - GitHub API integration
uv run pytest tests/test_api_client.py

# CLI command tests - User interface testing
uv run pytest tests/test_cli.py

# Data model tests - Pydantic validation
uv run pytest tests/test_models.py

# Configuration tests - Settings management
uv run pytest tests/test_config.py

# Formatting tests - Output generation
uv run pytest tests/test_formatting.py

# Exception handling tests - Error scenarios
uv run pytest tests/test_exceptions.py

Code Quality

The project uses several tools to maintain code quality:

• Ruff: Fast Python linter and formatter
• MyPy: Static type checking
• Pytest: Testing framework with 97% coverage
• pytest-cov: Coverage reporting and enforcement
• pytest-asyncio: Async testing support
• respx: HTTP request mocking for reliable API tests

Version Management

MyGH includes an automated version bumping script that updates both pyproject.toml and creates git tags to trigger releases:

# Bump patch version (0.1.1 -> 0.1.2)
uv run python bump-version.py patch

# Bump minor version (0.1.1 -> 0.2.0)
uv run python bump-version.py minor

# Bump major version (0.1.1 -> 1.0.0)
uv run python bump-version.py major

The script will:

1. Update the version in pyproject.toml
2. Create a git commit with the version change
3. Create and push a git tag (e.g., v0.1.2)
4. Automatically trigger the release workflow for PyPI publishing

Requirements: The packaging library is included in development dependencies.

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes
4. Run comprehensive tests: uv run pytest --cov=src/mygh --cov-fail-under=95
5. Test across Python versions: uv run tox
6. Run linting: uv run tox -e lint
7. Type checking: uv run tox -e type
8. Commit your changes: git commit -am 'Add some feature'
9. Push to the branch: git push origin feature-name
10. Submit a pull request

Handling Tox Failures

If you encounter failures in specific environments:

# Fix linting issues automatically where possible
uv run ruff check --fix src tests
uv run ruff format src tests

# Check what lint issues remain
uv run tox -e lint

# Fix type checking issues
uv run mypy src/mygh

# Re-run type checking environment
uv run tox -e type

# Run only the core test environments (skip lint/type)
uv run tox -e py310,py311,py312,py313,py314-dev,coverage

Note: All contributions must maintain the 95%+ test coverage requirement and pass tests on Python 3.10-3.14 (beta). Linting and type checking issues should be resolved for production code.

🛠️ Built With

Core Technologies

• Python 3.10+ - Programming language
• Typer - CLI framework
• Rich - Terminal formatting
• httpx - Async HTTP client
• Pydantic - Data validation
• uv - Modern package manager

Testing & Quality

• pytest - Testing framework
• pytest-asyncio - Async testing support
• pytest-cov - Coverage reporting
• respx - HTTP request mocking
• tox - Multi-Python version testing (3.10-3.14 beta)
• ruff - Fast linting and formatting
• mypy - Static type checking

📋 API Reference

GitHub API Integration

MyGH integrates with the GitHub REST API v3 and handles:

• Authentication: Personal access tokens and GitHub CLI integration
• Rate Limiting: Automatic handling of API rate limits
• Error Handling: Comprehensive error messages and retry logic
• Pagination: Efficient handling of paginated responses

Supported Endpoints

• /user - Authenticated user information
• /users/{username} - User information
• /user/starred - Starred repositories
• /users/{username}/starred - User's starred repositories
• /user/repos - User repositories
• /users/{username}/repos - User's repositories
• /user/gists - User gists
• /users/{username}/gists - User's gists
• /repos/{owner}/{repo}/issues - Repository issues

🚨 Error Handling

MyGH provides clear error messages for common scenarios:

• Authentication Errors: Clear instructions for setting up tokens
• API Rate Limits: Informative messages about rate limit status
• Network Issues: Retry logic for transient failures
• Invalid Parameters: Helpful parameter validation messages

🔒 Security

• Token Security: GitHub tokens are never logged or displayed
• Configuration: Tokens are not saved to configuration files
• Environment: Secure handling of environment variables
• HTTPS: All API communications use HTTPS

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Support

• Documentation: Check this README and built-in help (mygh --help)
• Issues: Report bugs and request features via GitHub Issues
• GitHub API: Refer to GitHub REST API documentation

🎯 Roadmap

• Interactive repository browser
• Repository creation and management
• Pull request management
• GitHub Actions integration
• Organization management
• Advanced search capabilities
• Notification management
• Team management features

---

Made with ❤️ using modern Python tooling