punchout takes the suck out of logging time on JIRA.
homebrew:
brew install dhth/tap/punchoutgo:
go install github.com/dhth/punchout@latestpunchout takes the suck out of logging time on JIRA.
Usage:
punchout [flags]
punchout [command]
Available Commands:
help Help about any command
mcp Interact with punchout's MCP server
Flags:
--config-file-path string location of punchout's config file (default "~/.config/punchout/punchout.toml")
--db-path string location of punchout's local database (default "~/punchout.v1.db")
--fallback-comment string fallback comment to use for worklog entries
-h, --help help for punchout
--jira-installation-type string JIRA installation type; allowed values: [cloud, onpremise]
--jira-time-delta-mins string time delta (in minutes) between your timezone and the timezone of the JIRA server; can be +/-
--jira-token string jira token (PAT for on-premise installation, API token for cloud installation)
--jira-url string URL of the JIRA server
--jira-username string username for authentication (for cloud installation)
--jql string JQL to use to query issues
--list-config print the config that punchout will use
punchout can receive its configuration via command line flags, or a config
file.
Create a toml file that looks like the following. The default location for this
file is ~/.config/punchout/punchout.toml. The configuration needed for
authenticating against your JIRA installation (on-premise or cloud) will depend
on the kind of the installation.
[jira]
jira_url = "https://jira.company.com"
# for on-premise installations
installation_type = "onpremise"
jira_token = "your personal access token"
# for cloud installations
installation_type = "cloud"
jira_token = "your API token"
jira_username = "[email protected]"
# put whatever JQL you want to query for
jql = "assignee = currentUser() AND updatedDate >= -14d ORDER BY updatedDate DESC"
# I don't know how many people will find use for this.
# I need this, since the JIRA on-premise server I use runs 5 hours behind
# the actual time, for whatever reason 🤷
jira_time_delta_mins = 300
# this comment will be used for worklogs when you don't provide one; optional"
fallback_comment = "comment"Both the config file and the command line flags can be used in conjunction, but the latter will take precedence over the former.
punchout lets you add worklogs on JIRA in a two step approach.
- You record one or more worklogs locally
- You push all unsynced worklogs to your JIRA server
This can be done either via punchout's TUI or its MCP server.
Historical context:
punchout's TUI came first. It was faster to track time using it when compared to JIRA's website. When AI agents became a thing, I saw an opportunity to offload the tedious work of creating worklogs to them by the means of the Model Context Protocol. These days, I exclusively use the MCP server as it's way faster than manually creating worklogs (demo below).
punchout comes with an MCP server which can allow you to automate the process
of recording worklogs and syncing them to your JIRA server. The server provides
5 tools:
| Tool | What it does |
|---|---|
get_jira_issues |
Return JIRA issues based on JQL configured |
add_worklog |
Record a worklog for an issue in punchout's database |
add_multiple_worklogs |
Record multiple worklogs in punchout's database |
get_unsynced_worklogs |
Get unsynced worklogs from punchout's database |
sync_worklogs_to_jira |
Sync all unsynced worklogs to JIRA |
You can leverage this MCP server in any way you want. I use it as follows:
Before MCP was a thing, the primary way to interact with punchout was through
its TUI. It's still an option for those who prefer it.
punchout Reference Manual
punchout has 5 panes:
- 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 View You enter/update a worklog entry from here
- Synced Worklog Entry View You view the worklog entries synced to JIRA
- Help View (this one)
Keyboard Shortcuts
General
1 Switch to Issues List View
2 Switch to Worklog List View
3 Switch to Synced Worklog List View
<tab> Go to next view/form entry
<shift+tab> Go to previous view/form entry
q/<ctrl+c> Go back/reset filtering/quit
<esc> Cancel form/quit
? Show help view
General List Controls
k/<Up> Move cursor up
j/<Down> Move cursor down
h<Left> Go to previous page
l<Right> Go to next page
/ Start filtering
Issue List View
s Toggle recording time on the currently selected issue,
will open up a form to record a comment on the second
"s" keypress
S Quick switch recording; will save a worklog entry without
a comment for the currently active issue, and start
recording time for another issue
<ctrl+s> Update active worklog entry (when tracking active), or add
manual worklog entry (when not tracking)
<ctrl+t> Go to currently tracked item
<ctrl+x> Discard currently active recording
<ctrl+b> Open issue in browser
Worklog List View
<ctrl+s>/u Update worklog entry
<ctrl+d> Delete worklog entry
s Sync all visible entries to JIRA
<ctrl+r> Refresh list
Worklog Entry View
enter Save worklog entry
k Move timestamp backwards by one minute
j Move timestamp forwards by one minute
K Move timestamp backwards by five minutes
J Move timestamp forwards by five minutes
h Move timestamp backwards by a day
l Move timestamp forwards by a day
Synced Worklog Entry View
<ctrl+r> Refresh list
punchout's TUI is built using bubbletea.