gtime 0.4.0

Global Time Utility (gtime) - A modern, colorful Python CLI utility for global time zone lookup, comparison, and management. It supports fuzzy search, favorites, city comparison, meeting time conversion, and a live/watch mode

🌍 Global Time Utility (gtime)

A modern, colorful Python CLI utility for global time zone lookup, comparison, and management

Sick of Googling time zones every day?! Stop wasting time figuring out the time. 🕐 gtime makes it effortless to work across time zones with fuzzy search, favorites, real-time updates, and beautiful terminal output.

⭐ Love this project? Give it a star!

If gtime helps you manage time zones more efficiently, please consider giving it a ⭐ on GitHub! Your support helps us improve and motivates continued development.

⭐ Star this project • 🐛 Report issues • 💡 Request features

---

🎯 Why gtime?

• ⚡ Lightning fast - Optimized for large city databases
• 🔍 Smart search - Fuzzy matching finds cities even with typos
• ❤️ Favorites - Save your most-used cities for quick access
• 🔄 Live updates - Watch mode for real-time monitoring
• 🎨 Beautiful output - Colorful, rich terminal interface
• 🤝 Meeting helper - Convert meeting times across all favorites with timezone support
• 🌐 Global team ready - Supports UTC, EST, PST, JST, CET and more timezones
• 📊 Compare easily - Side-by-side time comparisons

📦 Installation

With uv (recommended)

uv tool install gtime

In a virtual environment

uv venv
source .venv/bin/activate
uv pip install gtime

From source

git clone https://github.com/savitojs/gtime.git
cd gtime
uv sync
uv run gtime --help

🚀 Quick Start

# Get the time in any city
gtime London

# Add cities to your favorites
gtime add Tokyo Singapore "New York"

# See all your favorite cities at once
gtime list

# Compare times across multiple cities
gtime compare London Tokyo Sydney

# Find the perfect meeting time
gtime meeting at "2:00 PM"

# Live monitoring mode
gtime watch

🎬 Demo

See gtime in action:

Note: Some command output may appear broken in the demo, but it works perfectly in real terminal usage

🎯 Features

🏙️ City Lookup

• Fuzzy search: gtime toky finds Tokyo
• Suggestions: Get helpful suggestions for misspelled cities
• Instant results: Lightning-fast lookups even with huge databases

⭐ Favorites Management

gtime add "Los Angeles" Berlin Mumbai    # Add multiple cities
gtime remove Tokyo                       # Remove a city
gtime list                              # View all favorites
gtime clear                             # Clear all favorites

🔍 Multi-City Comparison

gtime compare London Tokyo "New York"   # Compare specific cities
gtime compare                           # Compare all favorites

📅 Meeting Time Conversion

gtime meeting at "10:00 AM"            # Convert across favorites
gtime meeting at "15:30"               # 24-hour format supported
gtime meeting at "3 PM UTC"            # Shows "Coordinated Universal Time (UTC)"
gtime meeting at "9:00 AM EST"         # Shows "Eastern Standard Time (EST)"

👀 Live Watch Mode

gtime watch                             # Monitor all favorites
gtime watch London Tokyo                # Watch specific cities

🌐 Timezone Support

When you specify a timezone, gtime shows the full timezone name for clarity:

gtime meeting at "10:00 AM JST"         # Shows: "Japan Standard Time (JST)"
gtime meeting at "3 PM UTC"             # Shows: "Coordinated Universal Time (UTC)"
gtime meeting at "2:00 PM EST"          # Shows: "Eastern Standard Time (EST)"

📚 Usage Examples

Basic Usage

# Simple city lookup
gtime Paris
gtime "San Francisco"
gtime mumbai                    # Case insensitive

# With fuzzy matching
gtime pairs                     # Finds Paris
gtime newyork                   # Finds New York

Managing Favorites

# Build your favorite cities list
gtime add London Tokyo "San Francisco" Berlin
gtime add Mumbai                # Add one more
gtime list                      # See your collection

# Remove cities you no longer need
gtime remove Berlin
gtime clear                     # Start fresh

Advanced Features

# Compare multiple cities
gtime compare London Tokyo Sydney Mumbai

# Perfect for planning meetings
gtime meeting at "9:00 AM"      # What time is 9 AM across favorites?
gtime meeting at "14:30"        # 24-hour format supported
gtime meeting at "3 PM UTC"     # Timezone support for global teams

# Real-time monitoring
gtime watch                     # Live updates every second

🛠️ Development

Using uv (recommended)

uv venv
source .venv/bin/activate
uv sync --extra dev

# Optional: update lockfile
uv lock

# Run tests
uv run pytest

Running Tests

uv run pytest tests/

# Run performance tests
uv run python tests/perf/profile_lookup.py

Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Run tests: pytest
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to the branch: git push origin feature/amazing-feature
7. Open a Pull Request

🚀 GitHub Actions

This project includes automated workflows:

• 🧪 Tests: Runs on every push/PR across Python 3.8-3.12
• 📦 Publish: Automatically publishes to PyPI upon new GitHub release

🤝 Support

• 📖 Documentation: Check out our Wiki
• 🐛 Bug Reports: Create an issue
• 💡 Feature Requests: Suggest new features
• 💬 Discussions: Join the conversation

📄 License

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

---

🌟 Show Your Support

If gtime makes your life easier, please consider:

• ⭐ Starring this repository
• 🐦 Sharing it on social media
• 📝 Writing a review
• 🤝 Contributing to the project

Made with ❤️ for developers working across time zones

---

Happy time zone management! 🌍