Drudge CLI - Professional Work Time Tracking Tool

A comprehensive, professionally architected command-line tool for tracking work time on tasks with organized daily logs. Built with modern Python package structure, Typer CLI framework, Rich formatting, type hints, dataclasses, and enterprise-level architectural patterns.

🎯 Version 2.2.0 - Google Sheets Sync & Project Support: Enhanced --time option with date support, project/category tagging, and Google Sheets sync with haunts-compatible format.

✨ Key Features

🚀 Task Management

• Smart task tracking: Start, end, pause, and resume tasks
• Anonymous work sessions: Start working without naming the task
• Single-task mode: Auto-ends previous tasks (default behavior)
• Parallel mode: Work on multiple tasks simultaneously with --parallel flag
• Custom timestamps: Backdate entries with --time HH:MM or --time "YYYY-MM-DD HH:MM"
• Project tagging: Organize tasks by project with --project "Project Name"
• Pause/Resume: Interrupt work and continue later

📊 Reporting & Views

• Unified list command: See active, paused, and completed tasks at a glance
• Recent tasks: View detailed recent work history
• Daily summaries: Time totals and task breakdown by day
• Flexible filtering: By date, task name, project, or custom limits

� NEW in v2.2.0: Google Sheets Sync

• Haunts-compatible format: Sync to Google Sheets with haunts column layout
• Multiple auth methods: Haunts OAuth, OAuth token, or Service Account
• Auto-sync option: Sync automatically after ending tasks with --sync
• Selective sync: Daily, monthly, or by specific date

🏷️ NEW in v2.2.0: Project Support

• Tag tasks: drudge start "Fix bug" --project "Backend API"
• Filter by project: drudge list --project "Backend"
• Project display: Projects shown in task listings

⏰ NEW in v2.2.0: Enhanced Time Option

• Date support: --time "2025-12-10 14:30" for any date
• Backward compatible: --time 14:30 still works (uses today)

🗑️ Clean Command

• Clean by date: Remove all entries for a specific date
• Clean by task: Remove all entries for a task across all dates
• Selective cleaning: Clean task entries for specific date only
• Clean all: Reset entire worklog with confirmation
• Automatic backups: Safety first - backups before deletion

🏁 End Command

• Default: drudge end - Ends only active tasks
• --all flag: drudge end --all - Ends active AND paused tasks
• --sync flag: drudge end --sync - End and sync to Google Sheets

❓ Help System

• Native Typer --help integration
• Command-specific help: drudge COMMAND --help
• Consistent with standard CLI conventions

📦 Installation

Prerequisites

• Python 3.8+ (tested with Python 3.10 and 3.13)
• Required packages: typer[all] and rich

Install from PyPI

pip install drudge-cli

Install from Source

# Clone the repository
git clone https://github.com/Trik16/drudge.git
cd drudge

# Install in development mode
pip install -e .

Setup Shell Alias

# Run the setup script
./setup_drudge_alias.sh

# Or add manually to your shell config
echo 'alias drudge="python3 -m src.worklog"' >> ~/.zshrc
source ~/.zshrc

Enable Shell Autocompletion

Drudge supports tab completion for commands and options in Bash, Zsh, Fish, and PowerShell.

Automatic Installation (Recommended)

# Install completion for your current shell
drudge --install-completion

# Restart your shell or source your config
source ~/.zshrc  # for Zsh
source ~/.bashrc # for Bash

Manual Installation

Zsh:

# Generate completion script
drudge --show-completion zsh > ~/.drudge-completion.zsh

# Add to ~/.zshrc
echo 'source ~/.drudge-completion.zsh' >> ~/.zshrc
source ~/.zshrc

Bash:

# Generate completion script
drudge --show-completion bash > ~/.drudge-completion.bash

# Add to ~/.bashrc
echo 'source ~/.drudge-completion.bash' >> ~/.bashrc
source ~/.bashrc

Fish:

# Generate completion script
drudge --show-completion fish > ~/.config/fish/completions/drudge.fish

PowerShell:

# Generate completion script
drudge --show-completion powershell | Out-File -FilePath $PROFILE

Verify Installation

# Try typing and press TAB
drudge <TAB>        # Shows all available commands
drudge start <TAB>  # Shows task name suggestions
drudge end --<TAB>  # Shows available flags

🚀 Quick Start

# Start your workday
drudge start "Morning emails"

# Check what's active
drudge list

# End the task
drudge end "Morning emails"

# View today's summary
drudge daily

⚙️ Configuration

Config File

