Toggl Time Tracking

Use the toggl CLI (@beauraines/toggl-cli) for Toggl Track integration.

Prerequisites

Install the CLI:

npm install -g @beauraines/toggl-cli

Configure authentication (create ~/.toggl-cli.json):

{
  "api_token": "YOUR_TOGGL_API_TOKEN",
  "default_workspace_id": "YOUR_WORKSPACE_ID",
  "timezone": "Your/Timezone"
}

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

Get your workspace ID from your Toggl URL: https://track.toggl.com/{workspace_id}/...

Set permissions: chmod 600 ~/.toggl-cli.json

Commands

Status

toggl now                    # Show running timer
toggl me                     # Show user info

Start/Stop

toggl start                  # Start timer (interactive)
toggl start -d "Task name"   # Start with description
toggl start -d "Task" -p "Project"  # With project
toggl stop                   # Stop current timer

Continue Previous

toggl continue               # Restart most recent entry
toggl continue "keyword"     # Restart entry matching keyword

Reports

toggl today                  # Today's time by project
toggl week                   # Weekly summary by day

List Entries

toggl ls                     # Last 14 days
toggl ls -d 7                # Last 7 days
toggl ls --today             # Today only
toggl ls "search term"       # Search entries

Add Completed Entry

toggl add "9:00AM" "10:30AM" "Meeting notes"

Edit Current

toggl edit -s "10:00AM"      # Change start time
toggl edit -d "New desc"     # Change description
toggl edit -p "Project"      # Change project

Delete

toggl rm <id>                # Remove entry by ID

Projects

toggl project ls             # List projects

Other

toggl web                    # Open Toggl in browser
toggl create-config          # Generate config template

Notes

• Times must be parsable by dayjs (e.g., 4:50PM, 12:00 AM, 9:00)
• Config file: ~/.toggl-cli.json
• Environment variables override config: TOGGL_API_TOKEN, TOGGL_DEFAULT_WORKSPACE_ID, TOGGL_TIMEZONE