toggletui

README

ToggleTUI

A beautiful Terminal User Interface (TUI) for Toggl time tracking, built with Go and tview.

Features

• 🕐 Current Timer Display - See your running timer with elapsed time
• 📊 Today's Entries - View all time entries for today with total time
• ⚡ Smart Sync - Intelligent API rate limiting (respects 30 calls/hour limit)
• 🎨 Beautiful UI - Clean, colorful terminal interface
• ⌨️ Keyboard Controls - Efficient keyboard-driven workflow
• 💾 Local Caching - Updates UI every second without API calls

Smart Sync Strategy

ToggleTUI intelligently manages API calls to stay within Toggl's rate limit:

• Timer Running: Syncs every 3 minutes (~20 calls/hour)
• User Activity: Syncs 2 minutes after last interaction
• Idle: Syncs every 10 minutes (~12 calls/hour)
• Safety Net: Forces sync after 15 minutes max

This means you can run ToggleTUI all day without hitting rate limits!

Installation

Option 1: Using go install (Recommended)

go install github.com/falt/toggletui@latest

Then run:

toggletui

On first run, you'll be prompted to enter your API token.

Option 2: Build from source

git clone https://github.com/falt/toggletui.git
cd toggletui
go build -o toggletui
./toggletui

Option 3: Download pre-built binary

Download the latest release from the Releases page.

Setup

Getting your API Token

1. Go to https://track.toggl.com/profile
2. Scroll down to "API Token"
3. Copy your token

First Run

When you run toggletui for the first time, you'll see:

ToggleTUI - First Time Setup
=============================

Get your API token from: https://track.toggl.com/profile

Enter your Toggl API token:

Enter your token and it will be saved to ~/.config/toggletui/token

Alternative: Environment Variable

You can also set your API token as an environment variable:

export TOGGL_API_TOKEN=your_token_here
toggletui

Usage

Keyboard Commands

• t - Toggle time display (show/hide elapsed time)
• r - Manual refresh (sync with Toggl API)
• s - Stop current running timer
• q - Quit application

Status Bar

The status bar shows:

• Last sync time - "Synced 45s ago"
• API call counter - "API: 12/30"
• Keyboard shortcuts

Project Structure

toggletui/
├── main.go           # Main application and TUI logic
├── toggl/
│   └── client.go     # Toggl API client
├── go.mod            # Go dependencies
└── README.md         # This file

Configuration

Configuration is stored in ~/.config/toggletui/:

• token - Your Toggl API token (chmod 600)

API Usage

ToggleTUI uses the following Toggl API endpoints:

• GET /me/time_entries/current - Get current running timer
• GET /me/time_entries - Get time entries for date range
• PATCH /workspaces/{id}/time_entries/{id}/stop - Stop timer

Development

Prerequisites

• Go 1.21 or higher
• A Toggl account with API access

Running locally

git clone https://github.com/falt/toggletui.git
cd toggletui
go mod download
go run main.go

Building

go build -o toggletui

Testing with different terminals

ToggleTUI works best with modern terminals that support:

• 256 colors
• UTF-8
• Terminal resizing

Recommended terminals:

• iTerm2 (macOS)
• Terminal.app (macOS)
• Alacritty
• Kitty
• Windows Terminal (Windows)

Contributing

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

TODO / Future Improvements

• Start new timers from TUI
• Display project names instead of IDs
• Edit existing entries
• Filter entries by project
• Weekly and monthly views
• Statistics and reports
• Support for tags
• Custom color themes
• Configuration file for settings

License

MIT License - see LICENSE file for details

Acknowledgments

• Built with tview - Terminal UI library
• Uses tcell - Terminal handling
• Powered by Toggl Track API

Support

If you encounter any issues or have questions:

• Open an issue on GitHub
• Check the Toggl API documentation

Author

Andreas Fält - GitHub

---

Made with ❤️ for Toggl users who love the terminal