npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

toggl-jira-sync

v1.3.0

Published

CLI tool to sync Toggl Track time entries to Jira work logs

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Git

Maintainers

fandassonfandasson

Keywords

toggljiratime-trackingcli

Readme

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="[email protected]" \
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="[email protected]"
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.