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 — fully scriptable with a non-interactive JSON mode for AI agents.

✨ Features

🤖 Automation & AI Agents

• Non-interactive mode — every agent-facing command runs without prompts
• JSON output (--json) for scripts and AI agents to parse
• --dry-run to preview writes without billing time
• Discovery (list) of projects/tasks/tags/workspaces/current as JSON
• Jira → Clockify task mirroring for unattended, billable time tracking

🚀 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:

1. Clockify API Setup

   • API key (from app.clockify.me/manage-api-keys)
   • Workspace selection
   • User validation

2. Jira Integration (Optional)

   • Jira URL (https://company.atlassian.net)
   • Email address
   • API token (from Atlassian API tokens)

3. 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

🤖 Non-interactive / AI agent mode

Every command an automation or AI agent needs can run without prompts and emit JSON, so the same Jira ⇄ Clockify workflow a human uses can be driven end-to-end by a script or agent.

How it activates:

• Pass --json (recommended) — suppresses banners/prompts and prints a single JSON object to stdout. Errors are printed as {"error": "..."} with a non-zero exit code.
• Or run under --no-interaction (-n) — same non-interactive behavior with a minimal id on stdout.
• --dry-run (on create-task, start, log) shows what would be written without touching Clockify — a safety net against double-billing.

In non-interactive mode there are no prompts, so the Clockify project must be resolvable from a --project flag or a saved Jira→Clockify mapping (see Project Mapping). Otherwise the command fails with a clear message instead of hanging.

Discovery (list)

clockify-wizard list                         # available resources
clockify-wizard list projects                # [{id,name,clientName,archived}]
clockify-wizard list tasks --project "API"   # [{id,name,status,projectId}]
clockify-wizard list tags                    # [{id,name}]
clockify-wizard list workspaces              # [{id,name}]
clockify-wizard list current                 # running timer (or {"running":false})

One-time mapping (map)

So unattended create-task/log/start can resolve the project automatically:

clockify-wizard map CAM "My Clockify Project"   # persist CAM → project
clockify-wizard map                              # list current mappings

Two billing flows for agents

Both are supported — pick per situation:

# 1) Measured duration (recommended for agents): the agent measures how long the
#    task took and logs that explicit duration. No dangling timer.
clockify-wizard log 1h30m --task CAM-451 --tags "ai-agent" --json

# 2) Live timer (real wall-clock): start when work begins, stop when done.
clockify-wizard start CAM-451 --tags "ai-agent" --json
# ... work ...
clockify-wizard stop --json
clockify-wizard pause --json     # Clockify has no native pause: stop + remember
clockify-wizard resume --json    # restart the paused timer

--tags accepts a comma-separated list of labels and creates any that don't exist yet.

Combined Jira → Clockify recipe

The PM/agent creates the Jira ticket, then mirrors it into Clockify so time can be billed against it:

# 1) Create the Jira ticket (jira-cli-wizard, also non-interactive)
KEY=$(jira-wizard create --project CAM --type Task --summary "New endpoint")

# 2) Mirror it as a Clockify task (idempotent: returns existing if already there).
#    You already know the summary and project from step 1, so skip the Jira lookup:
clockify-wizard create-task "$KEY" --project "My Project" \
  --summary "New endpoint" --no-jira --json     # {"id":...,"existed":false,...}

# 3) Register billable time against it
clockify-wizard log 2h --task "$KEY" --json

--summary / --no-jira: by default create-task fetches the summary from Jira to build the task name "KEY summary". When you already have the summary (e.g. straight from the jira-wizard create step), pass --summary "<text>" to build the name locally and --no-jira to make zero Jira calls. This also matters when one Jira project maps to several Clockify projects (e.g. routed by epic): there is no 1-to-1 mapping that fits, so pass --project explicitly per ticket and keep the routing rule in your own runbook/skill.

🎯 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 Continental
• Pacific/Easter - Easter Island
• UTC - Coordinated Universal Time
• America/New_York - Eastern Time
• America/Los_Angeles - Pacific Time
• Europe/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
└── Service/         # Prompt-free resolution (TaskResolver)

bin/
└── clockify-wizard  # Executable script

tests/               # PHPUnit tests

🤝 Contributing

We welcome contributions! Please read our Contributing Guide for details.

Development Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Run the test suite (composer test)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. 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