Can I use Toggl as a CLI?

Yes. KosmoKrator exposes a Toggl CLI through kosmo integrations:call and the provider shortcut command. Commands can return JSON for scripts, CI, and coding agents.

Can I expose Toggl through MCP?

Yes. The KosmoKrator MCP gateway can expose selected Toggl tools to clients such as Claude Code, Cursor, Codex, and other MCP-compatible tools.

Where are Toggl credentials stored?

Toggl credentials are configured in KosmoKrator's local integration settings and reused by CLI, Lua, and MCP gateway surfaces.

Can I deny write access for Toggl MCP tools?

Yes. Start the gateway with --write=deny for read-only clients, or use ask/allow only for trusted workspaces.

productivity

Toggl CLI for AI Agents

Use the Toggl CLI from KosmoKrator to call Toggl tools headlessly, return JSON, inspect schemas, and automate workflows from coding agents, scripts, and CI.

Toggl CLI Setup

Toggl can be configured headlessly with `kosmokrator integrations:configure toggl`.

Install, configure, and verify

# Install KosmoKrator first if it is not available on PATH.
curl -fsSL https://raw.githubusercontent.com/OpenCompanyApp/kosmokrator/main/install.sh | bash

# Configure and verify this integration.
kosmokrator integrations:configure toggl --set api_token="$TOGGL_API_TOKEN" --enable --read allow --write ask --json
kosmokrator integrations:doctor toggl --json
kosmokrator integrations:status --json

Credentials

Authentication type: API token api_token. Configure credentials once, then reuse the same stored profile from scripts, coding CLIs, Lua, and MCP.

Key	Env var	Type	Required	Label
`api_token`	`TOGGL_API_TOKEN`	Secret `secret`	yes	API Token
`url`	`TOGGL_URL`	URL `url`	no	API Base URL

Command Patterns

The generic command is stable across every integration. The provider shortcut is shorter for humans.

Generic CLI call

kosmo integrations:call toggl.toggl_create_time_entry '{"workspace_id":"example_workspace_id","description":"example_description","start":"example_start","stop":"example_stop","duration":1,"project_id":"example_project_id","tags":"example_tags"}' --json

Provider shortcut

kosmo integrations:toggl toggl_create_time_entry '{"workspace_id":"example_workspace_id","description":"example_description","start":"example_start","stop":"example_stop","duration":1,"project_id":"example_project_id","tags":"example_tags"}' --json

Discovery

These commands return structured output for coding agents that need to inspect capabilities before choosing a function.

Discovery commands

kosmo integrations:docs toggl --json
kosmo integrations:docs toggl.toggl_create_time_entry --json
kosmo integrations:schema toggl.toggl_create_time_entry --json
kosmo integrations:search "Toggl" --json
kosmo integrations:list --json

Automation Contexts

The same configured command surface works in these environments. The command does not change unless the host wrapper, credentials, or permissions change.

CI Run integration calls from CI jobs with JSON output, explicit credentials, and predictable exit status. Cron Jobs Schedule repeatable integration workflows from cron while keeping credentials in KosmoKrator config. Shell Scripts Call integration functions from shell scripts with stable JSON input and output. Headless Automation Use KosmoKrator as a non-interactive integration runtime for local automations and wrappers. Coding Agents Let coding agents discover schemas and execute integration functions through CLI commands or MCP.

CLI Functions

Every function below can be called headlessly. Commands are highlighted, copyable, and scroll horizontally when payloads are long.

`toggl.toggl_create_time_entry`

Create a new time entry in a Toggl workspace. Provide a description, start time, and optionally a project and stop time.

Write write

Parameters: workspace_id, description, start, stop, duration, project_id, tags

Generic call

kosmo integrations:call toggl.toggl_create_time_entry '{"workspace_id":"example_workspace_id","description":"example_description","start":"example_start","stop":"example_stop","duration":1,"project_id":"example_project_id","tags":"example_tags"}' --json

Shortcut

kosmo integrations:toggl toggl_create_time_entry '{"workspace_id":"example_workspace_id","description":"example_description","start":"example_start","stop":"example_stop","duration":1,"project_id":"example_project_id","tags":"example_tags"}' --json

