# gh-toolkit
[](https://badge.fury.io/py/gh-toolkit)
[](https://www.python.org/downloads/)
**GitHub repository portfolio management and presentation toolkit with LLM-powered categorization and beautiful site generation**
A comprehensive command-line tool for managing GitHub repository portfolios at scale. Perfect for academics, educators, and developers who need to organize, categorize, and showcase their GitHub repositories professionally.
## ✨ Features
- 📋 **Repository Management** - List, filter, and extract comprehensive repository data
- 🤖 **LLM-Powered Categorization** - Intelligent repository classification using Claude AI
- 🏷️ **Automated Topic Tagging** - Smart topic suggestions with fallback rules
- 🩺 **Repository Health Checking** - Comprehensive quality audits with best practices compliance
- 🎨 **Portfolio Site Generation** - Beautiful, responsive HTML portfolios with 4 themes
- 📄 **Landing Page Generation** - Convert README.md to stunning HTML or Jekyll pages
- 📧 **Invitation Management** - Bulk accept/leave repository collaborations
- 🎯 **Academic Workflow** - Perfect alternative to GitHub Classroom
- ⚡ **Modern CLI** - Built with typer and rich for beautiful terminal experience
## 🚀 Quick Start
### Installation
```bash
pip install gh-toolkit
```
### Basic Usage
```bash
# List repositories
gh-toolkit repo list username
# Extract repository data with LLM categorization
gh-toolkit repo extract repos.txt --anthropic-key=sk-...
# Generate beautiful portfolio site
gh-toolkit site generate repos_data.json --theme educational
# Convert README to landing page
gh-toolkit page generate README.md --output index.html
# Check repository health and best practices
gh-toolkit repo health username/repo --rules academic
# Add topic tags to repositories
gh-toolkit repo tag username/* --dry-run
# Manage invitations (perfect for educators)
gh-toolkit invite accept --dry-run
```
## 📖 Commands
### Repository Commands
```bash
# List repositories with filters
gh-toolkit repo list michael-borck --public --language Python
# Extract comprehensive data
gh-toolkit repo extract repos.txt \
--anthropic-key=sk-... \
--output portfolio_data.json
# Add intelligent topic tags
gh-toolkit repo tag user/repo --force --anthropic-key=sk-...
# Check repository health and compliance
gh-toolkit repo health user/repo --rules professional --min-score 80
```
### Site Generation
```bash
# Generate portfolio with different themes
gh-toolkit site generate repos.json --theme educational
gh-toolkit site generate repos.json --theme resume
gh-toolkit site generate repos.json --theme research
gh-toolkit site generate repos.json --theme portfolio
# Custom title and metadata
gh-toolkit site generate repos.json \
--title "My Projects" \
--description "My awesome software" \
--metadata custom.yaml
```
### Page Generation
```bash
# Generate standalone HTML landing page
gh-toolkit page generate README.md
# Generate Jekyll-compatible markdown
gh-toolkit page generate README.md --jekyll --output index.md
# Custom title and description
gh-toolkit page generate README.md --jekyll \
--title "My Project" \
--description "Amazing software project"
```
### Invitation Management
```bash
# Accept all pending invitations
gh-toolkit invite accept --dry-run
# Leave repositories you're collaborating on
gh-toolkit invite leave --confirm
```
## 🎨 Portfolio Themes
### Educational Theme
Perfect for educators and academic portfolios
- Purple gradient design
- Emphasizes learning resources and tools
- Category order: Desktop → Web → Python → Learning Resources
### Resume Theme
Professional showcase for career portfolios
- Blue corporate design
- Highlights technical expertise
- Category order: Web → Desktop → Python → Infrastructure
### Research Theme
Academic research and scientific computing
- Green academic design
- Focuses on publications and analysis
- Category order: Learning → Analysis → Python → Web
### Portfolio Theme
General project showcase
- Indigo modern design
- Balanced category presentation
- Category order: Web → Desktop → Python → Infrastructure
## 🤖 LLM Integration
gh-toolkit integrates with Anthropic's Claude for intelligent repository analysis:
- **Smart Categorization** - Analyzes README, description, languages, and topics
- **Confidence Scoring** - Shows certainty of AI classifications
- **Graceful Fallback** - Uses rule-based classification when LLM unavailable
- **Topic Generation** - Suggests relevant GitHub topics based on content
```bash
export ANTHROPIC_API_KEY=sk-ant-...
gh-toolkit repo extract repos.txt # Uses LLM automatically
```
## 📚 Academic Use Case
Perfect alternative to GitHub Classroom:
```bash
# Students accept repository invitations
gh-toolkit invite accept
# Extract all student repositories
gh-toolkit repo extract student_repos.txt --anthropic-key=sk-...
# Generate class portfolio site
gh-toolkit site generate student_data.json \
--theme educational \
--title "CS 101 Student Projects" \
--output class_portfolio.html
```
## 🛠️ Development
### Setup
```bash
git clone https://github.com/michael-borck/gh-toolkit.git
cd gh-toolkit
uv sync --group dev
```
### Testing
```bash
# Run all tests
./scripts/test.sh
# Generate coverage report
./scripts/coverage.sh
# Run specific test suites
uv run pytest tests/unit/ -v
uv run pytest tests/integration/ -v
```
### Architecture
```
src/gh_toolkit/
├── cli.py # Main CLI entry point
├── commands/ # Command implementations
│ ├── repo.py # Repository management
│ ├── site.py # Site generation
│ ├── tag.py # Topic tagging
│ └── invite.py # Invitation management
└── core/ # Core functionality
├── github_client.py # GitHub API client
├── repo_extractor.py # Data extraction
├── site_generator.py # HTML generation
└── topic_tagger.py # LLM tagging
```
## 🔧 Configuration
### Environment Variables
```bash
export GITHUB_TOKEN=ghp_... # GitHub personal access token
export ANTHROPIC_API_KEY=sk-ant-... # Anthropic API key (optional)
```
### GitHub Token Scopes
- `repo` - Access repositories
- `read:org` - Read organization membership
- `write:org` - Accept organization invitations
## 📊 Example Workflow
```bash
# 1. Extract repository data
gh-toolkit repo extract my_repos.txt \
--anthropic-key=$ANTHROPIC_API_KEY \
--output extracted_data.json
# 2. Add topic tags
gh-toolkit repo tag my_repos.txt \
--anthropic-key=$ANTHROPIC_API_KEY \
--force
# 3. Generate portfolio site
gh-toolkit site generate extracted_data.json \
--theme portfolio \
--title "My Software Portfolio" \
--output index.html
# 4. Deploy to GitHub Pages
# Upload index.html to your GitHub Pages repository
```
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit changes (`git commit -m 'Add amazing feature'`)
4. Push to branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## 📝 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- Built with [typer](https://typer.tiangolo.com/) and [rich](https://rich.readthedocs.io/)
- LLM integration powered by [Anthropic Claude](https://www.anthropic.com/claude)
- Modern Python tooling with [uv](https://github.com/astral-sh/uv)
---
**⭐ Star this repository if gh-toolkit helps you manage your GitHub portfolio!**
Raw data
{
"_id": null,
"home_page": null,
"name": "gh-toolkit",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "cli, github, management, portfolio, repository",
"author": null,
"author_email": "Michael Borck <michael.borck@curtin.edu.au>",
"download_url": "https://files.pythonhosted.org/packages/98/74/31f15640857d4329396cfec1a219267406824583cd697e5447c1da3eba72/gh_toolkit-0.10.3.tar.gz",
"platform": null,
"description": "# gh-toolkit\n\n[](https://badge.fury.io/py/gh-toolkit)\n[](https://www.python.org/downloads/)\n\n**GitHub repository portfolio management and presentation toolkit with LLM-powered categorization and beautiful site generation**\n\nA comprehensive command-line tool for managing GitHub repository portfolios at scale. Perfect for academics, educators, and developers who need to organize, categorize, and showcase their GitHub repositories professionally.\n\n## \u2728 Features\n\n- \ud83d\udccb **Repository Management** - List, filter, and extract comprehensive repository data\n- \ud83e\udd16 **LLM-Powered Categorization** - Intelligent repository classification using Claude AI\n- \ud83c\udff7\ufe0f **Automated Topic Tagging** - Smart topic suggestions with fallback rules\n- \ud83e\ude7a **Repository Health Checking** - Comprehensive quality audits with best practices compliance\n- \ud83c\udfa8 **Portfolio Site Generation** - Beautiful, responsive HTML portfolios with 4 themes\n- \ud83d\udcc4 **Landing Page Generation** - Convert README.md to stunning HTML or Jekyll pages\n- \ud83d\udce7 **Invitation Management** - Bulk accept/leave repository collaborations\n- \ud83c\udfaf **Academic Workflow** - Perfect alternative to GitHub Classroom\n- \u26a1 **Modern CLI** - Built with typer and rich for beautiful terminal experience\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\n```bash\npip install gh-toolkit\n```\n\n### Basic Usage\n\n```bash\n# List repositories\ngh-toolkit repo list username\n\n# Extract repository data with LLM categorization\ngh-toolkit repo extract repos.txt --anthropic-key=sk-...\n\n# Generate beautiful portfolio site\ngh-toolkit site generate repos_data.json --theme educational\n\n# Convert README to landing page\ngh-toolkit page generate README.md --output index.html\n\n# Check repository health and best practices\ngh-toolkit repo health username/repo --rules academic\n\n# Add topic tags to repositories\ngh-toolkit repo tag username/* --dry-run\n\n# Manage invitations (perfect for educators)\ngh-toolkit invite accept --dry-run\n```\n\n## \ud83d\udcd6 Commands\n\n### Repository Commands\n\n```bash\n# List repositories with filters\ngh-toolkit repo list michael-borck --public --language Python\n\n# Extract comprehensive data\ngh-toolkit repo extract repos.txt \\\n --anthropic-key=sk-... \\\n --output portfolio_data.json\n\n# Add intelligent topic tags\ngh-toolkit repo tag user/repo --force --anthropic-key=sk-...\n\n# Check repository health and compliance\ngh-toolkit repo health user/repo --rules professional --min-score 80\n```\n\n### Site Generation\n\n```bash\n# Generate portfolio with different themes\ngh-toolkit site generate repos.json --theme educational\ngh-toolkit site generate repos.json --theme resume \ngh-toolkit site generate repos.json --theme research\ngh-toolkit site generate repos.json --theme portfolio\n\n# Custom title and metadata\ngh-toolkit site generate repos.json \\\n --title \"My Projects\" \\\n --description \"My awesome software\" \\\n --metadata custom.yaml\n```\n\n### Page Generation\n\n```bash\n# Generate standalone HTML landing page\ngh-toolkit page generate README.md\n\n# Generate Jekyll-compatible markdown\ngh-toolkit page generate README.md --jekyll --output index.md\n\n# Custom title and description\ngh-toolkit page generate README.md --jekyll \\\n --title \"My Project\" \\\n --description \"Amazing software project\"\n```\n\n### Invitation Management\n\n```bash\n# Accept all pending invitations\ngh-toolkit invite accept --dry-run\n\n# Leave repositories you're collaborating on\ngh-toolkit invite leave --confirm\n```\n\n## \ud83c\udfa8 Portfolio Themes\n\n### Educational Theme\nPerfect for educators and academic portfolios\n- Purple gradient design\n- Emphasizes learning resources and tools\n- Category order: Desktop \u2192 Web \u2192 Python \u2192 Learning Resources\n\n### Resume Theme \nProfessional showcase for career portfolios\n- Blue corporate design\n- Highlights technical expertise\n- Category order: Web \u2192 Desktop \u2192 Python \u2192 Infrastructure\n\n### Research Theme\nAcademic research and scientific computing\n- Green academic design \n- Focuses on publications and analysis\n- Category order: Learning \u2192 Analysis \u2192 Python \u2192 Web\n\n### Portfolio Theme\nGeneral project showcase\n- Indigo modern design\n- Balanced category presentation\n- Category order: Web \u2192 Desktop \u2192 Python \u2192 Infrastructure\n\n## \ud83e\udd16 LLM Integration\n\ngh-toolkit integrates with Anthropic's Claude for intelligent repository analysis:\n\n- **Smart Categorization** - Analyzes README, description, languages, and topics\n- **Confidence Scoring** - Shows certainty of AI classifications\n- **Graceful Fallback** - Uses rule-based classification when LLM unavailable\n- **Topic Generation** - Suggests relevant GitHub topics based on content\n\n```bash\nexport ANTHROPIC_API_KEY=sk-ant-...\ngh-toolkit repo extract repos.txt # Uses LLM automatically\n```\n\n## \ud83d\udcda Academic Use Case\n\nPerfect alternative to GitHub Classroom:\n\n```bash\n# Students accept repository invitations\ngh-toolkit invite accept\n\n# Extract all student repositories \ngh-toolkit repo extract student_repos.txt --anthropic-key=sk-...\n\n# Generate class portfolio site\ngh-toolkit site generate student_data.json \\\n --theme educational \\\n --title \"CS 101 Student Projects\" \\\n --output class_portfolio.html\n```\n\n## \ud83d\udee0\ufe0f Development\n\n### Setup\n\n```bash\ngit clone https://github.com/michael-borck/gh-toolkit.git\ncd gh-toolkit\nuv sync --group dev\n```\n\n### Testing\n\n```bash\n# Run all tests\n./scripts/test.sh\n\n# Generate coverage report\n./scripts/coverage.sh\n\n# Run specific test suites\nuv run pytest tests/unit/ -v\nuv run pytest tests/integration/ -v\n```\n\n### Architecture\n\n```\nsrc/gh_toolkit/\n\u251c\u2500\u2500 cli.py # Main CLI entry point\n\u251c\u2500\u2500 commands/ # Command implementations\n\u2502 \u251c\u2500\u2500 repo.py # Repository management\n\u2502 \u251c\u2500\u2500 site.py # Site generation \n\u2502 \u251c\u2500\u2500 tag.py # Topic tagging\n\u2502 \u2514\u2500\u2500 invite.py # Invitation management\n\u2514\u2500\u2500 core/ # Core functionality\n \u251c\u2500\u2500 github_client.py # GitHub API client\n \u251c\u2500\u2500 repo_extractor.py # Data extraction\n \u251c\u2500\u2500 site_generator.py # HTML generation\n \u2514\u2500\u2500 topic_tagger.py # LLM tagging\n```\n\n## \ud83d\udd27 Configuration\n\n### Environment Variables\n\n```bash\nexport GITHUB_TOKEN=ghp_... # GitHub personal access token\nexport ANTHROPIC_API_KEY=sk-ant-... # Anthropic API key (optional)\n```\n\n### GitHub Token Scopes\n\n- `repo` - Access repositories\n- `read:org` - Read organization membership \n- `write:org` - Accept organization invitations\n\n## \ud83d\udcca Example Workflow\n\n```bash\n# 1. Extract repository data\ngh-toolkit repo extract my_repos.txt \\\n --anthropic-key=$ANTHROPIC_API_KEY \\\n --output extracted_data.json\n\n# 2. Add topic tags\ngh-toolkit repo tag my_repos.txt \\\n --anthropic-key=$ANTHROPIC_API_KEY \\\n --force\n\n# 3. Generate portfolio site\ngh-toolkit site generate extracted_data.json \\\n --theme portfolio \\\n --title \"My Software Portfolio\" \\\n --output index.html\n\n# 4. Deploy to GitHub Pages\n# Upload index.html to your GitHub Pages repository\n```\n\n## \ud83e\udd1d Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit changes (`git commit -m 'Add amazing feature'`)\n4. Push to branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## \ud83d\udcdd License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f Acknowledgments\n\n- Built with [typer](https://typer.tiangolo.com/) and [rich](https://rich.readthedocs.io/)\n- LLM integration powered by [Anthropic Claude](https://www.anthropic.com/claude)\n- Modern Python tooling with [uv](https://github.com/astral-sh/uv)\n\n---\n\n**\u2b50 Star this repository if gh-toolkit helps you manage your GitHub portfolio!**",
"bugtrack_url": null,
"license": null,
"summary": "GitHub repository portfolio management and presentation toolkit",
"version": "0.10.3",
"project_urls": {
"Homepage": "https://github.com/michael-borck/gh-toolkit",
"Issues": "https://github.com/michael-borck/gh-toolkit/issues",
"Repository": "https://github.com/michael-borck/gh-toolkit"
},
"split_keywords": [
"cli",
" github",
" management",
" portfolio",
" repository"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "60988718bf195f9bd8fde5cd1b8acb18d7da4051b9f7c330f669aac4132d0c89",
"md5": "3e5624dfbbfbab5d682d3a57d8923775",
"sha256": "58dd62926612f8a27a20b9c8c6b73fd36e67329cd11691a66c87cdfcc7288567"
},
"downloads": -1,
"filename": "gh_toolkit-0.10.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3e5624dfbbfbab5d682d3a57d8923775",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 65120,
"upload_time": "2025-09-19T06:24:51",
"upload_time_iso_8601": "2025-09-19T06:24:51.588451Z",
"url": "https://files.pythonhosted.org/packages/60/98/8718bf195f9bd8fde5cd1b8acb18d7da4051b9f7c330f669aac4132d0c89/gh_toolkit-0.10.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "987431f15640857d4329396cfec1a219267406824583cd697e5447c1da3eba72",
"md5": "b0880f59662a681d8447440475e11451",
"sha256": "f0df16dfae94154dc7ab80a55b007178e5d22b56f8245d650e400318be62a9c1"
},
"downloads": -1,
"filename": "gh_toolkit-0.10.3.tar.gz",
"has_sig": false,
"md5_digest": "b0880f59662a681d8447440475e11451",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 114546,
"upload_time": "2025-09-19T06:24:53",
"upload_time_iso_8601": "2025-09-19T06:24:53.736994Z",
"url": "https://files.pythonhosted.org/packages/98/74/31f15640857d4329396cfec1a219267406824583cd697e5447c1da3eba72/gh_toolkit-0.10.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-19 06:24:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "michael-borck",
"github_project": "gh-toolkit",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "gh-toolkit"
}
JSON