Drudge can be configured using a YAML file located at ~/.worklog/config.yaml. This file is automatically created from a template on first run.

Configuration File

The config file is created automatically when you first run any drudge command. You can view and manage it with:

# Show configuration summary
drudge config

# Show full config.yaml content
drudge config --show

# Edit configuration file directly
nano ~/.worklog/config.yaml
# or
code ~/.worklog/config.yaml

Configuration Structure

# Basic settings
worklog_directory: "~/.worklog"
sheet_document_id: "1A2B3C4D5E6F7G8H9I0J"
timezone: "Europe/Rome"

# Project categorization
projects:
  - Backend
  - Frontend
  - DevOps
  - Research

# Google Sheets sync (haunts-compatible format)
google_sheets:
  enabled: true
  auto_sync: false
  round_hours: 0.5      # Round to 15min (0.25), 30min (0.5), hour (1.0)

# Optional: Haunts integration (for Calendar sync)
haunts:
  enabled: false
  config_path: "~/.haunts"

Configuration Parameters

Basic Settings

Parameter	Type	Default	Description
worklog_directory	string	~/.worklog	Directory for worklog data
sheet_document_id	string	-	Google Sheets document ID (shared)
timezone	string	system	Timezone (from haunts or system)

Projects

Define project categories to organize your work entries. Projects can be assigned when starting tasks:

# Start a task with project categorization
drudge start "Implement login feature" --project Backend
drudge start "Fix CSS layout" --project Frontend

Google Sheets Integration

Parameter	Type	Default	Description
enabled	boolean	false	Enable/disable Google Sheets sync
auto_sync	boolean	false	Auto-sync on task end
round_hours	float	0.5	Rounding: 0.25 (15min), 0.5 (30min), 1.0 (hour)

Note: Decimal places are automatic: 0.25→2 decimals, 0.5→1 decimal, 1.0→0 decimals

Haunts Integration (Optional)

Parameter	Type	Default	Description
enabled	boolean	false	Whether you use haunts for Calendar sync
config_path	string	~/.haunts	Path to haunts config (reference only)

Note: Haunts is optional. If enabled, it reads the Google Sheet and creates Calendar events independently.

Hours Formatting Examples

The round_hours setting controls how task durations are rounded. Decimal places are automatic:

# Example 1: Round to 30 minutes (default)
round_hours: 0.5
# 2h 12m → 2,0 hours (2h 00m) - 1 decimal
# 2h 38m → 2,5 hours (2h 30m) - 1 decimal
# 2h 52m → 3,0 hours (3h 00m) - 1 decimal

# Example 2: Round to 15 minutes  
round_hours: 0.25
# 2h 12m → 2,25 hours (2h 15m) - 2 decimals
# 2h 38m → 2,50 hours (2h 30m) - 2 decimals
# 2h 52m → 2,75 hours (2h 45m) - 2 decimals

# Example 3: Round to full hour
round_hours: 1.0
# 2h 12m → 2 hours - 0 decimals
# 2h 38m → 3 hours - 0 decimals

Note: Uses comma (,) as decimal separator for European format.

Project-Based Workflow

Once configured, you can organize your work by project:

# Start tasks with project categorization
drudge start "API refactoring" --project Backend
drudge start "Button animations" --project Frontend

# Tasks are tracked with their projects
drudge list
# Output shows: "API refactoring [Backend]" and "Button animations [Frontend]"

# End tasks (project info is preserved)
drudge end "API refactoring"
# Output: 🏁 Completed 'API refactoring' [Backend] (2h 30m)

Haunts Sync

When enabled, drudge can sync completed tasks to Google Calendar via Haunts:

# Manual sync (when sync_mode: manual)
drudge daily --sync

# View what will be synced
drudge daily
# Shows completed tasks with their projects and durations

Note: Haunts integration requires the Haunts package to be installed and configured.

📖 Command Reference

