mi-lopez / clockify-cli-wizard
A beautiful CLI wizard for time tracking with Clockify and Jira integration
Requires
- php: ^8.1
- guzzlehttp/guzzle: ^7.0
- league/csv: ^9.0
- nesbot/carbon: ^2.0|^3.0
- psr/log: ^3.0
- symfony/console: ^6.0|^7.0
- symfony/filesystem: ^6.0|^7.0
- symfony/process: ^6.0|^7.0
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.21
- phpstan/phpstan: ^1.10
- phpstan/phpstan-symfony: ^1.3
- phpunit/phpunit: ^10.0
- squizlabs/php_codesniffer: ^3.7
This package is auto-updated.
Last update: 2025-07-04 19:15:17 UTC
README
A beautiful, intelligent CLI wizard for seamless time tracking with Clockify and Jira integration.
Transform your time tracking workflow with smart automation, Git integration, and an intuitive command-line interface designed for developers.
✨ Features
🚀 Smart Time Tracking
- Auto-detection from Git branch names (extracts ticket IDs like
CAM-451
,PROJ-123
) - Interactive wizard with intelligent suggestions
- Multiple time formats support (
2h
,1h30m
,90m
,9:30am-11:30am
) - Real-time timer with start/stop functionality
🎯 Jira Integration
- Automatic ticket fetching with summary and project info
- Project mapping between Jira and Clockify
- Recent issues selection for quick logging
- Task auto-creation with formatted names
📊 Advanced Reporting
- Daily/Weekly summaries with detailed breakdowns
- Timeline views with gap detection
- Export capabilities (CSV, JSON)
- Progress tracking against weekly targets
- Project and task analytics
🌍 Timezone Intelligence
- Smart timezone handling (defaults to Chile/Santiago)
- Local time display with UTC API communication
- Working hours awareness
- International timezone support
🎨 Enhanced User Experience
- Beautiful CLI interface with colors and emojis
- Pagination and search for large project lists
- Progress indicators and status messages
- Configuration wizard with validation
- Error handling with helpful suggestions
📦 Installation
Via Composer (Recommended)
composer global require mi-lopez/clockify-cli-wizard
Manual Installation
git clone https://github.com/mi-lopez/clockify-cli-wizard.git
cd clockify-cli-wizard
composer install
chmod +x bin/clockify-wizard
Add to PATH (Global Access)
# Add to your ~/.bashrc or ~/.zshrc export PATH="$PATH:$HOME/.composer/vendor/bin" # Or create a symlink ln -s /path/to/clockify-cli-wizard/bin/clockify-wizard /usr/local/bin/clockify-wizard
⚙️ Configuration
Initial Setup
clockify-wizard configure
The wizard will guide you through:
-
Clockify API Setup
- API key (from clockify.me/user/settings)
- Workspace selection
- User validation
-
Jira Integration (Optional)
- Jira URL (
https://company.atlassian.net
) - Email address
- API token (from Atlassian API tokens)
- Jira URL (
-
General Settings
- Timezone configuration
- Default duration settings
- Auto-detection preferences
Environment Variables (Optional)
export CLOCKIFY_API_KEY="your-api-key" export CLOCKIFY_WORKSPACE_ID="workspace-id" export JIRA_URL="https://company.atlassian.net" export JIRA_EMAIL="your-email@company.com" export JIRA_TOKEN="your-jira-token"
🚀 Quick Start
Basic Time Logging
# Log 2 hours with auto-detection from Git branch clockify-wizard log 2h --auto # Interactive mode with wizard clockify-wizard log --interactive # Log specific time range clockify-wizard log --start 9:30am --end 11:30am --task CAM-451 # Quick log with description clockify-wizard log 1h30m --task PROJ-123 --description "Bug fixing"
Timer Management
# Start a timer clockify-wizard start CAM-451 # Stop active timer clockify-wizard stop # Check current status clockify-wizard status
Task Management
# Create task from Jira ticket clockify-wizard create-task CAM-451 # List all tasks clockify-wizard list-tasks # Filter tasks by project clockify-wizard list-tasks --project "My Project"
Reports and Analytics
# Today's summary clockify-wizard today --detailed # Weekly report clockify-wizard week --detailed --export week.csv # Custom reports clockify-wizard reports --period month --group-by project --export monthly.csv
📋 Available Commands
Command | Description | Aliases |
---|---|---|
configure |
Setup wizard for Clockify and Jira | config , setup |
start |
Start a timer for time tracking | begin |
stop |
Stop the active timer | end |
log |
Log time with smart detection | l |
today |
Show today's time summary | td |
week |
Show weekly time summary | wk |
create-task |
Create task from Jira ticket | task |
list-tasks |
List tasks from projects | tasks , ls |
reports |
Generate detailed reports | report |
status |
Show current status and config | info |
🎯 Advanced Usage
Git Integration
The tool automatically detects ticket IDs from Git branch names:
# Branch: feature/CAM-451-user-authentication git checkout feature/CAM-451-user-authentication clockify-wizard log 2h --auto # Automatically detects CAM-451
Supported patterns:
feature/CAM-451-description
bugfix/PROJ-123
CAM-451-hotfix
TICKET-456
Project Mapping
Automatically map Jira projects to Clockify projects:
# First time mapping clockify-wizard log 1h --task CAM-451 # Wizard will ask to map Jira project "CAM" to a Clockify project # Future CAM tickets will use the same mapping automatically
Time Format Examples
# Duration formats clockify-wizard log 2h # 2 hours clockify-wizard log 1h30m # 1 hour 30 minutes clockify-wizard log 90m # 90 minutes clockify-wizard log 1.5h # 1.5 hours # Time range formats clockify-wizard log --start 9am --end 11:30am clockify-wizard log --start 14:30 --end 16:00 clockify-wizard log 2h --end-now # 2 hours ending now
Smart Suggestions
The interactive mode provides intelligent suggestions:
clockify-wizard log --interactive
- Recent Jira tickets for quick selection
- Time suggestions based on current time and common work hours
- Project suggestions based on Git context and history
📊 Reports and Analytics
Daily Summary
clockify-wizard today --detailed
Shows:
- Total time tracked
- Project breakdown with percentages
- Timeline view with gaps
- Active timer status
Weekly Analysis
clockify-wizard week --detailed --export week.csv
Features:
- Daily breakdown for the entire week
- Target progress (40-hour work week)
- Project distribution
- Export capabilities
Custom Reports
# Monthly project report clockify-wizard reports --period month --group-by project # Task-level analysis clockify-wizard reports --group-by task --start 2024-01-01 --end 2024-01-31 # Export options clockify-wizard reports --format csv --export report.csv clockify-wizard reports --format json --export report.json
🔧 Configuration Details
Config File Location
~/.clockify-cli-config.json
Sample Configuration
{ "version": "1.0", "timezone": "America/Santiago", "clockify": { "api_key": "your-api-key", "workspace_id": "workspace-id", "user_id": "user-id" }, "jira": { "url": "https://company.atlassian.net", "email": "your-email@company.com", "token": "your-jira-token" }, "project_mappings": { "CAM": "clockify-project-id", "PROJ": "another-clockify-project-id" }, "timer": { "default_duration": "1h", "round_to_minutes": 15, "auto_detect_branch": true } }
Reset Configuration
clockify-wizard configure --reset
🌍 Timezone Support
The tool intelligently handles timezones:
- Default:
America/Santiago
(Chile) - Auto-detection from system settings
- Manual configuration during setup
- UTC conversion for API communication
- Local display for user interface
Supported Timezones
America/Santiago
- Chile ContinentalPacific/Easter
- Easter IslandUTC
- Coordinated Universal TimeAmerica/New_York
- Eastern TimeAmerica/Los_Angeles
- Pacific TimeEurope/Madrid
- Central European Time
🛠️ Development
Requirements
- PHP ^8.1
- Composer
- Git (for auto-detection features)
Local Development
git clone https://github.com/mi-lopez/clockify-cli-wizard.git cd clockify-cli-wizard composer install # Run tests composer test # Code style check composer cs-check # Fix code style composer cs-fix # Static analysis composer phpstan
Project Structure
src/
├── Client/ # API clients (Clockify, Jira)
├── Commands/ # Console commands
├── Config/ # Configuration management
├── Console/ # Application setup
└── Helper/ # Utility classes
bin/
└── clockify-wizard # Executable script
tests/ # PHPUnit tests
🤝 Contributing
We welcome contributions! Please read our Contributing Guide for details.
Development Workflow
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature
) - Make your changes
- Add tests for new functionality
- Run the test suite (
composer test
) - Commit your changes (
git commit -m 'Add amazing feature'
) - Push to the branch (
git push origin feature/amazing-feature
) - Open a Pull Request
Reporting Issues
Please use the GitHub Issues page to report bugs or request features.
📝 Changelog
See CHANGELOG.md for version history and updates.
🔒 Security
If you discover any security-related issues, please email miguel.lopezt86@gmail.com instead of using the issue tracker.
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🙏 Acknowledgments
- Clockify for the excellent time tracking API
- Atlassian for the Jira API
- Symfony Console for the CLI framework
- Carbon for date/time manipulation
- All contributors and users of this project
💬 Support
- 📖 Documentation: This README and inline help (
clockify-wizard --help
) - 🐛 Bug Reports: GitHub Issues
- 💡 Feature Requests: GitHub Issues
- 📧 Email: miguel.lopezt86@gmail.com
Made with ❤️ for developers who value efficient time tracking
Features • Installation • Quick Start • Advanced Usage • Development