punchout takes the suck out of logging time on JIRA.

💾 Installation

Pre-built binaries

Download a pre-built binary from the latest release. See Verifying release artifacts for instructions on verifying your download.

Install from source

You can also install from source using the go toolchain:

go install github.com/dhth/punchout@latest

🧭 Tour

New to punchout? Run the interactive tour:

punchout tour

The tour introduces punchout’s worklog workflow, main TUI views and controls, MCP server, and configuration. It does not require a configuration file.

⚡️ Quick start

Create a configuration file if you do not already have one:

mkdir -p ~/.config/punchout
punchout config show-sample > ~/.config/punchout/punchout.toml

Edit the generated file with your JIRA details, then validate it and start the TUI:

punchout config validate
punchout

>_ Commands

Run punchout <command> --help for details about a particular command.

🔄 Workflow

punchout lets you add worklogs to JIRA in two steps:

1. Record one or more worklogs locally.
2. Push all unsynced worklogs to JIRA.

You can do this through either the TUI or the MCP server.

⚙️ Configuration

punchout reads configuration from ~/.config/punchout/punchout.toml by default. Authentication settings differ between JIRA Cloud and on-premise installations.

# String configuration values can reference environment variables. Referenced
# variables need to be set before running punchout.

# Optional. Defaults to punchout's standard database path.
# db_path = "$SOME_ENV_VAR/punchout.db"

[jira]
# Optional. Defaults to "onpremise". Allowed values: "onpremise", "cloud".
installation_type = "onpremise"

jira_url = "https://jira.company.com"
jira_token = "$PUNCHOUT_JIRA_TOKEN"

# For cloud installations, set installation_type to "cloud", use an API token,
# and provide a username.
# jira_username = "example@example.com"

# Put whatever JQL you want to use to query issues.
jql = "assignee = currentUser() AND updatedDate >= -14d ORDER BY updatedDate DESC"

# Optional. Time difference, in minutes, between your timezone and the JIRA
# server's timezone. Defaults to 0.
# jira_time_delta_mins = 300

# Optional. Used for worklogs when you do not provide a comment.
# fallback_comment = "work"

[tui]
# Optional. Defaults to false.
# use_cache_on_startup = true

# Optional. Defaults to "gruvbox-dark-hard".
# theme = "tokyonight"

[mcp]
# Optional. Defaults to "stdio". Allowed values: "stdio", "http".
# transport = "http"

# Optional. Used when transport is "http". Defaults to 18899.
# http_port = 9999

Command-line flags override values from the configuration file. Use a different file with --config-file-path, or inspect the resolved configuration with --list-config; JIRA tokens are redacted from that output.

Successful JIRA issue fetches are saved to a local cache. Set use_cache_on_startup to true to start with the most recently cached issues instead of immediately querying JIRA. Press <ctrl+r> from the issues list to fetch the latest issues and update the cache. If the cache is unavailable, punchout falls back to querying JIRA.

🖥️ TUI

punchout’s TUI lets you log time against JIRA issues and sync worklogs to JIRA. You can track time as you work or add worklogs manually.

The TUI has 5 primary views:

• Issues List View — Shows you issues matching your JQL query
• Worklog List View — Shows you your worklog entries; you sync these entries to JIRA from here
• Worklog Entry/Update View — You enter/update a worklog entry from here
• Synced Worklog List View — You view the worklog entries synced to JIRA here
• Help View — Shows available keymaps (as listed below)

Keyboard Shortcuts

General

General List Controls

Issue List View

Worklog List View

Worklog Entry/Update View

Synced Worklog List View

Themes

punchout’s TUI comes with several built-in themes. You can see them in action by pressing [ or ]. Here is a sampling of 4 built-in themes.

Theme	Preview
catppuccin-mocha
monokai-classic
rose-pine-moon
gruvbox-light

🔌 MCP Server

punchout comes with an MCP server which allows you to automate the process of recording worklogs and syncing them to your JIRA server.

The server uses stdio by default:

punchout mcp serve

It can also use Streamable HTTP:

punchout mcp serve --transport http --http-port 18899

The HTTP server listens on 127.0.0.1, exposes the MCP endpoint at /v1, and provides a health check at /health. Transport and port can also be set in the [mcp] section of the configuration file.

The server provides five tools:

Here’s one way the MCP server can be used:

🔐 Verifying release artifacts

Each release includes checksums for all artifacts. The checksum file is signed using cosign (version 3.1.3).

Replace x.y.z below with the release version you want to verify.

1. Get the checksum and cosign signature from the release:

   curl -sSLO https://github.com/dhth/punchout/releases/download/vx.y.z/punchout_x.y.z_checksums.txt
   curl -sSLO https://github.com/dhth/punchout/releases/download/vx.y.z/punchout_x.y.z_checksums.txt.sigstore.json
   

2. Verify the checksum file’s signature:

   cosign verify-blob \
       --bundle punchout_x.y.z_checksums.txt.sigstore.json \
       --certificate-identity-regexp 'https://github\.com/dhth/punchout/\.github/workflows/.+' \
       --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
       punchout_x.y.z_checksums.txt
   

3. Download the archive for your platform and validate its checksum. For example, for Linux x86-64:

   curl -sSLO https://github.com/dhth/punchout/releases/download/vx.y.z/punchout_x.y.z_linux_amd64.tar.gz
   sha256sum --ignore-missing -c punchout_x.y.z_checksums.txt
   

4. Once both checks pass, extract the archive:

   tar -xzf punchout_x.y.z_linux_amd64.tar.gz
   ./punchout -h
   

Changelog

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

v1.5.0 - Sep 05, 2026

Added

• Built-in themes
• Support loading cached JIRA issues when starting the TUI
• Support configuring database path, TUI settings, and MCP settings in config file
• A guided introduction to punchout’s main features, available via punchout tour
• Command to validate configuration (punchout config validate)
• Command to show sample configuration (punchout config show-sample)
• Support for MCP protocol version 2026-07-28

Changed

• Change default TUI theme to gruvbox-dark-hard
• Limit concurrent JIRA requests when syncing worklogs
• Worklog lists now show issue summaries for entries without comments
• Show days in worklog durations
• Expand environment variables in all string configuration attributes
• Redact JIRA tokens in --list-config output

Removed

• Publishing new releases via Homebrew

Fixed

• Show the correct begin timestamp for an active worklog after restarting punchout

v1.4.0 - Mar 17, 2026

Fixed

• Fetching issues from cloud installations (which broke due to deprecation of the underlying JIRA API)

v1.3.0 - Dec 24, 2025

Added

• An MCP server that allows for creating worklogs and syncing them to JIRA
• Allow syncing worklog timestamps with each other in workflow create/edit form
• Show time duration being recorded in workflow create/edit form
• Allow quickly finishing a worklog (ends worklog at current time, doesn’t ask for comment)

v1.2.0 - Jan 16, 2025

Added

• Allow for quickly switching actively tracked issue
• Add support for fallback comments
• Allow updating active worklog entry
• Add support for JIRA Cloud installation
• Allow shifting timestamps for worklog entries using h/j/k/l/J/K
• Show time spent on unsynced worklog entries

Changed

• Save UTC timestamps in the database
• Allow going back views instead of quitting directly
• Improved error handling
• Upgrade to go 1.23.4
• Dependency upgrades

v1.1.0 - Jul 2, 2024

Added

• Allow tweaking time when saving worklog
• Add first time help, “tracking started since” indicator
• Show indicator for currently tracked item
• Show unsynced count
• Add more colors for issue type
• Dependency upgrades