Command	Description	Example
Task Management
drudge start "Name"	🚀 Start a new task (auto-ends previous)	drudge start "Bug fix #123"
drudge start	🚀 Start anonymous work session	drudge start
drudge start --parallel	🚀 Start without ending active tasks	drudge start "Review" --parallel
drudge start --project NAME	🚀 Start with project categorization	drudge start "API work" --project Backend
drudge start --time HH:MM	🚀 Start at specific time	drudge start "Meeting" --time 09:30
drudge end "Name"	🏁 End a specific task	drudge end "Bug fix #123"
drudge end	🏁 End ALL active tasks (paused remain)	drudge end
drudge end --all	🏁 NEW End active AND paused tasks	drudge end --all
drudge end --time HH:MM	🏁 End at specific time	drudge end "Meeting" --time 17:30
drudge pause "Name"	⏸️ Pause an active task	drudge pause "Task"
drudge resume "Name"	▶️ Resume a paused task	drudge resume "Task"
Cleaning & Maintenance
drudge clean YYYY-MM-DD	🗑️ NEW Clean all entries for date	drudge clean 2025-10-03
drudge clean "Task"	🗑️ NEW Clean task (all dates)	drudge clean "Bug fix"
drudge clean "Task" --date	🗑️ NEW Clean task for specific date	drudge clean "Meeting" -d 2025-10-03
drudge clean --all	🗑️ NEW Clean ALL entries (confirm)	drudge clean --all
Viewing & Reporting
drudge list	📋 Show active, paused, completed	drudge list
drudge list --date YYYY-MM-DD	📋 List entries for date	drudge list --date 2025-10-03
drudge list --task "keyword"	📋 Filter by task name	drudge list --task "bug"
drudge list --limit N	📋 Limit results	drudge list --limit 10
drudge recent	📝 Recent tasks (full details)	drudge recent
drudge recent --limit N	📝 Show N recent tasks	drudge recent --limit 10
drudge daily	📅 Today's summary	drudge daily
drudge daily --date YYYY-MM-DD	📅 Specific date summary	drudge daily --date 2025-10-03
Help & Info
drudge --help	❓ IMPROVED Main help	drudge --help
drudge COMMAND --help	❓ IMPROVED Command help	drudge start --help
Configuration
drudge config	⚙️ Show config summary	drudge config
drudge config --show	⚙️ Display full config.yaml	drudge config --show
drudge version	📦 Show version	drudge version

💡 Usage Examples

Basic Task Tracking

# Start a task
$ drudge start "Fix bug #123"
🚀 Started 'Fix bug #123' at 2025-10-04 10:00:00

# End it
$ drudge end "Fix bug #123"
🏁 Completed 'Fix bug #123' at 2025-10-04 12:30:00 (Duration: 02:30:00)

Anonymous Work Session

# Don't know what you're working on yet?
$ drudge start
💡 Starting anonymous work session

# Name it later (converts anonymous → named)
$ drudge start "Research and planning"
✏️ Renamed anonymous work to 'Research and planning'

Parallel Tasks

# Work on multiple tasks simultaneously
$ drudge start "Backend API"
$ drudge start "Code review" --parallel  # Keeps Backend API running

$ drudge list
🔥 ACTIVE TASKS:
  • Backend API (Running: 01:00:00)
  • Code review (Running: 00:15:00)

# End specific task
$ drudge end "Code review"
🏁 Completed 'Code review' (Duration: 00:30:00)

Pause and Resume

# Working on a task
$ drudge start "Important project"

# Lunch break
$ drudge pause "Important project"
⏸️ Paused 'Important project'

# Back from lunch
$ drudge resume "Important project"
▶️ Resumed 'Important project'

# Finish up
$ drudge end "Important project"
🏁 Completed 'Important project' (Duration: 03:30:00)

Enhanced End Command (v2.1.0)

# Create test scenario
$ drudge start "Active Task"
$ drudge start "Another Task" --parallel
$ drudge pause "Active Task"

$ drudge list
🔥 ACTIVE TASKS:
  • Another Task (Running: 00:05:00)

⏸️  PAUSED TASKS:
  • Active Task

# End only active tasks (DEFAULT behavior)
$ drudge end
✅ Ended 1 task(s) successfully  # Only "Another Task" ended

$ drudge list
⏸️  PAUSED TASKS:
  • Active Task  # Paused task remains!

# End ALL tasks including paused (NEW --all flag)
$ drudge end --all
▶️ Resumed 'Active Task'
🏁 Completed 'Active Task'
✅ Ended 1 task(s) successfully

Clean Command (v2.1.0)

# Clean all entries for a specific date
$ drudge clean 2025-10-03
✅ Cleaned 15 entries for 2025-10-03
💾 Backup created for safety

# Clean all entries for a task (across all dates)
$ drudge clean "Bug fix #123"
✅ Cleaned 3 entries for task 'Bug fix #123'
💾 Backup created for safety

# Clean task entries for specific date only
$ drudge clean "Meeting" --date 2025-10-03
✅ Cleaned 1 entries for task 'Meeting' on 2025-10-03
💾 Backup created for safety

