@togglhq/cli 1.5.19

package/skills/toggl-cli/reference/statuses-users.md

@@ -0,0 +1,33 @@
+# Statuses and Users
+
+Statuses and users are reference data. Use them to resolve IDs before task updates, assignment-related payloads, filtering, or reporting.
+
+## Statuses
+
+List statuses:
+
+```bash
+toggl --json statuses list
+```
+
+Use this before moving a task when the user gives a status name instead of a status ID:
+
+```bash
+toggl --json tasks update --task-id <task-id> --payload-status-id <status-id>
+```
+
+## Users
+
+List users:
+
+```bash
+toggl --json users list
+```
+
+Use this before working with assignee/member IDs when a user gives a person name or email.
+
+## Agent Workflow
+
+Do not guess IDs from names. List the reference data, pick the exact match, and ask when there are multiple plausible matches.
+
+If a status or user appears missing, verify the active workspace and profile before concluding it does not exist.

package/skills/toggl-cli/reference/tasks.md

@@ -0,0 +1,57 @@
+# Tasks
+
+Use task commands for Focus task lookup, creation, updates, and deletion.
+
+## Commands
+
+List tasks:
+
+```bash
+toggl --json tasks list --project-id <project-id>
+toggl --json tasks list --project-id <project-id> --status-id <status-id>
+```
+
+Get one task:
+
+```bash
+toggl --json tasks get --task-id <task-id>
+```
+
+Create a task:
+
+```bash
+toggl --json tasks create --data '{"name":"Follow up with design","project_id":436195}'
+```
+
+Update a task with scalar payload flags:
+
+```bash
+toggl --json tasks update --task-id <task-id> --payload-name "Updated name"
+toggl --json tasks update --task-id <task-id> --payload-status-id <status-id>
+```
+
+Update a task with a JSON payload:
+
+```bash
+toggl --json tasks update --data '{"task_id":12345,"payload":{"name":"Updated name","status_id":270002}}'
+```
+
+Delete a task only after explicit user confirmation:
+
+```bash
+toggl --json tasks delete --task-id <task-id> --yes
+```
+
+## Agent Workflow
+
+When the user names a task but does not provide an ID, list tasks in the relevant project first. If multiple matches are plausible, ask before mutating.
+
+When changing a task status, use `toggl --json statuses list` if the status ID is unknown.
+
+Use `--dry-run` before non-trivial updates:
+
+```bash
+toggl tasks update --task-id <task-id> --payload-status-id <status-id> --dry-run
+```
+
+Prefer scalar flags for single-field updates. Prefer `--data -` or `--data-file` for multi-field payloads or names with tricky shell quoting.

package/skills/toggl-cli/reference/time-blocks.md

@@ -0,0 +1,43 @@
+# Time Blocks
+
+Use time block commands to inspect, create, update, and delete scheduled Focus blocks.
+
+## Commands
+
+List time blocks for a date range:
+
+```bash
+toggl --json time-blocks list --date-from 2026-04-01 --date-to 2026-04-07
+```
+
+Get one time block:
+
+```bash
+toggl --json time-blocks get --task-id <task-id> --time-block-id <time-block-id>
+```
+
+Create a time block:
+
+```bash
+toggl --json time-blocks create --data '{"task_id":12345,"payload":{"start":"2026-04-06T09:00:00Z","end":"2026-04-06T11:00:00Z"}}'
+```
+
+Update a time block:
+
+```bash
+toggl --json time-blocks update --data '{"task_id":12345,"time_block_id":67890,"payload":{"start":"2026-04-06T10:00:00Z","end":"2026-04-06T12:00:00Z"}}'
+```
+
+Delete a time block only after explicit user confirmation:
+
+```bash
+toggl --json time-blocks delete --task-id <task-id> --time-block-id <time-block-id> --yes
+```
+
+## Agent Workflow
+
+Use RFC 3339 timestamps for exact scheduled blocks. If the user gives local times, preserve the intended time zone offset when possible.
+
+Time block commands usually need both `task_id` and `time_block_id`. Resolve both IDs with a list or get command before mutating.
+
+Use `--dry-run` before creating or updating blocks when times were inferred from natural language.

package/skills/toggl-cli/reference/time-entries.md

@@ -0,0 +1,42 @@
+# Time Entries
+
+Use time entry commands to inspect tracked time and control the running timer.
+
+## Commands
+
+List time entries for a date range:
+
+```bash
+toggl --json time-entries list --date-from 2026-04-01 --date-to 2026-04-07
+```
+
+Start tracking a task. When `--type` is omitted, the CLI defaults to `activity`:
+
+```bash
+toggl --json time-entries start --task-id <task-id>
+```
+
+Start a break:
+
+```bash
+toggl --json time-entries start --type break
+```
+
+Stop the running timer:
+
+```bash
+toggl --json time-entries stop
+```
+
+## Update vs partial-update
+
+- **`time-entries partial-update`** — PATCH-style: change optional fields (for example description, billable, or type) without sending a full timing payload.
+- **`time-entries update`** — full timing replace: the API requires **`start`**, **`duration`**, and **`type`** together (`activity` or `break`). Use **`update`** when moving or resizing an entry (new start and duration); do not use **`partial-update`** for that.
+
+## Agent Workflow
+
+When the user asks to start tracking work for a named task, resolve the task ID first with `tasks list` or `tasks get`.
+
+Use `YYYY-MM-DD` ranges for full days. Use RFC 3339 datetimes when the user gives exact times or time zones.
+
+Before starting a timer on an ambiguous task, ask for confirmation. Stopping the timer does not require a task ID.