`toggl.toggl_get_current_user`

Get the authenticated Toggl user profile. Use this to verify your API token is working.

Read read

Parameters: none

Generic call

kosmo integrations:call toggl.toggl_get_current_user '{}' --json

Shortcut

kosmo integrations:toggl toggl_get_current_user '{}' --json

`toggl.toggl_get_project`

Get details for a single Toggl project by ID.

Read read

Parameters: workspace_id, project_id

Generic call

kosmo integrations:call toggl.toggl_get_project '{"workspace_id":"example_workspace_id","project_id":"example_project_id"}' --json

Shortcut

kosmo integrations:toggl toggl_get_project '{"workspace_id":"example_workspace_id","project_id":"example_project_id"}' --json

`toggl.toggl_get_time_entry`

Get details for a single Toggl time entry by ID.

Read read

Parameters: time_entry_id

Generic call

kosmo integrations:call toggl.toggl_get_time_entry '{"time_entry_id":"example_time_entry_id"}' --json

Shortcut

kosmo integrations:toggl toggl_get_time_entry '{"time_entry_id":"example_time_entry_id"}' --json

`toggl.toggl_list_projects`

List projects in a Toggl workspace. Optionally filter for active projects only.

Read read

Parameters: workspace_id, active

Generic call

kosmo integrations:call toggl.toggl_list_projects '{"workspace_id":"example_workspace_id","active":true}' --json

Shortcut

kosmo integrations:toggl toggl_list_projects '{"workspace_id":"example_workspace_id","active":true}' --json

`toggl.toggl_list_time_entries`

List recent Toggl time entries. Optionally filter by date range.

Read read

Parameters: start_date, end_date

Generic call

kosmo integrations:call toggl.toggl_list_time_entries '{"start_date":"example_start_date","end_date":"example_end_date"}' --json

Shortcut

kosmo integrations:toggl toggl_list_time_entries '{"start_date":"example_start_date","end_date":"example_end_date"}' --json

`toggl.toggl_list_workspaces`

List all Toggl workspaces the authenticated user belongs to. Returns workspace IDs and names needed for other Toggl tools.

Read read

Parameters: none

Generic call

kosmo integrations:call toggl.toggl_list_workspaces '{}' --json

Shortcut

kosmo integrations:toggl toggl_list_workspaces '{}' --json

`toggl.toggl_create_project`

Create a new project in a Toggl Track workspace.

Write write

Parameters: workspace_id, name, color, billable, is_private, active, estimated_hours, client_id

Generic call

kosmo integrations:call toggl.toggl_create_project '{"workspace_id":1,"name":"example_name","color":"example_color","billable":true,"is_private":true,"active":true,"estimated_hours":1,"client_id":1}' --json

Shortcut

kosmo integrations:toggl toggl_create_project '{"workspace_id":1,"name":"example_name","color":"example_color","billable":true,"is_private":true,"active":true,"estimated_hours":1,"client_id":1}' --json

`toggl.toggl_update_time_entry`

Update an existing time entry in Toggl Track. Use this to edit description, times, project, tags, or billable status.

Write write

Parameters: workspace_id, time_entry_id, description, start, stop, duration, project_id, task_id, tags, tag_ids, billable

Generic call

kosmo integrations:call toggl.toggl_update_time_entry '{"workspace_id":1,"time_entry_id":1,"description":"example_description","start":"example_start","stop":"example_stop","duration":1,"project_id":1,"task_id":1}' --json

Shortcut

kosmo integrations:toggl toggl_update_time_entry '{"workspace_id":1,"time_entry_id":1,"description":"example_description","start":"example_start","stop":"example_stop","duration":1,"project_id":1,"task_id":1}' --json

`toggl.toggl_delete_time_entry`

Delete a time entry from Toggl Track. This action is permanent and cannot be undone.

Write write

Parameters: workspace_id, time_entry_id

Generic call

kosmo integrations:call toggl.toggl_delete_time_entry '{"workspace_id":1,"time_entry_id":1}' --json

Shortcut

