Toggl TimeGuru

A powerful CLI tool for managing and analyzing Toggl Track time entries, built with Rust.

Features

• Time tracking from command line - start and stop time entries directly
• Sync time entries from Toggl Track to local SQLite database
• Interactive TUI for browsing time entries with vim-style navigation
• Project assignment directly from TUI with search, usage-based sorting, and batch operations
• Time entry editing in TUI for updating descriptions with batch support
• Group entries by description or by description within each day
• Filter entries by date range, project, and tag from CLI and TUI
• Summary reports with daily, weekly, monthly, project, billable, and rounding options
• CSV export with grouping options for external reporting
• Duration rounding (rounds up to next interval) for easy time reporting
• Multi-account support with automatic account detection and switching
• Data management CLI commands for cleaning database and config
• Offline support via local caching
• Fast and efficient native Rust performance

Installation

From Source

cargo build --release
sudo cp target/release/toggl-timeguru /usr/local/bin/

Quick Start

1. Get your Toggl API token from Toggl Track Profile Settings

2. Configure the application:

toggl-timeguru config --set-token YOUR_API_TOKEN

3. Sync your time entries:

toggl-timeguru sync

4. Launch the interactive TUI:

toggl-timeguru tui

Usage

Commands

config - Configure the application

# Set API token
toggl-timeguru config --set-token YOUR_TOKEN

# Set default date range (in days)
toggl-timeguru config --set-date-range 7

# Set duration rounding (in minutes, rounds UP to next interval)
# Example: 15 rounds to quarter hours (0.25h, 0.5h, 0.75h, 1.0h, etc.)
toggl-timeguru config --set-round-minutes 15

# Sort the TUI project selector by name or recent usage
toggl-timeguru config --set-project-sort usage

# Show current configuration
toggl-timeguru config --show

sync - Sync time entries from Toggl

# Sync last 90 days (default)
toggl-timeguru sync

# Sync specific date range
toggl-timeguru sync --start 2025-01-01 --end 2025-01-31

list - List time entries

# List entries for the last 7 days (default)
toggl-timeguru list

# List with grouping by description
toggl-timeguru list --group

# Filter by project ID
toggl-timeguru list --project 12345

# Filter by tag
toggl-timeguru list --tag "client-work"

# Use offline/cached data
toggl-timeguru list --offline

# Custom date range
toggl-timeguru list --start 2025-01-01 --end 2025-01-31

report - Generate summary reports

# Daily report for the default date range
toggl-timeguru report

# Weekly or monthly summaries
toggl-timeguru report --period weekly
toggl-timeguru report --period monthly

# Filter a report by project ID
toggl-timeguru report --project 12345

# Use cached entries and round output to quarter hours
toggl-timeguru report --offline --round --round-minutes 15

# Choose whether rounding is applied to totals or each entry before aggregation
toggl-timeguru report --round --round-mode entry

tui - Interactive terminal UI

# Launch TUI with default date range
toggl-timeguru tui

# Launch TUI with custom date range
toggl-timeguru tui --start 2025-01-01 --end 2025-01-31

TUI Keyboard Shortcuts:

• ↑/k - Move up
• ↓/j - Move down
• PageUp/PageDown - Jump by page
• Home/End - Jump to first/last entry
• g - Toggle grouping by description
• d - Toggle day-based grouping (groups by description within each day)
• s - Toggle date sorting (ascending/descending)
• r - Toggle rounding on/off (default: ON in grouped view)
• f - Open or close the filter panel for billable, project, and tag filters
• c - Clear active filters when filters are applied
• p - Open project selector to assign project (works on individual or grouped entries)
• e - Edit description (works on individual or grouped entries, batch edit supported)
• y - Copy selected entry description to clipboard
• q/Esc - Quit

export - Export time entries to CSV

# Export entries to CSV (individual entries)
toggl-timeguru export --start 2025-01-01 --end 2025-01-31 --output report.csv

# Export with grouping by description
toggl-timeguru export --output report.csv --group

# Export with day-based grouping (groups by description within each day)
toggl-timeguru export --output report.csv --group-by-day

# Include metadata header (date range, user email, entry count)
toggl-timeguru export --output report.csv --include-metadata

clean - Delete application data

# Delete all data (database + config)
toggl-timeguru clean --all

# Delete only database (keeps config)
toggl-timeguru clean --data

# Delete only configuration (keeps database)
toggl-timeguru clean --config

# Skip confirmation prompt (useful for automation)
toggl-timeguru clean --all --confirm

track - Start and stop time tracking

# Start a new time entry with description
toggl-timeguru track start --message "Working on feature X"

# Start a new time entry without description
toggl-timeguru track start

# Stop the currently running time entry
toggl-timeguru track stop

Note: The track command works directly with the Toggl API and requires an active internet connection.

