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:

Clockify API Setup
- API key (from app.clockify.me/manage-api-keys)
- Workspace selection
- User validation
Jira Integration (Optional)
- Jira URL (https://company.atlassian.net)
- Email address
- API token (from Atlassian API tokens)
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`
`pause`	Pause the running timer (stop + remember)
`resume`	Resume a paused timer
`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`	List resources as JSON (agents/scripts)
`list-tasks`	List tasks from projects (table)	`tasks`, `ls`
`map`	Map a Jira project key to a Clockify project
`reports`	Generate detailed reports	`report`
`status`	Show current status and config	`info`

🤖 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

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

mi-lopez / clockify-cli-wizard

Maintainers

Package info

Statistics

Security