# Fast Gogs CLI
A high-performance, async command-line interface for interacting with Gogs Git repositories. Built with modern Python async/await patterns for maximum speed and efficiency.
[](https://badge.fury.io/py/gogs-cli)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
## Features
- **Fast Async Operations**: Built with `aiohttp` for high-performance HTTP requests
- **Connection Pooling**: Reuses connections for better performance
- **Rich Terminal Output**: Beautiful colored output with progress indicators (optional)
- **Repository Management**: Create, list, delete, migrate, and clone repositories
- **User Management**: Get current user information
- **Configuration Management**: Flexible config file and command-line options
- **Git Integration**: Direct git clone operations with advanced options
- **Multiple Output Formats**: Table, JSON, and simple text formats
- **Retry Logic**: Automatic retry with exponential backoff for failed requests
- **Cross-Platform**: Works on Windows, macOS, and Linux with proper config file locations
## Installation
### From PyPI (Recommended)
```bash
pip install gogs-cli
```
### From Source
```bash
# Clone the repository
git clone https://github.com/cumulus13/gogs_cli.git
cd gogs_cli
# Install dependencies
pip install -r requirements.txt
# Or install in development mode
pip install -e .
```
### Requirements
```bash
# Required dependencies
pip install aiohttp
# Optional but recommended for better UI
pip install rich rich-argparse
# Optional for config file support
pip install configset
# Optional for clipboard support
pip install clipboard
```
## Configuration
The CLI automatically searches for configuration files in the following locations (in order):
### Configuration File Locations
**Linux/macOS:**
1. `~/.config/gogs_cli.ini`
2. `./gogs_cli.ini` (current directory)
3. `<script_directory>/gogs_cli.ini`
**Windows:**
1. `~/.gogs-cli/gogs_cli.ini`
2. `%APPDATA%/.gogs-cli/gogs_cli.ini`
3. `./gogs_cli.ini` (current directory)
4. `<script_directory>/gogs_cli.ini`
### Config File Format
Create a config file at any of the above locations:
```ini
[api]
key = your_gogs_api_token_here
url = http://your-gogs-server.com/api/v1
timeout = 30
[auth]
username = your_username
password = your_password
```
### Using Config Commands
Instead of manually editing the config file, you can use the built-in config commands:
```bash
# Set up your API configuration
gogs-cli/gogs config --set api.key YOUR_API_TOKEN
gogs-cli/gogs config --set api.url http://your-gogs-server.com/api/v1
# Or use short form
gogs-cli/gogs config --set key YOUR_API_TOKEN
gogs-cli/gogs config --set url http://gogs.example.com/api/v1
# Verify your configuration
gogs-cli/gogs config --show
```
### Command Line Options
You can override config file settings with command line arguments:
```bash
gogs-cli --api YOUR_API_TOKEN --url http://gogs.example.com/api/v1 repo -l
# Or
gogs --api YOUR_API_TOKEN --url http://gogs.example.com/api/v1 repo -l
# Or just
gogs-cli repo -l
```
### Getting API Token
1. Log in to your Gogs server
2. Go to Settings > Applications
3. Generate a new token
4. Copy the token to your config file or use with `--api` flag
## Usage
### Basic Syntax
```bash
gogs-cli/gogs [global-options] <command> [command-options]
```
### Global Options
- `-u, --username`: Gogs username
- `-p, --password`: Gogs password
- `--api`: Gogs API key/token
- `--url`: Gogs API endpoint URL
- `--timeout`: Request timeout in seconds (default: 30)
- `-v, --verbose`: Verbose output
- `-h, --help`: Show help message
## Commands
### Repository Operations (`repo`)
#### List Repositories
```bash
# List all repositories in table format (default)
gogs-cli/gogs repo -l
# List in JSON format
gogs-cli/gogs repo -l --format json
# List in simple format (names only)
gogs-cli/gogs repo -l --format simple
```
#### Create Repository
```bash
# Create a simple repository
gogs-cli/gogs repo -a myproject
# Create with description
gogs-cli/gogs repo -a myproject -d "My awesome project"
# Create private repository
gogs-cli/gogs repo -a myproject --private
# Create with description and make it private
gogs-cli/gogs repo -a myproject -d "Secret project" --private
```
#### Delete Repository
```bash
# Delete a repository
gogs-cli/gogs repo -rm oldproject
# The CLI will automatically detect the owner from your API token
```
#### Migrate Repository
```bash
# Migrate from GitHub
gogs-cli/gogs repo -m https://github.com/user/project.git
# Migrate with custom name
gogs-cli/gogs repo -m https://github.com/user/project.git -n mynewproject
# Migrate as private repository
gogs-cli/gogs repo -m https://github.com/user/project.git --private
# Migrate as mirror (read-only)
gogs-cli/gogs repo -m https://github.com/user/project.git --mirror
```
#### Clone Repository
```bash
# Clone your own repository by name
gogs-cli/gogs repo -c myproject
# Clone to specific directory
gogs-cli/gogs repo -c myproject --dest ./local-copy
# Clone specific branch
gogs-cli/gogs repo -c myproject --branch develop
# Shallow clone (faster for large repos)
gogs-cli/gogs repo -c myproject --depth 1
# Clone with submodules
gogs-cli/gogs repo -c myproject --recursive
# Clone from any URL
gogs-cli/gogs repo -c https://github.com/user/repo.git
# Clone with all options
gogs-cli/gogs repo -c myproject --dest ./my-local-copy --branch main --depth 5 --recursive
```
### User Operations (`user`)
#### Get User Information
```bash
# Show current user info in table format
gogs-cli/gogs user -i
# The output includes user ID, username, email, and other profile information
```
### Configuration Operations (`config`)
#### Show Configuration
```bash
# Display current configuration
gogs-cli/gogs config --show
```
#### Set Configuration Values
```bash
# Set API key
gogs-cli/gogs config --set api.key YOUR_API_TOKEN
# Set API URL
gogs-cli/gogs config --set api.url http://your-gogs-server.com/api/v1
# Set timeout
gogs-cli/gogs config --set api.timeout 60
# Set username for basic auth
gogs-cli/gogs config --set auth.username your_username
# Set password for basic auth
gogs-cli/gogs config --set auth.password your_password
# Short form (without section prefix)
gogs-cli/gogs config --set key YOUR_API_TOKEN
gogs-cli/gogs config --set url http://gogs.example.com/api/v1
gogs-cli/gogs config --set timeout 45
gogs-cli/gogs config --set username myuser
gogs-cli/gogs config --set password mypass
```
#### Get Configuration Values
```bash
# Get API key (will be masked for security)
gogs-cli/gogs config --get api.key
# Get API URL
gogs-cli/gogs config --get api.url
# Get timeout
gogs-cli/gogs config --get api.timeout
# Get username
gogs-cli/gogs config --get auth.username
# Short form
gogs-cli/gogs config --get key
gogs-cli/gogs config --get url
gogs-cli/gogs config --get timeout
```
#### List Available Configuration Keys
```bash
# Show all available configuration keys with descriptions
gogs-cli/gogs config --list
```
## Examples
### Complete Workflow Example
```bash
# 1. Set up configuration first
gogs-cli/gogs config --set key YOUR_API_TOKEN
gogs-cli/gogs config --set url http://your-gogs-server.com/api/v1
# 2. Verify configuration
gogs-cli/gogs config --show
# 3. Check current user
gogs-cli/gogs user -i
# 4. List existing repositories
gogs-cli/gogs repo -l
# 5. Create a new project
gogs-cli/gogs repo -a "my-new-project" -d "A sample project" --private
# 6. Clone it locally
gogs-cli/gogs repo -c "my-new-project" --dest ./my-project
# 7. Later, if you want to delete it
gogs-cli/gogs repo -rm "my-new-project"
```
### Configuration Management Example
```bash
# Initial setup
gogs-cli/gogs config --set api.key abc123...
gogs-cli/gogs config --set api.url http://gogs.company.com/api/v1
gogs-cli/gogs config --set api.timeout 60
# Check what's configured
gogs-cli/gogs config --list
gogs-cli/gogs config --show
# Get specific values
gogs-cli/gogs config --get api.url
gogs-cli/gogs config --get api.key # Will be masked for security
# Update configuration
gogs-cli/gogs config --set timeout 120
```
### Migration Example
```bash
# Migrate from GitHub to your Gogs server
gogs-cli/gogs repo -m https://github.com/torvalds/linux.git -n linux-mirror --mirror
# Migrate private repository
gogs-cli/gogs repo -m https://github.com/mycompany/private-repo.git --private
```
### Bulk Operations Example
```bash
# List all repos in JSON format and save to file
gogs-cli/gogs repo -l --format json > my-repos.json
# Get simple list for scripting
gogs-cli/gogs repo -l --format simple | while read repo; do
echo "Processing: $repo"
gogs-cli repo -c "$repo" --dest "backup/$repo"
done
```
## Performance Features
### Connection Pooling
The CLI uses connection pooling to reuse HTTP connections:
- **Total pool size**: 100 connections
- **Per-host limit**: 30 connections
- **DNS cache**: 5 minutes TTL
- **Automatic connection management**
### Retry Logic
Automatic retry with exponential backoff:
- **Max retries**: 3 attempts
- **Backoff**: 2^attempt seconds (1s, 2s, 4s)
- **Handles**: Connection errors, timeouts
### Async Operations
All network operations are asynchronous:
- **Non-blocking I/O**: Multiple operations can run concurrently
- **Better resource usage**: Lower memory and CPU usage
- **Faster execution**: Especially for multiple operations
## Error Handling
The CLI provides clear error messages and proper exit codes:
```bash
# API errors
❌ Failed to create repo: 409 Repository already exists
# Network errors
❌ Error: Connection timeout after 30 seconds
# Git errors
❌ Failed to clone repository: Repository not found
# Authentication errors
❌ Cannot determine user from API key
```
## Troubleshooting
### Common Issues
1. **Help not showing**: Make sure you're using the correct Python version (3.7+)
```bash
gogs-cli/gogs -h
```
2. **API connection issues**: Verify your API endpoint and token
```bash
gogs-cli/gogs --url http://your-gogs.com/api/v1 --api YOUR_TOKEN user -i
# Or set it permanently:
gogs-cli/gogs config --set api.url http://your-gogs.com/api/v1
gogs-cli/gogs config --set api.key YOUR_TOKEN
```
3. **Configuration not saving**: Make sure configset is installed
```bash
pip install configset
# Then use config commands:
gogs-cli/gogs config --set key YOUR_TOKEN
```
4. **Git not found**: Install git for clone operations
```bash
# Ubuntu/Debian
sudo apt-get install git
# macOS
brew install git
# Windows
# Download from https://git-scm.com/
```
5. **Rich formatting issues**: Install rich for better output
```bash
pip install rich rich-argparse
```
6. **Invalid configuration key error**: Use the list command to see valid keys
```bash
gogs-cli/gogs config --list
```
7. **Config file not found**: The CLI will automatically create a config file in the appropriate location for your OS when you first set a value
```bash
gogs-cli/gogs config --set key YOUR_TOKEN
# This will create the config file automatically
```
### Debug Mode
Enable debug output with environment variables:
```bash
# Show full tracebacks
TRACEBACK=1 gogs-cli repo -l
# Verbose output
gogs-cli/gogs -v repo -l
```
## Development
### Project Structure
```
gogs_cli.py # Main CLI script
gogs_cli.ini # Configuration file (optional)
README.md # This file
requirements.txt # Dependencies
```
### Requirements
```txt
aiohttp>=3.8.0
rich>=13.0.0
rich-argparse>=1.0.0
configset>=2.0.0
clipboard>=0.0.4
```
### Contributing
1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure code follows PEP 8
5. Submit a pull request
## License
MIT License - see [LICENSE](LICENSE) file for details
## Changelog
### v1.0.0 (Current)
- Initial release
- Async HTTP operations with aiohttp
- Repository CRUD operations
- Git clone integration
- User management
- Rich terminal output
- Configuration management
- Retry logic and error handling
## Support
- **Issues**: Report bugs on GitHub
- **Documentation**: Check this README
- **API Reference**: See Gogs API documentation
## Performance Comparison
| Operation | Requests (sync) | This CLI (async) | Improvement |
|-----------|-----------------|------------------|-------------|
| List 100 repos | ~2-5 seconds | ~0.5-1 seconds | 4-5x faster |
| Clone 5 repos | Sequential | Concurrent | 3-4x faster |
| Multiple API calls | Blocking | Non-blocking | 5-10x faster |
## Security Notes
- API tokens are sensitive - never commit them to version control
- Use environment variables or config files with proper permissions
- The CLI supports both token and username/password authentication
- HTTPS is recommended for production Gogs servers
## FAQ
**Q: How do I change my API configuration without editing files manually?**
A: Use the built-in config commands:
```bash
gogs config --set api.key YOUR_NEW_TOKEN
gogs config --set api.url http://new-server.com/api/v1
gogs config --show # Verify changes
```
**Q: What configuration keys are available?**
A: Run `python gogs_cli.py config --list` to see all available keys with descriptions.
**Q: Can I see my current API key?**
A: Yes, but it will be masked for security: `python gogs_cli.py config --get api.key`
**Q: How do I reset my configuration?**
A: Delete the config file (`gogs_cli.ini`) or set new values with `--set` commands.
## author
[Hadi Cahyadi](mailto:cumulus13@gmail.com)
[](https://www.buymeacoffee.com/cumulus13)
[](https://ko-fi.com/cumulus13)
[Support me on Patreon](https://www.patreon.com/cumulus13)
Raw data
{
"_id": null,
"home_page": "https://github.com/cumulus13/gogs_cli",
"name": "gogs-cli",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "gogs, gitea, git, cli, async, repository, api, command-line, version-control",
"author": "Hadi Cahyadi",
"author_email": "cumulus13@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/94/82/712de4fc31ca9aa0c3974c010e14ca5d8596969a6e90a7b6474a2275e48e/gogs_cli-0.17.tar.gz",
"platform": null,
"description": "# Fast Gogs CLI\r\n\r\nA high-performance, async command-line interface for interacting with Gogs Git repositories. Built with modern Python async/await patterns for maximum speed and efficiency.\r\n\r\n[](https://badge.fury.io/py/gogs-cli)\r\n[](https://www.python.org/downloads/)\r\n[](https://opensource.org/licenses/MIT)\r\n\r\n## Features\r\n\r\n- **Fast Async Operations**: Built with `aiohttp` for high-performance HTTP requests\r\n- **Connection Pooling**: Reuses connections for better performance\r\n- **Rich Terminal Output**: Beautiful colored output with progress indicators (optional)\r\n- **Repository Management**: Create, list, delete, migrate, and clone repositories\r\n- **User Management**: Get current user information\r\n- **Configuration Management**: Flexible config file and command-line options\r\n- **Git Integration**: Direct git clone operations with advanced options\r\n- **Multiple Output Formats**: Table, JSON, and simple text formats\r\n- **Retry Logic**: Automatic retry with exponential backoff for failed requests\r\n- **Cross-Platform**: Works on Windows, macOS, and Linux with proper config file locations\r\n\r\n## Installation\r\n\r\n### From PyPI (Recommended)\r\n\r\n```bash\r\npip install gogs-cli\r\n```\r\n\r\n### From Source\r\n\r\n```bash\r\n# Clone the repository\r\ngit clone https://github.com/cumulus13/gogs_cli.git\r\ncd gogs_cli\r\n\r\n# Install dependencies\r\npip install -r requirements.txt\r\n\r\n# Or install in development mode\r\npip install -e .\r\n```\r\n\r\n### Requirements\r\n\r\n```bash\r\n# Required dependencies\r\npip install aiohttp\r\n\r\n# Optional but recommended for better UI\r\npip install rich rich-argparse\r\n\r\n# Optional for config file support\r\npip install configset\r\n\r\n# Optional for clipboard support\r\npip install clipboard\r\n```\r\n\r\n## Configuration\r\n\r\nThe CLI automatically searches for configuration files in the following locations (in order):\r\n\r\n### Configuration File Locations\r\n\r\n**Linux/macOS:**\r\n1. `~/.config/gogs_cli.ini`\r\n2. `./gogs_cli.ini` (current directory)\r\n3. `<script_directory>/gogs_cli.ini`\r\n\r\n**Windows:**\r\n1. `~/.gogs-cli/gogs_cli.ini`\r\n2. `%APPDATA%/.gogs-cli/gogs_cli.ini`\r\n3. `./gogs_cli.ini` (current directory)\r\n4. `<script_directory>/gogs_cli.ini`\r\n\r\n### Config File Format\r\n\r\nCreate a config file at any of the above locations:\r\n\r\n```ini\r\n[api]\r\nkey = your_gogs_api_token_here\r\nurl = http://your-gogs-server.com/api/v1\r\ntimeout = 30\r\n\r\n[auth]\r\nusername = your_username\r\npassword = your_password\r\n```\r\n\r\n### Using Config Commands\r\n\r\nInstead of manually editing the config file, you can use the built-in config commands:\r\n\r\n```bash\r\n# Set up your API configuration\r\ngogs-cli/gogs config --set api.key YOUR_API_TOKEN\r\ngogs-cli/gogs config --set api.url http://your-gogs-server.com/api/v1\r\n\r\n# Or use short form\r\ngogs-cli/gogs config --set key YOUR_API_TOKEN\r\ngogs-cli/gogs config --set url http://gogs.example.com/api/v1\r\n\r\n# Verify your configuration\r\ngogs-cli/gogs config --show\r\n```\r\n\r\n### Command Line Options\r\n\r\nYou can override config file settings with command line arguments:\r\n\r\n```bash\r\ngogs-cli --api YOUR_API_TOKEN --url http://gogs.example.com/api/v1 repo -l\r\n# Or\r\ngogs --api YOUR_API_TOKEN --url http://gogs.example.com/api/v1 repo -l\r\n# Or just\r\ngogs-cli repo -l\r\n```\r\n\r\n### Getting API Token\r\n\r\n1. Log in to your Gogs server\r\n2. Go to Settings > Applications\r\n3. Generate a new token\r\n4. Copy the token to your config file or use with `--api` flag\r\n\r\n## Usage\r\n\r\n### Basic Syntax\r\n\r\n```bash\r\ngogs-cli/gogs [global-options] <command> [command-options]\r\n```\r\n\r\n### Global Options\r\n\r\n- `-u, --username`: Gogs username\r\n- `-p, --password`: Gogs password \r\n- `--api`: Gogs API key/token\r\n- `--url`: Gogs API endpoint URL\r\n- `--timeout`: Request timeout in seconds (default: 30)\r\n- `-v, --verbose`: Verbose output\r\n- `-h, --help`: Show help message\r\n\r\n## Commands\r\n\r\n### Repository Operations (`repo`)\r\n\r\n#### List Repositories\r\n\r\n```bash\r\n# List all repositories in table format (default)\r\ngogs-cli/gogs repo -l\r\n\r\n# List in JSON format\r\ngogs-cli/gogs repo -l --format json\r\n\r\n# List in simple format (names only)\r\ngogs-cli/gogs repo -l --format simple\r\n```\r\n\r\n#### Create Repository\r\n\r\n```bash\r\n# Create a simple repository\r\ngogs-cli/gogs repo -a myproject\r\n\r\n# Create with description\r\ngogs-cli/gogs repo -a myproject -d \"My awesome project\"\r\n\r\n# Create private repository\r\ngogs-cli/gogs repo -a myproject --private\r\n\r\n# Create with description and make it private\r\ngogs-cli/gogs repo -a myproject -d \"Secret project\" --private\r\n```\r\n\r\n#### Delete Repository\r\n\r\n```bash\r\n# Delete a repository\r\ngogs-cli/gogs repo -rm oldproject\r\n\r\n# The CLI will automatically detect the owner from your API token\r\n```\r\n\r\n#### Migrate Repository\r\n\r\n```bash\r\n# Migrate from GitHub\r\ngogs-cli/gogs repo -m https://github.com/user/project.git\r\n\r\n# Migrate with custom name\r\ngogs-cli/gogs repo -m https://github.com/user/project.git -n mynewproject\r\n\r\n# Migrate as private repository\r\ngogs-cli/gogs repo -m https://github.com/user/project.git --private\r\n\r\n# Migrate as mirror (read-only)\r\ngogs-cli/gogs repo -m https://github.com/user/project.git --mirror\r\n```\r\n\r\n#### Clone Repository\r\n\r\n```bash\r\n# Clone your own repository by name\r\ngogs-cli/gogs repo -c myproject\r\n\r\n# Clone to specific directory\r\ngogs-cli/gogs repo -c myproject --dest ./local-copy\r\n\r\n# Clone specific branch\r\ngogs-cli/gogs repo -c myproject --branch develop\r\n\r\n# Shallow clone (faster for large repos)\r\ngogs-cli/gogs repo -c myproject --depth 1\r\n\r\n# Clone with submodules\r\ngogs-cli/gogs repo -c myproject --recursive\r\n\r\n# Clone from any URL\r\ngogs-cli/gogs repo -c https://github.com/user/repo.git\r\n\r\n# Clone with all options\r\ngogs-cli/gogs repo -c myproject --dest ./my-local-copy --branch main --depth 5 --recursive\r\n```\r\n\r\n### User Operations (`user`)\r\n\r\n#### Get User Information\r\n\r\n```bash\r\n# Show current user info in table format\r\ngogs-cli/gogs user -i\r\n\r\n# The output includes user ID, username, email, and other profile information\r\n```\r\n\r\n### Configuration Operations (`config`)\r\n\r\n#### Show Configuration\r\n\r\n```bash\r\n# Display current configuration\r\ngogs-cli/gogs config --show\r\n```\r\n\r\n#### Set Configuration Values\r\n\r\n```bash\r\n# Set API key\r\ngogs-cli/gogs config --set api.key YOUR_API_TOKEN\r\n\r\n# Set API URL\r\ngogs-cli/gogs config --set api.url http://your-gogs-server.com/api/v1\r\n\r\n# Set timeout\r\ngogs-cli/gogs config --set api.timeout 60\r\n\r\n# Set username for basic auth\r\ngogs-cli/gogs config --set auth.username your_username\r\n\r\n# Set password for basic auth\r\ngogs-cli/gogs config --set auth.password your_password\r\n\r\n# Short form (without section prefix)\r\ngogs-cli/gogs config --set key YOUR_API_TOKEN\r\ngogs-cli/gogs config --set url http://gogs.example.com/api/v1\r\ngogs-cli/gogs config --set timeout 45\r\ngogs-cli/gogs config --set username myuser\r\ngogs-cli/gogs config --set password mypass\r\n```\r\n\r\n#### Get Configuration Values\r\n\r\n```bash\r\n# Get API key (will be masked for security)\r\ngogs-cli/gogs config --get api.key\r\n\r\n# Get API URL\r\ngogs-cli/gogs config --get api.url\r\n\r\n# Get timeout\r\ngogs-cli/gogs config --get api.timeout\r\n\r\n# Get username\r\ngogs-cli/gogs config --get auth.username\r\n\r\n# Short form\r\ngogs-cli/gogs config --get key\r\ngogs-cli/gogs config --get url\r\ngogs-cli/gogs config --get timeout\r\n```\r\n\r\n#### List Available Configuration Keys\r\n\r\n```bash\r\n# Show all available configuration keys with descriptions\r\ngogs-cli/gogs config --list\r\n```\r\n\r\n## Examples\r\n\r\n### Complete Workflow Example\r\n\r\n```bash\r\n# 1. Set up configuration first\r\ngogs-cli/gogs config --set key YOUR_API_TOKEN\r\ngogs-cli/gogs config --set url http://your-gogs-server.com/api/v1\r\n\r\n# 2. Verify configuration\r\ngogs-cli/gogs config --show\r\n\r\n# 3. Check current user\r\ngogs-cli/gogs user -i\r\n\r\n# 4. List existing repositories\r\ngogs-cli/gogs repo -l\r\n\r\n# 5. Create a new project\r\ngogs-cli/gogs repo -a \"my-new-project\" -d \"A sample project\" --private\r\n\r\n# 6. Clone it locally\r\ngogs-cli/gogs repo -c \"my-new-project\" --dest ./my-project\r\n\r\n# 7. Later, if you want to delete it\r\ngogs-cli/gogs repo -rm \"my-new-project\"\r\n```\r\n\r\n### Configuration Management Example\r\n\r\n```bash\r\n# Initial setup\r\ngogs-cli/gogs config --set api.key abc123...\r\ngogs-cli/gogs config --set api.url http://gogs.company.com/api/v1\r\ngogs-cli/gogs config --set api.timeout 60\r\n\r\n# Check what's configured\r\ngogs-cli/gogs config --list\r\ngogs-cli/gogs config --show\r\n\r\n# Get specific values\r\ngogs-cli/gogs config --get api.url\r\ngogs-cli/gogs config --get api.key # Will be masked for security\r\n\r\n# Update configuration\r\ngogs-cli/gogs config --set timeout 120\r\n```\r\n\r\n### Migration Example\r\n\r\n```bash\r\n# Migrate from GitHub to your Gogs server\r\ngogs-cli/gogs repo -m https://github.com/torvalds/linux.git -n linux-mirror --mirror\r\n\r\n# Migrate private repository\r\ngogs-cli/gogs repo -m https://github.com/mycompany/private-repo.git --private\r\n```\r\n\r\n### Bulk Operations Example\r\n\r\n```bash\r\n# List all repos in JSON format and save to file\r\ngogs-cli/gogs repo -l --format json > my-repos.json\r\n\r\n# Get simple list for scripting\r\ngogs-cli/gogs repo -l --format simple | while read repo; do\r\n echo \"Processing: $repo\"\r\n gogs-cli repo -c \"$repo\" --dest \"backup/$repo\"\r\ndone\r\n```\r\n\r\n## Performance Features\r\n\r\n### Connection Pooling\r\n\r\nThe CLI uses connection pooling to reuse HTTP connections:\r\n- **Total pool size**: 100 connections\r\n- **Per-host limit**: 30 connections \r\n- **DNS cache**: 5 minutes TTL\r\n- **Automatic connection management**\r\n\r\n### Retry Logic\r\n\r\nAutomatic retry with exponential backoff:\r\n- **Max retries**: 3 attempts\r\n- **Backoff**: 2^attempt seconds (1s, 2s, 4s)\r\n- **Handles**: Connection errors, timeouts\r\n\r\n### Async Operations\r\n\r\nAll network operations are asynchronous:\r\n- **Non-blocking I/O**: Multiple operations can run concurrently\r\n- **Better resource usage**: Lower memory and CPU usage\r\n- **Faster execution**: Especially for multiple operations\r\n\r\n## Error Handling\r\n\r\nThe CLI provides clear error messages and proper exit codes:\r\n\r\n```bash\r\n# API errors\r\n\u274c Failed to create repo: 409 Repository already exists\r\n\r\n# Network errors \r\n\u274c Error: Connection timeout after 30 seconds\r\n\r\n# Git errors\r\n\u274c Failed to clone repository: Repository not found\r\n\r\n# Authentication errors\r\n\u274c Cannot determine user from API key\r\n```\r\n\r\n## Troubleshooting\r\n\r\n### Common Issues\r\n\r\n1. **Help not showing**: Make sure you're using the correct Python version (3.7+)\r\n ```bash\r\n gogs-cli/gogs -h\r\n ```\r\n\r\n2. **API connection issues**: Verify your API endpoint and token\r\n ```bash\r\n gogs-cli/gogs --url http://your-gogs.com/api/v1 --api YOUR_TOKEN user -i\r\n # Or set it permanently:\r\n gogs-cli/gogs config --set api.url http://your-gogs.com/api/v1\r\n gogs-cli/gogs config --set api.key YOUR_TOKEN\r\n ```\r\n\r\n3. **Configuration not saving**: Make sure configset is installed\r\n ```bash\r\n pip install configset\r\n # Then use config commands:\r\n gogs-cli/gogs config --set key YOUR_TOKEN\r\n ```\r\n\r\n4. **Git not found**: Install git for clone operations\r\n ```bash\r\n # Ubuntu/Debian\r\n sudo apt-get install git\r\n \r\n # macOS\r\n brew install git\r\n \r\n # Windows\r\n # Download from https://git-scm.com/\r\n ```\r\n\r\n5. **Rich formatting issues**: Install rich for better output\r\n ```bash\r\n pip install rich rich-argparse\r\n ```\r\n\r\n6. **Invalid configuration key error**: Use the list command to see valid keys\r\n ```bash\r\n gogs-cli/gogs config --list\r\n ```\r\n\r\n7. **Config file not found**: The CLI will automatically create a config file in the appropriate location for your OS when you first set a value\r\n ```bash\r\n gogs-cli/gogs config --set key YOUR_TOKEN\r\n # This will create the config file automatically\r\n ```\r\n\r\n### Debug Mode\r\n\r\nEnable debug output with environment variables:\r\n\r\n```bash\r\n# Show full tracebacks\r\nTRACEBACK=1 gogs-cli repo -l\r\n\r\n# Verbose output\r\ngogs-cli/gogs -v repo -l\r\n```\r\n\r\n## Development\r\n\r\n### Project Structure\r\n\r\n```\r\ngogs_cli.py # Main CLI script\r\ngogs_cli.ini # Configuration file (optional)\r\nREADME.md # This file\r\nrequirements.txt # Dependencies\r\n```\r\n\r\n### Requirements\r\n\r\n```txt\r\naiohttp>=3.8.0\r\nrich>=13.0.0\r\nrich-argparse>=1.0.0\r\nconfigset>=2.0.0\r\nclipboard>=0.0.4\r\n```\r\n\r\n### Contributing\r\n\r\n1. Fork the repository\r\n2. Create a feature branch\r\n3. Add tests for new functionality\r\n4. Ensure code follows PEP 8\r\n5. Submit a pull request\r\n\r\n## License\r\n\r\nMIT License - see [LICENSE](LICENSE) file for details\r\n\r\n## Changelog\r\n\r\n### v1.0.0 (Current)\r\n- Initial release\r\n- Async HTTP operations with aiohttp\r\n- Repository CRUD operations\r\n- Git clone integration\r\n- User management\r\n- Rich terminal output\r\n- Configuration management\r\n- Retry logic and error handling\r\n\r\n## Support\r\n\r\n- **Issues**: Report bugs on GitHub\r\n- **Documentation**: Check this README\r\n- **API Reference**: See Gogs API documentation\r\n\r\n## Performance Comparison\r\n\r\n| Operation | Requests (sync) | This CLI (async) | Improvement |\r\n|-----------|-----------------|------------------|-------------|\r\n| List 100 repos | ~2-5 seconds | ~0.5-1 seconds | 4-5x faster |\r\n| Clone 5 repos | Sequential | Concurrent | 3-4x faster |\r\n| Multiple API calls | Blocking | Non-blocking | 5-10x faster |\r\n\r\n## Security Notes\r\n\r\n- API tokens are sensitive - never commit them to version control\r\n- Use environment variables or config files with proper permissions\r\n- The CLI supports both token and username/password authentication\r\n- HTTPS is recommended for production Gogs servers\r\n\r\n## FAQ\r\n\r\n**Q: How do I change my API configuration without editing files manually?**\r\nA: Use the built-in config commands:\r\n```bash\r\ngogs config --set api.key YOUR_NEW_TOKEN\r\ngogs config --set api.url http://new-server.com/api/v1\r\ngogs config --show # Verify changes\r\n```\r\n\r\n**Q: What configuration keys are available?**\r\nA: Run `python gogs_cli.py config --list` to see all available keys with descriptions.\r\n\r\n**Q: Can I see my current API key?**\r\nA: Yes, but it will be masked for security: `python gogs_cli.py config --get api.key`\r\n\r\n**Q: How do I reset my configuration?**\r\nA: Delete the config file (`gogs_cli.ini`) or set new values with `--set` commands.\r\n\r\n## author\r\n[Hadi Cahyadi](mailto:cumulus13@gmail.com)\r\n \r\n\r\n[](https://www.buymeacoffee.com/cumulus13)\r\n\r\n[](https://ko-fi.com/cumulus13)\r\n\r\n[Support me on Patreon](https://www.patreon.com/cumulus13)\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A high-performance, async command-line interface for interacting with Gogs Git repositories",
"version": "0.17",
"project_urls": {
"Bug Tracker": "https://github.com/cumulus13/gogs_cli/issues",
"Documentation": "https://github.com/cumulus13/gogs_cli#readme",
"Homepage": "https://github.com/cumulus13/gogs_cli",
"Source Code": "https://github.com/cumulus13/gogs_cli"
},
"split_keywords": [
"gogs",
" gitea",
" git",
" cli",
" async",
" repository",
" api",
" command-line",
" version-control"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f5ddc58d5cc36cad0d853fbce86de64bac9d0c8b5fd424e107ed96052e888242",
"md5": "acd47ae3dfde6e61ff17e88493bbfba5",
"sha256": "0d65d2721ba69795a1e12e53c874bd81c8d90266c97b1809e2eeece847307bc8"
},
"downloads": -1,
"filename": "gogs_cli-0.17-py3-none-any.whl",
"has_sig": false,
"md5_digest": "acd47ae3dfde6e61ff17e88493bbfba5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 14441,
"upload_time": "2025-09-20T09:35:53",
"upload_time_iso_8601": "2025-09-20T09:35:53.792832Z",
"url": "https://files.pythonhosted.org/packages/f5/dd/c58d5cc36cad0d853fbce86de64bac9d0c8b5fd424e107ed96052e888242/gogs_cli-0.17-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9482712de4fc31ca9aa0c3974c010e14ca5d8596969a6e90a7b6474a2275e48e",
"md5": "bc86bc7123aa1f14111180b27b4b2371",
"sha256": "1baf4a30d2f4d84364f0aa33aec0c76e5730dbd8e2b923cacd9ddf624450ae9f"
},
"downloads": -1,
"filename": "gogs_cli-0.17.tar.gz",
"has_sig": false,
"md5_digest": "bc86bc7123aa1f14111180b27b4b2371",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 21183,
"upload_time": "2025-09-20T09:35:56",
"upload_time_iso_8601": "2025-09-20T09:35:56.757105Z",
"url": "https://files.pythonhosted.org/packages/94/82/712de4fc31ca9aa0c3974c010e14ca5d8596969a6e90a7b6474a2275e48e/gogs_cli-0.17.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-20 09:35:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cumulus13",
"github_project": "gogs_cli",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "aiohttp",
"specs": [
[
">=",
"3.8.0"
]
]
},
{
"name": "rich",
"specs": [
[
">=",
"13.0.0"
]
]
},
{
"name": "rich-argparse",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "configset",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "clipboard",
"specs": [
[
">=",
"0.0.4"
]
]
}
],
"lcname": "gogs-cli"
}
JSON
