Timesheet - Time Tracking

Track time, manage projects and tasks using timesheet.io CLI

Security Scan

Instruction-only timesheet CLI skill is internally coherent for the stated purpose, but the SKILL.md and registry metadata disagree about required binaries and it references an API key and jq usage that are not declared — verify those before installing or running.

Purpose & Capability

The skill's stated purpose (control timesheet.io via the timesheet CLI) matches the instructions. However, SKILL.md metadata lists a required binary ('timesheet') while the registry metadata earlier claimed no required binaries — this mismatch should be resolved.

Instruction Scope

SKILL.md limits actions to running the timesheet CLI (auth, timer, projects, tasks, reports, config). Those commands are appropriate for the purpose. The docs do show examples that may read or show local CLI config (e.g., `timesheet config show`) and auth status — expected but worth noting because local config may contain tokens.

Install Mechanism

There is no install spec (instruction-only), so nothing is written to disk by the skill itself. This is the lowest-risk install posture.

Credentials

SKILL.md suggests setting TIMESHEET_API_KEY for automation and uses `jq` in an example, but the registry did not declare any required environment variables or binaries. Requesting an API key is reasonable for this CLI, but the skill should declare that requirement explicitly and mention the exact env var(s) it needs.

Persistence & Privilege

always is false and the skill has no install/script so it does not request permanent presence or elevated platform privileges.

Assessment

This skill is instruction-only and simply tells an agent how to call the timesheet.io CLI. Before using it, verify: 1) You have the official timesheet CLI installed from a trusted source; SKILL.md expects a 'timesheet' binary but the registry metadata omitted that — confirm the requirement. 2) The CLI may require an API key (TIMESHEET_API_KEY) or local login; if you set an API key, be aware it will be available to processes and could be read by commands like `timesheet config show` — store keys securely and avoid exporting them in shared shells. 3) The docs use `jq` for filtering but do not declare it as a dependency — install jq if you plan to use those examples. 4) Review what the timesheet CLI stores in its config (tokens, file paths) so you understand what the agent could access when running auth/config commands. If you cannot verify the CLI source or prefer not to expose an API key, use the CLI manually instead of granting an automated agent permission to invoke it.

Timesheet CLI Skill

Control timesheet.io time tracking from the command line. Use --json flag for all commands to get structured output.

Authentication

Check auth status before using other commands:

timesheet auth status --json

If not authenticated, guide the user to run:

timesheet auth login

Or for automation, set an API key:

export TIMESHEET_API_KEY=ts_your.apikey

Timer Operations

Start a Timer

# List projects first to get project ID
timesheet projects list --json

# Start timer for a project
timesheet timer start <project-id>

Check Timer Status

timesheet timer status --json

Returns: status (running/paused/stopped), project name, duration, start time.

Control Timer

timesheet timer pause
timesheet timer resume
timesheet timer stop  # Creates a task from the timer

Update Running Timer

timesheet timer update --description "Working on feature X"
timesheet timer update --billable

Project Management

List Projects

timesheet projects list --json

Create Project

timesheet projects create "Project Name" --json
timesheet projects create "Client Project" --billable --json

Show/Update/Delete

timesheet projects show <id> --json
timesheet projects update <id> --title "New Name"
timesheet projects delete <id>

Task Management

List Tasks

timesheet tasks list --json           # Recent tasks
timesheet tasks list --today --json   # Today's tasks
timesheet tasks list --this-week --json

Create Task Manually

timesheet tasks create -p <project-id> -s "2024-01-15 09:00" -e "2024-01-15 17:00" --json
timesheet tasks create -p <project-id> -s "09:00" -e "17:00" -d "Task description" --json

Update Task

timesheet tasks update <id> --description "Updated description"
timesheet tasks update <id> --billable
timesheet tasks update <id> --start "10:00" --end "12:00"

Delete Task

timesheet tasks delete <id>

Teams & Tags

Teams

timesheet teams list --json

Tags

timesheet tags list --json
timesheet tags create "Urgent" --color 1
timesheet tags delete <id>

Reports

Time Summary

timesheet reports summary --today --json
timesheet reports summary --this-week --json
timesheet reports summary --this-month --json
timesheet reports summary --from 2024-01-01 --to 2024-01-31 --json

Export Data

timesheet reports export -f xlsx -s 2024-01-01 -e 2024-01-31
timesheet reports export -f csv --this-month

Profile & Config

timesheet profile show --json
timesheet profile settings --json

timesheet config show
timesheet config set defaultProjectId <id>

Common Workflows

Log Time for Current Work

1. Check if timer is running: timesheet timer status --json
2. If not, start timer: timesheet timer start <project-id>
3. When done, stop timer: timesheet timer stop

Quick Time Entry

# Create a completed task directly
timesheet tasks create -p <project-id> -s "09:00" -e "12:00" -d "Morning standup and dev work" --json

Find Project by Name

timesheet projects list --json | jq '.[] | select(.title | contains("ProjectName"))'

Error Handling

Exit codes:

• 0: Success
• 1: General error
• 2: Usage error (invalid arguments)
• 3: Authentication error - run timesheet auth login
• 4: API error
• 5: Rate limit exceeded - wait and retry
• 6: Network error

Tips

• Always use --json for parsing output programmatically
• Use --quiet or -q to suppress non-essential output
• Set defaultProjectId in config to skip project selection for timer
• Pipe-friendly output is automatic when not in a terminal