kosmo integrations:toggl toggl_delete_time_entry '{"workspace_id":1,"time_entry_id":1}' --json

Function Schemas

Use these parameter tables when building CLI payloads without calling integrations:schema first.

toggl.toggl_create_time_entry 7 parameters

Schema command

kosmo integrations:schema toggl.toggl_create_time_entry --json

Parameter	Type	Required	Description
`workspace_id`	string	yes	The workspace ID.
`description`	string	no	Description of the time entry.
`start`	string	no	Start time (ISO 8601, e.g. "2026-04-05T09:00:00Z"). Defaults to now.
`stop`	string	no	Stop time (ISO 8601). Omit for a running timer.
`duration`	integer	no	Duration in seconds. Use -1 for a running timer (default: -1).
`project_id`	string	no	Project ID to assign the time entry to.
`tags`	array	no	Tags for the time entry.

toggl.toggl_get_current_user 0 parameters

Schema command

kosmo integrations:schema toggl.toggl_get_current_user --json

Parameter	Type	Required	Description
No parameters.

toggl.toggl_get_project 2 parameters

Schema command

kosmo integrations:schema toggl.toggl_get_project --json

Parameter	Type	Required	Description
`workspace_id`	string	yes	The workspace ID.
`project_id`	string	yes	The project ID.

toggl.toggl_get_time_entry 1 parameters

Schema command

kosmo integrations:schema toggl.toggl_get_time_entry --json

Parameter	Type	Required	Description
`time_entry_id`	string	yes	The time entry ID.

toggl.toggl_list_projects 2 parameters

Schema command

kosmo integrations:schema toggl.toggl_list_projects --json

Parameter	Type	Required	Description
`workspace_id`	string	yes	The workspace ID.
`active`	boolean	no	Filter for active projects only (default: true).

toggl.toggl_list_time_entries 2 parameters

Schema command

kosmo integrations:schema toggl.toggl_list_time_entries --json

Parameter	Type	Required	Description
`start_date`	string	no	Start date filter (ISO 8601 date, e.g. "2026-01-01").
`end_date`	string	no	End date filter (ISO 8601 date).

toggl.toggl_list_workspaces 0 parameters

Schema command

kosmo integrations:schema toggl.toggl_list_workspaces --json

Parameter	Type	Required	Description
No parameters.

toggl.toggl_create_project 8 parameters

Schema command

kosmo integrations:schema toggl.toggl_create_project --json

Parameter	Type	Required	Description
`workspace_id`	integer	yes	The workspace ID.
`name`	string	yes	Project name (e.g., "Website Redesign").
`color`	string	no	Project color as a hex code (e.g., "#0b83d9").
`billable`	boolean	no	Whether the project is billable. Defaults to false.
`is_private`	boolean	no	Whether the project is private. Defaults to false.
`active`	boolean	no	Whether the project is active. Defaults to true.
`estimated_hours`	number	no	Estimated hours for the project.
`client_id`	integer	no	Client ID to associate with the project.

toggl.toggl_update_time_entry 11 parameters

Schema command

kosmo integrations:schema toggl.toggl_update_time_entry --json

Parameter	Type	Required	Description
`workspace_id`	integer	yes	The workspace ID.
`time_entry_id`	integer	yes	The time entry ID to update.
`description`	string	no	Updated description.
`start`	string	no	Updated start time in ISO 8601 format.
`stop`	string	no	Updated stop time in ISO 8601 format.
`duration`	integer	no	Updated duration in seconds.
`project_id`	integer	no	Updated project ID.
`task_id`	integer	no	Updated task ID.
`tags`	array	no	Updated array of tag names.
`tag_ids`	array	no	Updated array of tag IDs.
`billable`	boolean	no	Updated billable status.

toggl.toggl_delete_time_entry 2 parameters

Schema command

kosmo integrations:schema toggl.toggl_delete_time_entry --json

Parameter	Type	Required	Description
`workspace_id`	integer	yes	The workspace ID.
`time_entry_id`	integer	yes	The time entry ID to delete.

Permissions

Headless calls still follow the integration read/write permission policy. Configure read/write defaults with integrations:configure. Add --force only for trusted automation that should bypass that policy.