Toggl CLI – Time tracking for you and your agent

Control your Toggl Track workspace via CLI to manage time entries, projects, clients, tasks, tags, workspaces, and user profiles with flexible commands.

Security Scan

The skill's instructions match a Toggl CLI, but the package metadata omits the required API token and the runtime instructions ask you to run unreviewed npm code and to store a secret in agent-visible files—this mismatch and the install guidance are concerning.

Purpose & Capability

The name and SKILL.md describe a Toggl CLI that manages time entries, projects, clients, etc. The commands and API endpoints listed are consistent with a Toggl Track integration.

Instruction Scope

The runtime instructions explicitly tell the user to set TOGGL_API_TOKEN (and optionally TOGGL_WORKSPACE_ID), to git-clone a GitHub repo and run npm install/build/link. However the skill metadata does not declare any required environment variables. The SKILL.md also recommends placing the API token in ~/.claude/.env (an agent-specific file) or in shell rc files, which has implications for secret exposure and scope of access.

Install Mechanism

There is no registry install spec; the SKILL.md instructs manual installation from https://github.com/FroeMic/toggl-cli using git + npm. Installing and linking unreviewed npm code runs arbitrary scripts on the user's machine — a normal choice for a CLI but it increases risk compared to a vetted package. The repository is a public GitHub URL (not a shortener or IP), which is better than an unknown host but still unverified.

Credentials

The skill actually requires TOGGL_API_TOKEN (and optionally TOGGL_WORKSPACE_ID), yet the registry metadata lists no required env vars or primary credential. Asking for an API token is reasonable for Toggl, but the omission from metadata is an inconsistency. Additionally, recommending storing the token in ~/.claude/.env or shell rc files may expose the secret to other tools or the agent runtime.

Persistence & Privilege

No elevated persistence flags are set (always not set). However disable-model-invocation is not set, so an agent could invoke this skill autonomously if integrated. Given the skill acts on a user's Toggl account via an API token, consider whether you want the agent able to make changes without explicit user approval.

What to consider before installing

This SKILL.md appears to implement a legitimate Toggl CLI, but the metadata failed to declare the TOGGL_API_TOKEN it requires — that's an inconsistency you should understand before installing. If you consider using it: - Review the GitHub repo code yourself (or have a trusted reviewer) before running npm install/link; npm scripts can execute arbitrary code. - Prefer not to put your API token in broadly-loaded shell rc files; store secrets in a secure location and only expose them to the CLI when needed. - Be cautious about adding the token to ~/.claude/.env (it may make the token accessible to agents or tools you run). - If you don't want the agent to act on your Toggl account autonomously, ensure model-invocation is restricted or require explicit user consent when the skill runs. - Ask the publisher to update registry metadata to declare required environment variables and primary credential (TOGGL_API_TOKEN) so the skill's claims and requirements match. If you cannot or will not review the repository and are uncomfortable exposing your Toggl API token, do not install or provide the token.

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.