https://github.com/iv4n-ga6l/ghexplorer
Terminal based GitHub profile explorer tool built in Go using Bubble Tea
https://github.com/iv4n-ga6l/ghexplorer
cli explorer go golang terminalbased
Last synced: 3 months ago
JSON representation
Terminal based GitHub profile explorer tool built in Go using Bubble Tea
- Host: GitHub
- URL: https://github.com/iv4n-ga6l/ghexplorer
- Owner: iv4n-ga6l
- Created: 2024-09-15T20:38:51.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-05-22T09:14:54.000Z (5 months ago)
- Last Synced: 2025-05-22T10:31:41.241Z (5 months ago)
- Topics: cli, explorer, go, golang, terminalbased
- Language: Go
- Homepage:
- Size: 1.58 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# GitHub Profile Explorer (ghexplorer)
[](https://golang.org)
[](LICENSE)
[](#)
A powerful, interactive Terminal User Interface (TUI) application built with Go that allows you to explore GitHub profiles, repositories, and file contents directly from your terminal. Built using the excellent [Bubble Tea](https://github.com/charmbracelet/bubbletea) framework for creating delightful TUI applications.
https://github.com/user-attachments/assets/aa417c9e-3b3d-4ad1-a3e8-ca4991580a25
## ✨ Features
### 🔍 **Interactive Profile Exploration**
- Browse GitHub user profiles with detailed information
- View follower/following counts and bio information
- Navigate through user repositories with pagination
- Search repositories by name or description
### 📁 **Repository Navigation**
- Explore repository file structures interactively
- Navigate through directories with breadcrumb navigation
- View file contents with syntax highlighting support
- Copy file contents to clipboard
### 🎨 **Beautiful TUI Interface**
- Modern, responsive terminal interface
- Tab-based navigation between different views
- Keyboard shortcuts for efficient navigation
- Color-coded file types and folders
- Loading spinners and progress indicators
### 🚀 **Command Line Interface**
- Direct repository exploration without TUI
- JSON and text output formats
- Batch operations for automation
- Search functionality from command line
## 🛠️ Installation
### Prerequisites
- Go 1.23 or higher
- Git
### Build from Source
```bash
# Clone the repository
git clone https://github.com/IvanGael/ghexplorer.git
cd ghexplorer
# Install the required dependencies
go mod download
go mod tidy
# Build the application
go build -o ghexplorer
# (Optional) Install globally
go install
```
## 🚀 Quick Start
### Interactive TUI Mode
```bash
# Start with username prompt
./ghexplorer explore
# Start with specific user
./ghexplorer explore octocat
```
### Command Line Mode
```bash
# Get repository information
./ghexplorer repo octocat Hello-World
# Search repositories
./ghexplorer search octocat "machine learning"
# Output as JSON
./ghexplorer repo octocat Hello-World --format json
# Save to file
./ghexplorer repo octocat Hello-World --output repo_info.txt
```
## 🎮 Usage Guide
### TUI Navigation
| Key | Action |
|-----|--------|
| `Enter` | Select item / Navigate into directory |
| `Esc` | Go back / Cancel selection |
| `Tab` | Switch between tabs (Overview/Repositories) |
| `↑/↓` | Navigate up/down in lists |
| `q` | Quit application |
| `/` | Search repositories |
| `Ctrl+A` | Select all text (in file view) |
| `Ctrl+C` | Copy selected text to clipboard |
| `Ctrl+D` | Deselect text |
### File Content View
- **Scroll**: Use `↑/↓` or `PgUp/PgDn` to scroll through file content
- **Select Text**: Use `Ctrl+A` to select all, then navigate with arrow keys
- **Copy**: Use `Ctrl+C` to copy selected text to clipboard
- **Navigate**: Use `Esc` to return to file list
## 📋 Available Commands
### `explore` - Interactive TUI
Start the interactive Terminal User Interface for exploring GitHub profiles.
```bash
ghexplorer explore [username] [flags]
```
**Flags:**
- `-o, --output string`: Output file for saving data
- `-f, --format string`: Output format (text/json) (default "text")
### `repo` - Repository Information
Get detailed information about a specific repository.
```bash
ghexplorer repo [username] [repository] [flags]
```
**Example:**
```bash
ghexplorer repo microsoft vscode --format json
```
### `search` - Repository Search
Search through a user's repositories.
```bash
ghexplorer search [username] [query] [flags]
```
**Example:**
```bash
ghexplorer search google "tensorflow" --output search_results.json
```
## 🏗️ Architecture
### Project Structure
```
ghexplorer/
├── cmd/ # CLI commands
│ ├── explore.go # TUI exploration command
│ ├── repo.go # Repository info command
│ ├── search.go # Search command
│ └── root.go # Root command setup
├── config/ # Configuration and styling
│ └── config.go # App configuration
├── github_api/ # GitHub API integration
│ ├── github_api.go # API client implementation
│ └── github_api_test.go # API tests
├── helper/ # Utility functions
│ └── helper.go # Helper functions
├── model/ # Bubble Tea models
│ └── model.go # TUI state management
└── main.go # Application entry point
```
### Key Components
- **Bubble Tea Model**: Handles TUI state management and user interactions
- **GitHub API Client**: Manages all GitHub API communications
- **Cobra CLI**: Provides command-line interface structure
- **Lip Gloss**: Handles terminal styling and layout
## 🔧 Configuration
### Environment Variables
- `GITHUB_TOKEN`: (Optional) GitHub personal access token for higher rate limits
- `GITHUB_API_BASE_URL`: (Optional) Custom GitHub API base URL
### Rate Limiting
The application uses the GitHub API without authentication by default, which has the following rate limits:
- **60 requests per hour** for unauthenticated requests
- **5,000 requests per hour** with authentication
For production use or heavy usage, consider setting up a GitHub personal access token.
## 🧪 Testing
```bash
# Run all tests
go test ./...
# Run tests with coverage
go test -cover ./...
# Run specific package tests
go test ./github_api
```
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
### Development Setup
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
### Code Style
- Follow standard Go formatting (`go fmt`)
- Add tests for new functionality
- Update documentation as needed
- Use meaningful commit messages
## 📝 License
This project is licensed under the MIT License
## 🙏 Acknowledgments
- [Bubble Tea](https://github.com/charmbracelet/bubbletea) - The TUI framework that makes this possible
- [Lip Gloss](https://github.com/charmbracelet/lipgloss) - For beautiful terminal styling
- [Cobra](https://github.com/spf13/cobra) - For the CLI framework
- [Clipboard](https://github.com/atotto/clipboard) - For clipboard functionality
- GitHub API - For providing the data that powers this application
## 🐛 Known Issues
- Large files may take time to load and display
- Binary files are not properly handled in the file viewer
- Search functionality is limited to repository names and descriptions
## 🔮 Future Enhancements
- [ ] GitHub authentication support
- [ ] Syntax highlighting for code files
- [ ] Repository cloning functionality
- [ ] Issue and PR browsing
- [ ] Star/unstar repositories
- [ ] Multiple user profile comparison
- [ ] Export functionality for profiles and repositories
- [ ] Plugin system for custom extensions
## 📊 Performance
- **Startup Time**: < 1 second
- **Memory Usage**: ~10-20 MB typical
- **API Calls**: Optimized with pagination and caching
- **File Loading**: Efficient streaming for large files
---
**Made with 💙 and Go**
If you find this project useful, please consider giving it a ⭐ on GitHub!