toggl-cli

Interact with your Toggl Track workspace via the toggl-cli.

Install

Clone and install the CLI:

git clone https://github.com/FroeMic/toggl-cli
cd toggl-cli
npm install
npm run build
npm link

Set TOGGL_API_TOKEN environment variable (get it from Toggl Profile Settings):

• Recommended: Add to ~/.claude/.env for Claude Code
• Alternative: Add to ~/.bashrc or ~/.zshrc: export TOGGL_API_TOKEN="your-api-token"

Optionally set default workspace:

export TOGGL_WORKSPACE_ID="your-workspace-id"

Repository: https://github.com/FroeMic/toggl-cli

Commands

Time Entries (alias: te)

toggl te start --description "Working on feature"  # Start a timer
toggl te stop                                       # Stop the running timer
toggl te current                                    # Get current running entry
toggl te list                                       # List recent entries
toggl te list --start-date 2024-01-01              # List from date to now
toggl te list --start-date 2024-01-01 --end-date 2024-01-31  # Date range
toggl te get <id>                                   # Get entry by ID
toggl te create --start "2024-01-15T09:00:00Z" --duration 3600 --description "Meeting"
toggl te update <id> --description "Updated"        # Update entry
toggl te delete <id>                                # Delete entry

Projects (alias: proj)

toggl proj list                        # List all projects
toggl proj list --active true          # List active projects only
toggl proj get <id>                    # Get project details
toggl proj create --name "New Project" --color "#FF5733"
toggl proj update <id> --name "Renamed"
toggl proj delete <id>

Clients

toggl client list                      # List clients
toggl client list --status archived    # List archived clients
toggl client create --name "Acme Corp" --notes "Important client"
toggl client archive <id>              # Archive a client
toggl client restore <id>              # Restore archived client
toggl client delete <id>

Tags

toggl tag list                         # List tags
toggl tag create --name "urgent"
toggl tag update <id> --name "high-priority"
toggl tag delete <id>

Tasks

toggl task list --project <project_id>
toggl task create --name "Implement feature" --project <project_id>
toggl task update <id> --project <project_id> --name "Updated task"
toggl task delete <id> --project <project_id>

Workspaces (alias: ws)

toggl ws list                          # List workspaces
toggl ws get <id>                      # Get workspace details
toggl ws users list --workspace <id>   # List workspace users

Organizations (alias: org)

toggl org get <id>                     # Get organization details
toggl org users list --organization <id>  # List org users

Groups

toggl group list --organization <id>
toggl group create --organization <id> --name "Development Team"
toggl group update <id> --organization <org_id> --name "Engineering Team"
toggl group delete <id> --organization <org_id>

User Profile

toggl me get                           # Get your profile
toggl me get --with-related-data       # Include workspaces, etc.
toggl me preferences                   # Get user preferences
toggl me quota                         # Get API rate limit info

Output Formats

All list/get commands support --format option:

toggl te list --format json            # JSON output (default)
toggl te list --format table           # Human-readable table
toggl te list --format csv             # CSV for spreadsheets

Key Concepts

API Reference

• Base URL: https://api.track.toggl.com/api/v9
• Auth: HTTP Basic with API token as both username and password
• Rate Limits: 1 request/second (leaky bucket), 30-600 requests/hour (quota)

Common API Operations

Get current user:

curl -u $TOGGL_API_TOKEN:api_token https://api.track.toggl.com/api/v9/me

List time entries:

curl -u $TOGGL_API_TOKEN:api_token \
  "https://api.track.toggl.com/api/v9/me/time_entries?start_date=2024-01-01&end_date=2024-01-31"

Start a timer:

curl -X POST -u $TOGGL_API_TOKEN:api_token \
  -H "Content-Type: application/json" \
  -d '{"workspace_id": 123, "start": "2024-01-15T09:00:00Z", "duration": -1, "created_with": "curl"}' \
  https://api.track.toggl.com/api/v9/workspaces/123/time_entries

Stop a timer:

curl -X PATCH -u $TOGGL_API_TOKEN:api_token \
  https://api.track.toggl.com/api/v9/workspaces/{workspace_id}/time_entries/{entry_id}/stop

Notes

• The CLI handles rate limiting automatically with retry and exponential backoff.
• Negative duration on a time entry indicates a running timer.
• When using --start-date alone, --end-date defaults to now.
• Using --end-date without --start-date will error (API requires both).
• All timestamps are in ISO 8601 format.