--- name: toggl-cli description: Use the Toggl CLI to work with Toggl 2.0 tasks, projects, time entries, time blocks, workspaces, authentication, and CLI maintenance from an agent-friendly terminal workflow. Trigger when the user asks to inspect or modify Toggl 2.0 data through the terminal, authenticate Toggl, switch workspaces, install or refresh the Toggl agent skill, update the CLI, or automate Toggl 2.0 workflows. --- # Toggl CLI Use the `toggl` command when the user wants to inspect or modify Toggl 2.0 data from the terminal. The CLI is designed for agents: commands are non-interactive when flags are supplied, `--json` gives compact machine-readable responses, validation errors are explicit, and destructive operations require confirmation flags. ## When to Use Use this skill when the task involves: - Listing, reading, creating, updating, or deleting Toggl 2.0 tasks, projects, time blocks, or time entries. - Managing saved views, custom fields (admin), and task/project attachments (including file upload and download). - Finding workspace metadata such as statuses, users, and workspace IDs. - Authenticating the Toggl CLI, switching saved profiles, or switching the active workspace. - Installing or refreshing the CLI's agent skill (`toggl skill setup`, or `toggl skill sync` after upgrading `@toggl/cli`). - Updating a globally installed `@toggl/cli`. - Automating a Toggl 2.0 workflow from shell commands. Do not use this skill for Toggl Track APIs, raw Toggl 2.0 API calls, or MCP server implementation work unless the user specifically asks to operate through the CLI. ## Operating Rules - Prefer `toggl --json ...` for any command whose output you will parse. - Without `--json`, successful responses are formatted for human reading; do not parse that output in scripts. - Run list/get commands first when the target ID is unclear. - Use scalar flags for simple inputs: `--task-id`, `--project-id`, `--payload-status-id`. - Use `--data -` or `--data-file ` for nested payloads or fragile shell quoting. - Use `--dry-run` before mutations when you need to validate input. - On a TTY, mutations that omit `--data` / `--data-file` / complete scalar flags may open interactive prompts by default; optional reads only prompt when the operation allows it and you pass **`--interactive`**. The **`--interactive`** / **`--no-interactive`** flags exist only on commands where the catalog enables prompting (not on read-only commands that are `interactive: hidden`). Agents and scripts should pass explicit `--*-id` flags or `--data` instead of relying on prompts. - Never pass `--yes` unless the user explicitly requested a destructive delete. - Use `toggl profile current` / `toggl profile list` when the active account may be wrong. - Use `toggl profile switch []` to change the default account (omit the name in a TTY to pick interactively), or `--profile ` / `--workspace-id ` for one command. Use `toggl profile remove []` to delete a saved profile (omit the name in a TTY to pick interactively). - Use `toggl workspace switch []` to set the active workspace (omit the id in a TTY to pick interactively from cached workspaces; use `toggl workspace list --refresh` if the list is stale). - When changing a time entry’s start time or duration together, use `time-entries update` with required `type` (`activity` or `break`), not `partial-update`; details are in `reference/time-entries.md`. - Inspect command help when unsure: `toggl … --help`. Use **`--dry-run`** to print `{ dry_run, operation, input }` (operation id plus validated body) without calling the API. - Use the curated command groups: organization commands live under **`toggl organization …`** (not `toggl org …`), shared-data CLI routes sit under **`toggl shared …`**, search is `toggl search`, workspace settings are not nested under `users`, and advanced composite creation is under `projects create-advanced` / `tasks create-with-children`. Attachments nest under their parent: `toggl tasks attachments …` / `toggl projects attachments …`. - Attachment files use local paths: upload with `attachments create --file-path ` (mime inferred from extension, 20 MB cap), bulk-upload with `--data '{"file_paths":[…]}'`, download with `attachments view --save-to ` (refuses to replace an existing file unless `--overwrite true`). - custom-fields mutations need workspace admin and 403 otherwise. - After the user upgrades `@toggl/cli`, suggest `toggl skill sync` if they use `--copy` installs; symlink installs usually track the package without an extra step. ## Read Next - Toggl 2.0 concepts, entity hierarchy, and resource relationships: `reference/focus-concepts.md` - Auth, profiles, and workspaces: `reference/auth-environments-workspaces.md` - Command shape, JSON input, output, dates, and safety flags: `reference/command-contract.md` - Tasks: `reference/tasks.md` - Projects: `reference/projects.md` - Time entries: `reference/time-entries.md` - Time blocks: `reference/time-blocks.md` - Rates and billables (Toggl 2.0 API vs Track): `reference/rates-and-billables.md` - Statuses and users: `reference/statuses-users.md` - Reports (`get-workload` vs `get-flexq-data`): `reference/reports.md` - Common multi-step flows: `workflows/common-workflows.md` - Errors and recovery: `reference/troubleshooting.md` ## Quick Start ```bash toggl auth toggl --json profile list toggl --json workspace list toggl --json tasks list --project-id toggl tasks update --task-id --payload-status-id --dry-run toggl --json tasks update --task-id --payload-status-id ```