@toggl/cli

Command-line interface for Toggl 2.0.

Installation

npm install -g @togglhq/cli

Or run without installing:

npx @togglhq/cli

Authentication

toggl auth

Opens a browser for OAuth sign-in. On success, credentials are saved to ~/.toggl/focus-tools.json. When --profile is omitted, the CLI saves the account under a name based on your account, such as user-12345, and makes it active.

Options:

| Flag | Description | | --------------------- | --------------------------------------------------------------------- | | --workspace-id <id> | Select a specific workspace (required when your account has multiple) | | --profile <name> | Save credentials under an explicit profile name |

Sessions refresh automatically. Re-run toggl auth only to switch workspaces or after 4 weeks of inactivity.

Profiles

Use profiles to switch between saved accounts and environments:

toggl profile list
toggl profile current
toggl profile switch user-12345
toggl profile switch   # omit name in a TTY: pick from a menu or use the only profile
toggl profile remove user-12345

The active profile controls both the account and environment for later commands. You can still override it for one call with the global --profile <name> flag.

Agent skill setup

@togglhq/cli ships a toggl-cli agent skill under skills/toggl-cli. Install it with:

toggl skill setup

This delegates to the skills CLI, listed as a dependency of @togglhq/cli (no separate install). Interactive agent/scope prompts come from that CLI.

After upgrading the CLI, refresh the skill install:

toggl skill sync

By default the installer symlinks into your agent skill dirs so updates track CLI upgrades; use --copy only if you need a detached snapshot (then re-run toggl skill sync after upgrades). Pass flags for non-interactive setup:

toggl skill setup --agent cursor --global --copy --yes
toggl skill setup --agent cursor codex --copy --yes

Command shape

Generated Toggl 2.0 commands look like:

toggl [global flags] <group> … <subcommand> [flags]

Many endpoints use two segments (toggl tasks list). Some use nested groups, including:

• toggl organization … — organization APIs (not toggl org …; there is no org top-level command). Examples: toggl organization invitations list, toggl organization members get, toggl organization workspaces list, toggl organization workspaces get-timezone, toggl organization workspaces update-timezone.
• toggl shared … — shared workspace/org data routed through @toggl/queries helpers (status, holidays, working hours, time off). Example: toggl shared status get.

Core resource groups still include tasks, projects, time-blocks, time-entries, statuses, users, tags, clients, and others surfaced by the public command catalog. Some low-level endpoints are omitted from the CLI and MCP. Existing public command paths and operation IDs stay stable; use toggl --help and toggl <group> --help to explore what shipped.

Typical entity commands:

| Resource | Actions | | -------------- | -------------------------------------------------------- | | tasks | list (alias ls), get, create, update, delete | | projects | list (alias ls), get, create, update, delete | | time-blocks | list (alias ls), get, create, update, delete | | time-entries | list (alias ls), start, stop | | statuses | list (alias ls) | | users | list (alias ls) |

Bulk mutations use toggl <resource> bulk <verb>; see toggl tasks bulk --help.

Global flags (placed before the command path):

| Flag | Description | | --------------------- | ------------------------------------------------------------- | | --json | Pretty-printed JSON output (easier to pipe than human tables) | | --workspace-id <id> | Override the active workspace for this call | | --profile <name> | Use a named auth profile |

Per-command flags on generated operations always include --data, --data-file, and --dry-run. --interactive / --no-interactive appear only when the operation’s catalog metadata allows interactive prompting (read-only operations default to non-interactive unless marked otherwise). Interactive prompting requires a TTY and is disabled when you pass --json, --data, --data-file, CI, or TOGGL_NON_INTERACTIVE.

To see scalar flags for an operation, use toggl <group> … <command> --help. To print the resolved operation id and validated body without calling the API, use --dry-run.

Providing input

There are three ways to pass the request body:

1. Scalar flags

Each input field maps to a --field-name flag. Numeric values are coerced automatically.

toggl tasks get --task-id 12345
toggl tasks list --project-id 999 --status-id 111222
toggl time-entries list --date-from 2025-01-01 --date-to 2025-01-07
toggl time-entries start --task-id 12345 --type activity

