Toggl-Jira Sync CLI

A CLI tool to sync time entries from Toggl Track to Jira work logs. Created together with Claude code.

Features

• Fetches time entries from Toggl Track for a specific workspace and project
• Extracts Jira issue IDs from time entry descriptions (e.g., "ABC-123: Working on feature")
• Daily aggregation - Groups time entries by Jira issue AND date for better time visibility
• Detailed time breakdowns - Each work log shows when work was done throughout the day
• Shows summary of time entries with and without Jira issues
• Creates work logs in Jira with confirmation prompt
• Dry-run mode to preview changes without creating work logs
• Remembers synced entries - Automatically ignores already synced Toggl records
• Sync history management - View statistics and clear history when needed

Installation

From npm (recommended)

npm install -g toggl-jira-sync

Set environment Variables

Provide configuration via environment variables. See the configuration section below to know how to get them.

# Run with all required environment variables
TOGGL_API_TOKEN="your-toggl-token" \
TOGGL_WORKSPACE_ID="workspace-id" \
TOGGL_PROJECT_ID="project-id" \
JIRA_API_TOKEN="your-jira-token" \
JIRA_EMAIL="your-email@example.com" \
JIRA_DOMAIN="your-domain.atlassian.net" \
toggl-jira-sync

# Or export them first
export TOGGL_API_TOKEN="your-toggl-token"
export TOGGL_WORKSPACE_ID="workspace-id"
export TOGGL_PROJECT_ID="project-id"
export JIRA_API_TOKEN="your-jira-token"
export JIRA_EMAIL="your-email@example.com"
export JIRA_DOMAIN="your-domain.atlassian.net"
toggl-jira-sync

From source

1. Clone this repository
2. Install dependencies:

   pnpm install

3. Create a .env file based on .env.example:

   cp .env.example .env

4. Fill in your API credentials in the .env file

Configuration

Toggl API Token

1. Go to https://track.toggl.com/profile
2. Scroll down to "API Token" section
3. Copy your API token

Toggl Workspace and Project IDs

1. In Toggl Track, navigate to your workspace
2. The workspace ID is in the URL: https://track.toggl.com/[WORKSPACE_ID]/...
3. Click on a project to see its ID in the URL

Jira API Token

1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
2. Create non-scoped token as scoped tokens doesn't work for bug in JIRA API
3. Create a new scoped API token with the following scopes:
   • read:jira-work
   • write:jira-work
   • read:issue-worklog:jira
   • write:issue-worklog:jira
   • read:issue-worklog.property:jira
   • write:issue-worklog.property:jira
4. Copy the token value

Usage

Sync today's entries

# If installed globally via npm
toggl-jira-sync

# If running from source
node src/index.js sync

Sync specific date range

# If installed globally via npm
toggl-jira-sync --from 2024-01-01 --to 2024-01-31

# If running from source
node src/index.js sync --from 2024-01-01 --to 2024-01-31

Dry run (preview without creating work logs)

# If installed globally via npm
toggl-jira-sync --dry-run

# If running from source
node src/index.js sync --dry-run

Show configuration

# If installed globally via npm
toggl-jira-sync config

# If running from source
node src/index.js config

Manage sync history

# View sync history statistics
toggl-jira-sync history:view  # (or node src/index.js history:view from source)

# Clear all sync history (requires confirmation)
toggl-jira-sync history:clear  # (or node src/index.js history:clear from source)

How it works

1. The tool fetches time entries from Toggl for the specified date range
2. It filters out entries that have already been synced (stored in local ~/.toggl-jira-history.json)
3. It parses each remaining entry's description looking for Jira issue keys (e.g., ABC-123)
4. Entries with Jira keys are grouped by issue AND date for daily aggregation
5. A summary table is displayed showing:
   • Already synced entries (ignored)
   • Work logs to be created in Jira (grouped by issue/date with entry count)
   • Time entries without Jira issue keys
   • Total time breakdown
6. You're prompted to confirm before creating work logs in Jira
7. Work logs are created with detailed time breakdowns showing when work happened
8. Successfully synced entries are saved to local history to prevent re-syncing

Work Log Format in Jira

Each work log includes a detailed breakdown of your time entries:

Time breakdown for 3 entries:

• 09:00-09:30 (30m): Morning standup and planning
• 10:15-11:00 (45m): Bug investigation and analysis  
• 14:00-15:15 (1h 15m): Implementation and testing

Total: 2h 30m

This preserves the exact timing of when work was performed, making time tracking more accurate and transparent.

Testing

Run tests:

pnpm test

Jira Issue Key Format

The tool recognizes Jira issue keys in the format: [A-Z][A-Z0-9]+-\d+

Examples:

• ABC-123
• PROJ-4567
• TEST-1

The issue key can appear anywhere in the description.

Troubleshooting

Jira API Errors

If you encounter "400 Bad Request" errors when creating work logs:

1. Verify Issue Access: Make sure the Jira issue exists and you have permission to log work on it

2. Check Issue Status: Some Jira workflows prevent work logging on closed or certain status issues

3. Date Format Issues: The tool automatically formats dates to ISO format (e.g., 2024-01-01T10:30:00.000Z) which should work with all Jira instances

4. Test with Dry Run: Use --dry-run flag first to verify the tool can fetch and parse your Toggl entries correctly

Common Issues

• "No time entries found": Check your Toggl workspace and project IDs in the .env file
• "Missing required environment variables": Ensure all required variables are set in your .env file
• Permission errors: Verify your API tokens have the necessary scopes and permissions

Note on Sync History

The tool automatically tracks synced entries in ~/.toggl-jira-history.json to prevent duplicate work logs. This file is gitignored and stays local to your machine. You can safely run the sync multiple times without worrying about creating duplicate entries in Jira.