Tutorial: sync Toggl to Tempo

This is a tutorial for how to efficiently sync your worklogs from Toggl Track to Tempo in Jira, using Minutes.

Use the supported format for time logs.

First step is to check that your time logs in Toggl includes the required information. Minutes requires the following in Toggl time logs:

• A description.
• A tag which is the ticket ID (like BB-10447).
• A related project.
• The project must be linked to a client.

Install Minutes

Minutes is a command line application, that can be installed by downloading the release from GitHub at https://github.com/gabor-boros/minutes/releases. Find the latest release, and select the tar.gz file for your platform. For example, for a MacOS system with a x86_64 cpu, select minutes_Darwin_x86_64.tar.gz.

Download and extract this archive file, and look for the minutes file inside. This file is the Minutes application.

Configure Minutes

Minutes requires a configuration file. This file needs to be named .minutes.toml, and it should be in your home folder. Create this file and open it in a plain text editor.

Enter the following contents:

# Source config
source = "toggl"
source-user = "YOUR_TOGGL_USER_ID"

# Toggl config
# Free toggl plan supports the API, but only up to 30 requests per hour. This should be plenty for this tool. https://support.toggl.com/api-webhook-limits
toggl-api-key = "YOUR_TOGGL_API_KEY"
toggl-url = "https://api.track.toggl.com"
toggl-workspace = "YOUR_TOGGL_WORKSPACE_ID"

# Target config
target = "tempo"
# this is the internal Jira ID; usually the same as your username, but may be different if your username has been changed.
target-user = "YOUR_JIRA_USERNAME"

# Tempo config
tempo-url = "https://tasks.opencraft.com"
tempo-username = "YOUR_JIRA_USERNAME"
tempo-password = "YOUR_JIRA_PASSWORD"

# General config
tags-as-tasks-regex = '[A-Z]{2,7}-\d{1,6}'
round-to-closest-minute = true
force-billed-duration = true

# Optional: use this if you use your Toggl workspace for time logging unrelated to OpenCraft.
# This allows you to select time logs by Toggl project or client to upload as OpenCraft worklogs.
# filter-client = '.*'
# filter-project = '.*'

Fill in configuration placeholders

Now you need to fill in the placeholders above with real values. Jira username and password is simple: these are your usual credentials for logging into the OpenCraft Jira.

For the Toggl user ID, API key, and workspace ID, we need to go hunting. First, log in to Toggl Track on the web.

Then visit https://api.track.toggl.com/api/v9/me in the browser. You should see a data that looks something like this:

{
  "id": 12345678,
  "api_token": "deadbeef1234567890abcdefabcdef12",
  "email": "user@opencraft.com",
  "fullname": "User",
  "timezone": "Australia/Adelaide",
  "2fa_enabled": false,
  "toggl_accounts_id": "DEADBEEF1234567890BEEF",
  "default_workspace_id": 87654321,
  "beginning_of_week": 1,
  "image_url": "https://assets.track.toggl.com/images/profile.png",
  "created_at": "2026-02-01T00:00:00.000014Z",
  "updated_at": "2026-02-02T00:00:00.000017Z",
  "openid_email": null,
  "openid_enabled": true,
  "country_id": 14,
  "has_password": false,
  "at": "2026-02-03T00:00:00.000001Z",
  "oauth_providers": [
    "google"
  ],
  "authorization_updated_at": "2026-02-03T00:00:00.000000001Z"
}

From this, we can get the following required information:

• user id: the value of the "id" field: 12345678
• api key: the value of the "api_token" field: deadbeef1234567890abcdefabcdef12
• workspace ID: assuming you wish to use your default workspace, you can use the value of the "default_workspace_id" field: 87654321

If you have multiple Toggl workspaces, you can find the ID of the one you want by visiting https://api.track.toggl.com/api/v9/workspaces in the browser. The page will have a lot of data:

[
  {
    "id": 11111111,
    "organization_id": 12345678,
    "name": "My OpenCraft Workspace",
    "premium": true,
    ...
  },
  {
    "id": 22222222,
    "organization_id": 12345678,
    "name": "My Other Workspace",
    "premium": true,
    ...
  },
]

Select the value of the "id" field for the workspace you want to use, using the "name" field to find the workspace.

Run Minutes

This is where the actual worklog uploading happens. Since Minutes is a command line application, you will need to open a terminal in the directory where the minutes application is.

Then in the terminal, you can enter the ./minutes command, followed by a parameter with the "start" date - this is the date from which you wish to upload worklogs. For example, to upload all time logs since February 3, 2026:

./minutes --start "2026-02-03 00:00:00"

It will display a table of worklogs, and prompt you for confirmation to proceed with the upload.

Minutes is not idempotent: it can upload duplicate worklogs if you don't take care to check that the worklogs haven't already been uploaded. Be sure to check the start date and review the table of worklogs in Minutes before proceeding.

Example workflow

A simple workflow may be to run Minutes to upload worklogs at the end of every day you work. This may simplify figuring out when to set the start date and remembering which worklogs have already been uploaded.

In this case, you can use this shortcut command, which will automatically provide today's date to Minutes:

./minutes --start "$(date '+%F 00:00:00')"