For update commands, payload fields use a --payload-<field> prefix:

toggl tasks update --task-id 12345 --payload-name "New name" --payload-status-id 456789
toggl projects update --project-id 999 --payload-name "Renamed"

2. --data inline JSON

Pass the full input as a JSON string:

toggl tasks list --data '{"project_id": 123456, "per_page": 50}'
toggl tasks create --data '{"name": "Fix login bug", "project_id": 123456}'
toggl tasks update --data '{"task_id": 12345, "payload": {"name": "Updated", "status_id": 456789}}'

3. --data - (stdin) or --data-file <path>

Read JSON from stdin or a file:

echo '{"task_id": 12345}' | toggl tasks get --data -
toggl tasks create --data-file ./new-task.json

Output and errors

• Successful output goes to stdout as JSON (pretty-printed; --json keeps JSON while skipping human-oriented formatting helpers).
• Validation errors and API errors go to stderr.
• Exit code 0 on success, 1 on error.

Safety flags

--dry-run

Preview the resolved input without making an API call. Output includes dry_run: true, the operation ID, and the validated input object:

toggl tasks delete --task-id 12345 --dry-run
# {"dry_run":true,"operation":"focus.tasks.delete","input":{"task_id":12345}}

--yes (destructive operations)

delete commands require --yes to execute. Omitting it prints an error to stderr:

toggl tasks delete --task-id 12345 --yes
toggl projects delete --project-id 999 --yes
toggl time-blocks delete --task-id 12345 --time-block-id 67890 --yes

Examples

Tasks

# List all tasks in a project
toggl tasks list --project-id 123456

# Get a single task
toggl tasks get --task-id 12345

# Create a task
toggl tasks create --data '{"name": "Write release notes", "project_id": 123456}'

# Move task to "In Progress"
toggl tasks update --task-id 12345 --payload-status-id 456789

# Delete a task (requires --yes)
toggl tasks delete --task-id 12345 --yes

Projects

toggl projects list
toggl projects get --project-id 123456
toggl projects create --data '{"name": "Q3 Planning", "workspace_id": 789012}'
toggl projects update --project-id 123456 --payload-name "Q3 Planning (archived)"
toggl projects delete --project-id 999 --yes

Time entries

# List time entries for a week
toggl time-entries list --date-from 2025-01-01 --date-to 2025-01-07

# Start tracking (defaults type to 'activity')
toggl time-entries start --task-id 12345

# Start a break
toggl time-entries start --type break

# Stop the running timer
toggl time-entries stop

Time blocks

# List scheduled blocks for a week
toggl time-blocks list --date-from 2025-01-01 --date-to 2025-01-07

# Create a time block
toggl time-blocks create --data '{
  "task_id": 12345,
  "payload": {"start": "2025-01-06T09:00:00Z", "end": "2025-01-06T11:00:00Z"}
}'

# Delete a time block
toggl time-blocks delete --task-id 12345 --time-block-id 67890 --yes

Reference data

# List workspace statuses (useful for getting status IDs)
toggl statuses list

# List workspace members (useful for getting user IDs)
toggl users list

Dates

--date-from and --date-to accept:

• YYYY-MM-DD — expanded to T00:00:00Z (from) or T23:59:59Z (to)
• RFC 3339 datetime — used as-is (e.g. 2025-01-01T08:00:00+02:00)

Troubleshooting

Not authenticated

Not authenticated. Run `toggl auth` to sign in.

Run toggl auth. Credentials are stored in ~/.toggl/focus-tools.json. If you previously authenticated with an older version, your session at ~/.toggl-focus-mcp/config.json is still read automatically.

Invalid JSON from --data

Invalid JSON from --data: Unexpected token ...

Verify your JSON is well-formed. Use --data-file with a file if quoting is difficult in your shell.

Validation error

Invalid input: date_from: must be YYYY-MM-DD or RFC3339 datetime

Check field names and types. Use --dry-run to validate input without executing.

Debug API responses

TOGGL_DEBUG=1 toggl tasks list

Prints schema validation warnings from API responses to stderr.

License

Proprietary Toggl software. See LICENSE and Toggl legal terms.