package/skills/toggl-cli/reference/troubleshooting.md

@@ -0,0 +1,100 @@
+# Troubleshooting
+
+## Not Authenticated
+
+Error:
+
+```text
+Not authenticated. Run `toggl auth` to sign in.
+```
+
+Fix:
+
+```bash
+toggl auth
+```
+
+Use `toggl profile list` and `toggl profile switch [<profile>]` (omit name in a TTY for an interactive picker) if the user intended a different auth context.
+
+## Workspace Problems
+
+If data appears missing or a command targets the wrong workspace:
+
+```bash
+toggl --json profile current
+toggl --json profile list
+toggl --json workspace list
+toggl --json workspace list --refresh
+toggl --json workspace switch <workspace-id>
+```
+
+For one-off calls, prefer:
+
+```bash
+toggl --workspace-id <workspace-id> --json tasks list --project-id <project-id>
+```
+
+## Invalid JSON
+
+Error:
+
+```text
+Invalid JSON from --data
+```
+
+Fix shell quoting by using stdin or a file:
+
+```bash
+printf '%s\n' '{"task_id":12345,"payload":{"name":"Renamed task"}}' | toggl --json tasks update --data -
+toggl --json tasks update --data-file ./payload.json
+```
+
+## Missing Fields
+
+Error:
+
+```text
+Invalid input: task_id: required
+```
+
+Add the named scalar flag or include the field in `--data`:
+
+```bash
+toggl --json tasks get --task-id 12345
+toggl --json tasks get --data '{"task_id":12345}'
+```
+
+## Date Validation
+
+Use `YYYY-MM-DD` for full days or RFC 3339 for exact datetimes:
+
+```bash
+toggl --json time-entries list --date-from 2026-04-01 --date-to 2026-04-07
+toggl --json time-blocks list --date-from 2026-04-01T08:00:00+03:00 --date-to 2026-04-01T17:00:00+03:00
+```
+
+## Destructive Operation Blocked
+
+Delete commands fail without `--yes`. Only retry with `--yes` when the user explicitly requested the delete and the ID is confirmed:
+
+```bash
+toggl --json tasks delete --task-id <task-id> --yes
+```
+
+## Schema Warnings
+
+For API response schema warnings, rerun with debug enabled:
+
+```bash
+TOGGL_DEBUG=1 toggl --json tasks list --project-id 436195
+```
+
+## Unknown Command Shape
+
+Inspect help before guessing:
+
+```bash
+toggl --help
+toggl tasks --help
+toggl tasks update --help
+```

package/skills/toggl-cli/workflows/common-workflows.md

@@ -0,0 +1,104 @@
+# Common Workflows
+
+## Find IDs Before Acting
+
+Resolve project IDs:
+
+```bash
+toggl --json projects list
+```
+
+Resolve task IDs:
+
+```bash
+toggl --json tasks list --project-id <project-id>
+```
+
+Resolve status IDs:
+
+```bash
+toggl --json statuses list
+```
+
+Resolve user IDs:
+
+```bash
+toggl --json users list
+```
+
+If multiple resources match a user-provided name, ask before mutating.
+
+## Create a Task in a Project
+
+1. Resolve the project ID.
+2. Create the task.
+3. Return the created task JSON or summarize the created ID.
+
+```bash
+toggl --json projects list
+toggl --json tasks create --data '{"name":"Write release notes","project_id":436195}'
+```
+
+## Move a Task to a Status
+
+1. Resolve the task ID.
+2. Resolve the status ID.
+3. Dry-run if either ID was inferred.
+4. Update the task.
+
+```bash
+toggl --json tasks list --project-id <project-id>
+toggl --json statuses list
+toggl tasks update --task-id <task-id> --payload-status-id <status-id> --dry-run
+toggl --json tasks update --task-id <task-id> --payload-status-id <status-id>
+```
+
+## Start Tracking Work
+
+1. Resolve the task ID when the user names a task.
+2. Start the activity timer.
+
+```bash
+toggl --json tasks list --project-id <project-id>
+toggl --json time-entries start --task-id <task-id>
+```
+
+Start a break:
+
+```bash
+toggl --json time-entries start --type break
+```
+
+Stop the running timer:
+
+```bash
+toggl --json time-entries stop
+```
+
+## Plan a Time Block
+
+1. Resolve the task ID.
+2. Convert user-provided times to RFC 3339 datetimes.
+3. Dry-run when the time range was inferred.
+4. Create the block.
+
+```bash
+toggl time-blocks create --data '{"task_id":12345,"payload":{"start":"2026-04-06T09:00:00+03:00","end":"2026-04-06T11:00:00+03:00"}}' --dry-run
+toggl --json time-blocks create --data '{"task_id":12345,"payload":{"start":"2026-04-06T09:00:00+03:00","end":"2026-04-06T11:00:00+03:00"}}'
+```
+
+## Switch Workspace
+
+List workspaces, refresh if needed, then switch:
+
+```bash
+toggl --json workspace list
+toggl --json workspace list --refresh
+toggl --json workspace switch <workspace-id>
+```
+
+For one command only:
+
+```bash
+toggl --workspace-id <workspace-id> --json tasks list --project-id <project-id>
+```