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

Create or use existing Google Sheet

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

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:

Drudge → Writes tasks to Google Sheet
Haunts → Reads sheet and creates Calendar events
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:

Google Cloud Project with Sheets API enabled
OAuth 2.0 credentials or service account
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

Name		Name	Last commit message	Last commit date
Latest commit History 20 Commits
.github/workflows		.github/workflows
OLD_VERSION		OLD_VERSION
dev-env		dev-env
docs		docs
src/worklog		src/worklog
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
ToDo.md		ToDo.md
config.yaml.example		config.yaml.example
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
setup.py		setup.py
setup_alias.sh		setup_alias.sh
setup_drudge_alias.sh		setup_drudge_alias.sh

License

Trik16/drudge

Folders and files

Latest commit

History

Repository files navigation

Drudge CLI - Professional Work Time Tracking Tool

✨ Key Features

🚀 Task Management

📊 Reporting & Views

� NEW in v2.2.0: Google Sheets Sync

🏷️ NEW in v2.2.0: Project Support

⏰ NEW in v2.2.0: Enhanced Time Option

🗑️ Clean Command

🏁 End Command

❓ Help System

📦 Installation

Prerequisites

Install from PyPI

Install from Source

Setup Shell Alias

Enable Shell Autocompletion

Automatic Installation (Recommended)

Manual Installation

Verify Installation

🚀 Quick Start

⚙️ Configuration

Config File

Configuration File

Configuration Structure

Configuration Parameters

Basic Settings

Projects

Google Sheets Integration

Haunts Integration (Optional)

Hours Formatting Examples

Project-Based Workflow

Haunts Sync

📖 Command Reference

💡 Usage Examples

Basic Task Tracking

Anonymous Work Session

Parallel Tasks

Pause and Resume

Enhanced End Command (v2.1.0)

Clean Command (v2.1.0)

Custom Time Entry

Daily Reporting

Project-Based Workflow (v2.1.1+)

📊 Google Sheets Integration

Quick Setup

Sheet Structure

Example Data

Hours Formatting

Haunts Integration (Optional)

Authentication Setup

Complete Documentation

🏗️ Architecture

Package Structure

Data Storage

Daily File Format

🔄 Version History

Version 2.1.0 (Current - October 4, 2025)

Version 2.0.2

Version 2.0.1

Version 1.0

🧪 Testing

Running Tests

Test Coverage

🛠️ Development

Build Package

Publish to PyPI

📄 License

🔗 Links

🙏 Contributing

💬 Support

About

Topics

Resources

License

Packages