Install

homebrew:

brew install dhth/tap/punchout

go:

go install github.com/dhth/punchout@latest

⚡️ Usage

punchout can receive its configuration via command line flags, or a config file.

Using 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 = "example@example.com"

# 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"

Basic usage

Use punchout -h for help.

punchout \
    -db-path='/path/to/punchout/db/file.db' \
    -jira-url='https://jira.company.com' \
    -jira-installation-type 'onpremise' \
    -jira-token='XXX' \
    -jql='assignee = currentUser() AND updatedDate >= -14d ORDER BY updatedDate DESC'

punchout \
    -db-path='/path/to/punchout/db/file.db' \
    -jira-url='https://jira.company.com' \
    -jira-installation-type 'cloud' \
    -jira-token='XXX' \
    -jira-username='example@example.com' \
    -jql='assignee = currentUser() AND updatedDate >= -14d ORDER BY updatedDate DESC'

Both the config file and the command line flags can be used in conjunction, but the latter will take precedence over the former.

punchout \
    -config-file-path='/path/to/punchout/config/file.toml' \
    -jira-token='XXX' \
    -jql='assignee = currentUser() AND updatedDate >= -14d ORDER BY updatedDate DESC'

Screenshots

Screen 1

Screen 2

Screen 3

Screen 4

📋 Reference Manual

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

Acknowledgements

punchout is built using the awesome TUI framework bubbletea.

Changelog

All notable changes to this project will be documented in this file.

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

Unreleased

Added

Worklog entry/update view: allow syncing worklog timestamps with each other

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