Toggl CLI – Time tracking for you and your agent

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):

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                                    # Get entry by ID
toggl te create --start "2024-01-15T09:00:00Z" --duration 3600 --description "Meeting"
toggl te update  --description "Updated"        # Update entry
toggl te delete                                 # Delete entry

Projects (alias: proj)

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

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               # Archive a client
toggl client restore               # Restore archived client
toggl client delete 

Tags

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

Tasks

toggl task list --project 
toggl task create --name "Implement feature" --project 
toggl task update  --project  --name "Updated task"
toggl task delete  --project 

Workspaces (alias: ws)

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

Organizations (alias: org)

toggl org get                      # Get organization details
toggl org users list --organization   # List org users

Groups

toggl group list --organization 
toggl group create --organization  --name "Development Team"
toggl group update  --organization  --name "Engineering Team"
toggl group delete  --organization 

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

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