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

Concept	Purpose	Example
Time Entries	Track time spent on tasks	"2 hours on Project X"
Projects	Group related time entries	"Website Redesign"
Clients	Group projects by customer	"Acme Corp"
Workspaces	Separate environments	"Personal", "Work"
Tags	Categorize entries	"billable", "meeting"
Tasks	Sub-items within projects	"Design mockups"

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.