# Clean everything (with confirmation)
$ drudge clean --all
⚠️  This will clean ALL worklog entries!
Are you sure you want to continue? [y/N]: y
✅ Cleaned 50 entries and 10 daily files
💾 Backup created for safety

Custom Time Entry

# Forgot to track? Backdate it
$ drudge start "Morning standup" --time 09:00
🚀 Started 'Morning standup' at 2025-10-04 09:00:00

$ drudge end "Morning standup" --time 09:30
🏁 Completed 'Morning standup' (Duration: 00:30:00)

Daily Reporting

# View today's summary
$ drudge daily
📅 Daily Summary for 2025-10-04
📊 Total: 5 tasks, 7h 30m

  • Fix bug #123: 2h 30m
  • Code review: 1h 00m
  • Morning standup: 0h 30m
  • Documentation: 2h 00m
  • Backend API: 1h 30m

# View specific date
$ drudge daily --date 2025-10-03

Project-Based Workflow (v2.1.1+)

# Configure projects in ~/.worklog/config.yaml
# (file is auto-created on first run)
$ drudge config --show
# Edit to add your projects under 'projects:' section

# Start tasks with project categorization
$ drudge start "Implement login API" --project Backend
🚀 Started 'Implement login API' [Backend] at 2025-10-04 10:00:00

$ drudge start "Fix responsive design" --project Frontend --parallel
🚀 Started 'Fix responsive design' [Frontend] at 2025-10-04 10:30:00

# List shows projects
$ drudge list
🔥 ACTIVE TASKS:
  • Implement login API [Backend] (Running: 02:00:00)
  • Fix responsive design [Frontend] (Running: 01:30:00)

# End tasks (project info is preserved)
$ drudge end "Implement login API"
🏁 Completed 'Implement login API' [Backend] (Duration: 02:00:00)

$ drudge end "Fix responsive design"
🏁 Completed 'Fix responsive design' [Frontend] (Duration: 01:30:00)

# Daily summary shows projects
$ drudge daily
📅 Daily Summary for 2025-10-04
📊 Total: 2 tasks, 3h 30m

  • Implement login API [Backend]: 2h 00m
  • Fix responsive design [Frontend]: 1h 30m

# Sync to Google Calendar (with Haunts integration)
$ drudge daily --sync
✅ Synced 2 tasks to Google Calendar

📊 Google Sheets Integration

Drudge can sync your work tasks to Google Sheets in a haunts-compatible format. This allows you to:

• Keep a time-tracking spreadsheet
• Sync to Google Calendar (if using haunts)
• Share work reports with your team

Quick Setup

1. Create or use existing Google Sheet

2. Configure in ~/.worklog/config.yaml:

   # Add your Sheet Document ID (from URL)
   sheet_document_id: "1A2B3C4D5E6F7G8H9I0J"
   
   google_sheets:
     enabled: true
     auto_sync: false    # or true for automatic sync on 'drudge end'
     round_hours: 0.5    # 0.25=15min, 0.5=30min, 1.0=hour

3. Sync your tasks:

   drudge sync              # Sync all entries
   drudge sync --daily      # Sync today's entries
   drudge sync --monthly    # Sync current month
   drudge daily --sync      # Alias for --daily

Sheet Structure

1. Config Sheet (name: config)

• Maps project names to Calendar IDs (optional for drudge, required for haunts)

2. Monthly Sheets (names: January, February, March, etc.)

• Auto-created based on task dates
• Contains your task entries

Monthly Sheet Columns:

Column	Name	Description	Example
A	Date	Task date	04/10/2025
B	Start time	Task start time	09:30
C	Project	Project category	Backend
D	Activity	Task description	Implement login API
E	Details	Additional notes	Added JWT auth
F	Spent	Duration (decimal hours)	2,5
G	Event id	Calendar event ID (filled by haunts)	-
H	Link	Calendar event link (filled by haunts)	-
I	Action	Sync control (used by haunts)	-

Example Data

Task in drudge:

drudge start "Implement login API" --project Backend
# ... work for 2h 30m ...
drudge end "Implement login API"

Synced to Google Sheet (October tab):

| Date       | Start | Project | Activity             | Spent |
|------------|-------|---------|---------------------|-------|
| 04/10/2025 | 09:00 | Backend | Implement login API | 2,5   |

Hours Formatting

Configure how hours are formatted in the sheet:

google_sheets:
  hours_decimal: 1      # Decimal places (0, 1, or 2)
  round_hours: 0.25     # Round to 15min (0.25), 30min (0.5), or hour (1.0)

Examples:

