About The Project

Minutes is a CLI tool for synchronizing work logs between multiple time trackers, invoicing, and bookkeeping software to make entrepreneurs' daily work easier. Every source and destination comes with their specific flags. Before using any flags, check the related documentation.

Minutes come with absolutely NO WARRANTY; before and after synchronizing any logs, please ensure you got the expected result.

Getting Started

Prerequisites

Based on the nature of the project, prerequisites depending on what tools you are using. In case you are using Clockify as a time tracker and Tempo as your sync target, you should have an account at Clockify and Jira.

Installation

Using brew

$ brew tap gabor-boros/brew
$ brew install minutes

Manual install

To install minutes, use one of the release artifacts. If you have go installed, you can build from source as well.

Configuration

minutes has numerous flags and there will be more when other sources or targets are added. Therefore, minutes comes with a config file, that can be placed to the user's home directory or the config directory.

To read more about the config file, please refer to the Documentation

Usage

Below you can find more information about how to use minutes.

Usage:
  minutes [flags]

Flags:
      --clockify-api-key string                set the API key
      --clockify-url string                    set the base URL (default "https://api.clockify.me")
      --clockify-workspace string              set the workspace ID
      --config string                          config file (default is $HOME/.minutes.yaml)
      --date-format string                     set start and end date format (in Go style) (default "2006-01-02 15:04:05")
      --dry-run                                fetch entries, but do not sync them
      --end string                             set the end date (defaults to now)
      --filter-client string                   filter for client name after fetching
      --filter-project string                  filter for project name after fetching
      --force-billed-duration                  treat every second spent as billed
      --harvest-account int                    set the Account ID
      --harvest-api-key string                 set the API key
  -h, --help                                   help for minutes
      --round-to-closest-minute                round time to closest minute
  -s, --source string                          set the source of the sync [clockify harvest tempo timewarrior toggl]
      --source-user string                     set the source user ID
      --start string                           set the start date (defaults to 00:00:00)
      --table-hide-column strings              hide table column [summary project client start end]
      --table-sort-by strings                  sort table by column [task summary project client start end billable unbillable] (default [start,project,task,summary])
      --tags-as-tasks-regex string             regex of the task pattern
  -t, --target string                          set the target of the sync [tempo]
      --target-user string                     set the source user ID
      --tempo-password string                  set the login password
      --tempo-url string                       set the base URL
      --tempo-username string                  set the login user ID
      --timewarrior-arguments strings          set additional arguments
      --timewarrior-client-tag-regex string    regex of client tag pattern
      --timewarrior-command string             set the executable name (default "timew")
      --timewarrior-project-tag-regex string   regex of project tag pattern
      --timewarrior-unbillable-tag string      set the unbillable tag (default "unbillable")
      --toggl-api-key string                   set the API key
      --toggl-workspace int                    set the workspace ID
      --version                                show command version

Usage examples

Depending on the config file, the number of flags can change.

Simplest command

# No arguments, no flags, just running the command
$ minutes

Set specific date and time

# Set the date and time to fetch entries in the given time frame
$ minutes --start "2021-10-07 00:00:00" --end "2021-10-07 23:59:59"

# Specify the start and end date format
$ minutes --date-format "2006-01-02" --start "2021-10-07" --end "2021-10-08"

Use tags for tasks

# Specify how a tag should look like to be considered as a task
$ minutes --tags-as-tasks-regex '[A-Z]{2,7}-\d{1,6}'

Minute based rounding

# Set the billed and unbilled time separately
# to round to the closest minute (even if it is zero)
$ minutes --round-to-closest-minute

Sample config file

# Source config
source = "clockify"
source-user = "<clockify user ID>"

clockify-url = "https://api.clockify.me"
clockify-api-key = "<clockify API token>"
clockify-workspace = "<clockify workspace ID>"

# Target config
target = "tempo"
target-user = "<jira username>"

tempo-url = "https://<org>.atlassian.net"
tempo-username = "<jira username>"
tempo-password = "<jira password>"

# General config
tags-as-tasks-regex = '[A-Z]{2,7}-\d{1,6}'
round-to-closest-minute = true
force-billed-duration = true

table-sort-by = [
    "start",
    "project",
    "task",
    "summary",
]

table-hide-column = [
    "end"
]

[table-column-truncates]
summary = 40
project = 10
client = 10

# Column Config
[table-column-config.summary]
widthmax = 40

Supported tools

See the open issues for a full list of proposed features, tools and known issues.

Unsupported features

The following list of features are not supported at the moment:

• Cost rate sync
• Hourly rate sync
• Estimate sync
• Multiple source and target user support

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this tool better, please fork the repo and create a pull request. You can also simply open an issue. Don't forget to give the project a star!

1. Fork the Project
2. Create your Feature Branch (git checkout -b github-username/amazing-feature)
3. Commit your Changes (git commit -m 'feat(new tool): add my favorite tool as a source)
4. Push to the Branch (git push origin github-username/amazing-feature)
5. Open a Pull Request