Unofficial Toggl Track CLI — a thin wrapper over the Toggl Track API v9 for managing time tracking from the command line.
Download a prebuilt binary for your platform from Releases.
Supported platforms:
- Linux (x86_64)
- macOS (Apple Silicon)
- Windows (x86_64)
cargo install --path .Requires Rust 1.85.0 or later.
Set your Toggl Track API token. You can find it in Profile Settings.
# Interactive input (recommended - not saved in shell history)
tgltrk auth login
# Or use an environment variable
export TOGGL_API_TOKEN=your_token_hereCheck authentication status:
$ tgltrk auth status
✓ Authenticated as Alice (alice@example.com)# Show current timer
$ tgltrk timer current
#12345678 Code review 01:23:45 [running]
# Start a timer
$ tgltrk timer start -d "Code review" -p 12345 -t bug,review
✓ Timer started
#12345679 Code review 00:00:00 [running] [bug, review]
# Stop the timer
$ tgltrk timer stop
✓ Timer stopped
#12345679 Code review 00:45:12# List recent entries
$ tgltrk entries list -n 3
#12345677 Weekly meeting 2024-01-15 10:00-11:00 01:00:00 (Internal)
#12345676 Bug fix 2024-01-15 09:00-09:30 00:30:15 (Project A [Acme])
#12345675 Design review 2024-01-14 14:00-16:15 02:15:00 (Project A [Acme]) [design]
# Filter by date range
$ tgltrk entries list --since 2024-01-01 --until 2024-01-31
# Get entry details
$ tgltrk entries get 12345677
#12345677 Weekly meeting 01:00:00
# Create an entry with specific times
$ tgltrk entries create --start "2024-01-15 09:00" --stop "2024-01-15 10:30" -d "Morning meeting"
✓ Entry created
#12345678 Morning meeting 01:30:00
# Create with duration instead of stop time
$ tgltrk entries create --start "2024-01-15 14:00" --duration "2h" -d "Coding session"
✓ Entry created
#12345679 Coding session 02:00:00
# Edit an entry
$ tgltrk entries edit 12345677 -d "Standup meeting" -b true
✓ Entry updated
#12345677 Standup meeting 01:00:00
# Edit start/stop time
$ tgltrk entries edit 12345677 --start "2024-01-15 09:30" --duration "45m"
✓ Entry updated
#12345677 Standup meeting 00:45:00
# Delete an entry
$ tgltrk entries delete 12345677
✓ Entry #12345677 deleted
# Continue a previous entry (starts a new timer with the same settings)
$ tgltrk entries continue 12345676
✓ Timer continued
#12345680 Bug fix 00:00:00 [running]$ tgltrk projects list
#1001 Website Redesign [Acme Corp]
#1002 Mobile App [Acme Corp]
#1003 API Migration [Globex] (archived)
# Create a project with a client
$ tgltrk projects create "New Project" --client 101
✓ Project created
#1004 New Project
$ tgltrk projects update 1004 --name "Renamed Project"
✓ Project updated
#1004 Renamed Project
$ tgltrk projects delete 1004
✓ Project #1004 deleted$ tgltrk clients list
#101 Acme Corp
#102 Globex Inc
$ tgltrk clients get 101
#101 Acme Corp
$ tgltrk clients create "New Client"
✓ Client created
#103 New Client
$ tgltrk clients update 103 --name "Renamed Client"
✓ Client updated
#103 Renamed Client
$ tgltrk clients delete 103
✓ Client #103 deleted$ tgltrk tags list
#501 bug
#502 review
#503 design
$ tgltrk tags create "urgent"
✓ Tag created
#504 urgent
$ tgltrk tags delete 504
✓ Tag #504 deleted$ tgltrk workspaces list
#1234 My Workspace
#5678 Team Workspace
$ tgltrk workspaces get 1234
#1234 My WorkspaceUser info, projects, clients, tags, and workspaces are cached for 72 hours to reduce API calls. Toggl Track API has rate limits, and caching helps stay within those limits during normal usage.
$ tgltrk cache status
Cache dir: /Users/alice/Library/Caches/com.tgltrk.tgltrk
user: 245 bytes, last updated 2024-01-15 10:30:00 UTC
projects_1234: 1024 bytes, last updated 2024-01-15 10:30:01 UTC
$ tgltrk cache clear
✓ Cache clearedCache is automatically invalidated when you create, update, or delete projects/tags. Switching accounts via auth login clears all cached data.
--json Output in JSON format
--workspace Override workspace ID
JSON output includes cache hit metadata:
{
"meta": { "cached": ["user"] },
"data": {
"email": "alice@example.com",
"fullname": "Alice",
"default_workspace_id": 1234,
"timezone": "Asia/Tokyo"
}
}API tokens are stored in the OS native keyring (macOS Keychain / Windows Credential Manager / Linux Secret Service). If the keyring is unavailable, use the TOGGL_API_TOKEN environment variable instead.
Note: When TOGGL_API_TOKEN is set, it always takes precedence over the keyring. auth login and auth clear still operate on the keyring, but the environment variable will be used for API calls.
- No bulk operations: batch edit/delete of multiple entries or projects is not supported
- No reporting: Toggl Track's reporting endpoints (Summary, Detailed, Weekly) are not supported
- No workspace management: workspaces can be listed but not created or modified;
--workspaceselects an existing one - Paid features: features exclusive to paid Toggl Track plans (e.g., tasks, project templates, time estimates, required fields) are not supported
- Rate limits: Toggl Track API enforces rate limits. The CLI caches data for 72 hours to minimize API calls. If you hit rate limits, wait for the reset before retrying
The following Toggl Track API v9 endpoints are available but not implemented in this CLI:
PUT /me— Update user profile (timezone, email, etc.)GET /me/projects,GET /me/clients,GET /me/tags— Cross-workspace listing (single-workspace listing via--workspaceis supported)GET /me/features— Account feature flagsGET /me/location— IP-based locationGET /me/web-timer— Web timer state (usetimer currentinstead)PATCH /workspaces/{wid}/time_entries/{ids}— Bulk update time entriesPATCH /workspaces/{wid}/projects/{ids}— Bulk update projects
MIT OR Apache-2.0