API Optimization and Rate Limits

Toggl TimeGuru uses Toggl Track's bulk update endpoint for grouped project assignment and description edits. Bulk updates send up to 100 time entries per request, which keeps batch edits usable on lower Toggl API quotas and avoids the old one-request-per-entry behavior.

The app tracks Toggl quota headers when the API returns them:

• X-Toggl-Quota-Remaining - requests left in the current quota window
• X-Toggl-Quota-Resets-In - seconds until the quota window resets

When quota is low, the TUI shows warnings before batch edits and displays the latest known API quota in the footer after API responses include quota headers. When quota is exhausted, requests wait for the reset window where possible and surface a clear status or error message instead of repeatedly retrying immediately.

Global Options

# Use custom API token for single command
toggl-timeguru --api-token TOKEN sync

# Enable verbose logging
toggl-timeguru -v tui

Configuration

Configuration is stored in platform-specific locations:

• Linux: ~/.config/toggl-timeguru/config.toml
• macOS: ~/Library/Application Support/toggl-timeguru/config.toml
• Windows: %APPDATA%\toggl-timeguru\config.toml

The SQLite database is stored in:

• Linux: ~/.local/share/toggl-timeguru/timeguru.db
• macOS: ~/Library/Application Support/toggl-timeguru/timeguru.db
• Windows: %APPDATA%\toggl-timeguru\timeguru.db

Troubleshooting

Deleting Application Data

To manually delete the application database (useful when switching Toggl accounts):

macOS:

rm -rf ~/Library/Application\ Support/toggl-timeguru/

Linux:

rm -rf ~/.local/share/toggl-timeguru/

Windows (PowerShell):

Remove-Item -Recurse -Force "$env:APPDATA\toggl-timeguru"

Note: To also delete the configuration file, remove the config directory:

• macOS: rm -rf ~/Library/Application\ Support/toggl-timeguru/config.toml
• Linux: rm -rf ~/.config/toggl-timeguru/
• Windows: Remove-Item -Recurse -Force "$env:APPDATA\toggl-timeguru\config.toml"

Multi-Account Support

The application automatically detects when you switch between Toggl API tokens (different accounts):

• Database entries are automatically filtered by user_id
• The TUI displays your current account email in the header
• When switching accounts, you'll see a helpful message with cleanup instructions
• Use toggl-timeguru clean --data to remove old account data if needed

Development

Requirements

• Rust 1.89.0 or newer
• Cargo

Building

cargo build

Running Tests

cargo test

Code Formatting

cargo fmt

Linting

cargo clippy -- -D warnings

Project Structure

src/
├── cli.rs          # Command-line interface definitions
├── config/         # Configuration management
├── db/             # SQLite database operations
│   ├── connection.rs
│   └── schema.rs
├── processor.rs    # Time entry processing logic
├── toggl/          # Toggl API client
│   ├── client.rs
│   └── models.rs
├── ui/             # Terminal user interface
│   ├── app.rs
│   └── components.rs
└── main.rs         # Application entry point

Roadmap

See docs/PROGRESS.md for detailed development progress.

Phase 1: MVP (Completed)

• ✅ Core Toggl API integration
• ✅ Local SQLite caching
• ✅ Basic TUI with time entry display
• ✅ Time entry grouping and filtering
• ✅ Configuration management

Phase 2: Enhanced Functionality (In Progress)

• ✅ Advanced filtering (CLI and TUI project/tag filters)
• ✅ CSV export with grouping options
• ✅ Enhanced UI with better navigation
• ✅ Project assignment in TUI
• ✅ Time entry editing in TUI
• ✅ Multi-account support
• ✅ Data management CLI
• ✅ Time tracking CLI (start/stop commands)
• ✅ CI/CD & Build Automation
• ✅ Report generation (daily, weekly, monthly)
• ✅ Project selector usage sorting and first-letter jumps
• Client filtering UI (deferred until client names/models are available)
• Fuzzy description matching
• Incremental sync

Phase 3: Additional Features

• PDF export
• In-app help system
• Cross-platform packaging
• CI/CD pipeline
• Docker support

Tech Stack

• Language: Rust (edition 2024)
• TUI Framework: Ratatui + Crossterm
• HTTP Client: Reqwest (with rustls)
• Database: SQLite (via rusqlite)
• CLI Parsing: Clap
• Configuration: Confy
• Serialization: Serde
• Date/Time: Chrono
• Error Handling: Anyhow
• Logging: Tracing

See docs/TECH_STACK.md for complete details.

Documentation

• Initial Functional Analysis
• Library Recommendations
• Tech Stack Details
• Development Progress

License

MIT License - see LICENSE for details.

Contributing

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

Author

Dominik Zarsky dzarsky@dzarsky.eu