• Task: 2h 47m
• hours_decimal: 1, round_hours: 0.25 → 2,75 (2h 45m)
• hours_decimal: 2, round_hours: 0.5 → 2,50 (2h 30m)
• hours_decimal: 0, round_hours: 1.0 → 3 (3h)

Haunts Integration (Optional)

If you use haunts for Calendar sync:

1. Drudge → Writes tasks to Google Sheet
2. Haunts → Reads sheet and creates Calendar events
3. Haunts → Fills Event id and Link columns

Without haunts:

• You still get a time-tracking spreadsheet
• No automatic calendar sync
• Perfect for manual reporting

Authentication Setup

To use Google Sheets sync, you need:

1. Google Cloud Project with Sheets API enabled
2. OAuth 2.0 credentials or service account
3. Credentials file at ~/.worklog/credentials.json

See Google Sheets API Quickstart for detailed setup.

Complete Documentation

For detailed sheet structure, column specifications, and setup guides, see:

• 📄 Google Sheets Structure Documentation

🏗️ Architecture

Package Structure

src/worklog/
├── __init__.py          # Package initialization
├── __main__.py          # Entry point
├── models.py            # Data models (TaskEntry, PausedTask, WorkLogData)
├── config.py            # Configuration management
├── validators.py        # Input validation
├── managers/            # Business logic
│   ├── worklog.py       # Core WorkLog class
│   ├── backup.py        # Backup management
│   └── daily_file.py    # Daily file operations
├── cli/                 # Command-line interface
│   └── commands.py      # Typer commands
└── utils/               # Utilities
    └── decorators.py    # Common decorators

Data Storage

~/.worklog/
├── worklog.json         # Complete task database (JSON)
├── worklog.log          # Application logs
├── 2025-10-01.txt      # Human-readable daily logs
├── 2025-10-02.txt
├── 2025-10-03.txt
└── daily/              # Backup directory
    ├── 2025-10-01.txt
    └── 2025-10-02.txt

Daily File Format

2025-10-04 09:00:00 Morning standup (00:30:00)
2025-10-04 10:00:00 Fix bug #123 (02:30:00)
2025-10-04 14:00:00 Backend API [ACTIVE]
2025-10-04 15:00:00 Code review [PAUSED]

🔄 Version History

Version 2.1.0 (Current - October 4, 2025)

New Features:

• ✨ Enhanced end command: --all flag to end both active and paused tasks
• ✨ Clean command: Erase worklog entries by date, task, or all (with backups)
• ✨ Improved help: Native Typer --help integration (removed custom help command)

Improvements:

• 🔧 End command: drudge end keeps paused tasks, drudge end --all ends everything
• 🛡️ Clean safety: Automatic backups, confirmation for --all, smart daily file rebuild
• 📚 All 47 test cases passing (100%)

Version 2.0.2

New Features:

• Anonymous work sessions
• Parallel task mode
• Optimized list command
• Enhanced recent command

Version 2.0.1

Major Refactoring:

• Complete architectural overhaul
• Typer CLI framework with Rich formatting
• Professional package structure
• 28 comprehensive test cases

Version 1.0

• Initial release with basic task tracking

🧪 Testing

Running Tests

# Run all tests
pytest tests/ -v

# Run specific test file
pytest tests/test_cli_integration.py -v

# Run specific test class
pytest tests/test_worklog_updated.py::TestNewFeatures -v

# Run tests in Docker (isolated environment)
docker build -f Dockerfile.test -t drudge-test .
docker run --rm drudge-test

Test Coverage

• 106 comprehensive test cases
  • 47 CLI integration tests
  • 20 Google Sheets sync tests
  • 39 core worklog tests
• 100% pass rate on Python 3.10-3.13
• Core features: Start, end, pause, resume
• New features: Anonymous tasks, parallel mode, clean command, Google Sheets sync
• Edge cases and error handling

🛠️ Development

Build Package

# Build distribution
python3.10 -m build

# Check distribution
twine check dist/*

Publish to PyPI

# Upload to PyPI
twine upload dist/*

📄 License

MIT License - See LICENSE file for details

🔗 Links

• GitHub: github.com/Trik16/drudge
• PyPI: pypi.org/project/drudge-cli
• Changelog: CHANGELOG.md
• Release Notes: docs/RELEASE_2.1.0.md

🙏 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

💬 Support

For issues, questions, or feature requests, please open an issue on GitHub.

---

Built with ❤️ using Python, Typer, and Rich

Version 2.1.1 - Enhanced CLI with native help, powerful clean command, and improved task management