Minutes is a CLI tool for synchronizing work logs between multiple time trackers, invoicing, and bookkeeping software to make entrepreneurs' daily work easier.

Contributors Forks Stargazers Issues MIT License Maintainability Coverage


Minutes

Sync worklogs between multiple time trackers, invoicing, and bookkeeping software.
Explore the docs

Bug report · Feature request

About The Project

minutes

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

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

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
  -h, --help                                   help for minutes
      --round-to-closest-minute                round time to closest minute
  -s, --source string                          set the source of the sync [clockify 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                          treat tags matching the value of tags-as-tasks-regex as tasks
      --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-url string                       set the base URL (default "https://api.track.toggl.com")
      --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 --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-url = "https://api.clockify.me"
clockify-api-key = "
   
    "
   
clockify-workspace = "
   
    "
   

# Target config
target = "tempo"
target-user = "
   
    "
   

tempo-url = "https://
   
    .atlassian.net
    "
   
tempo-username = "
   
    "
   
tempo-password = "
   
    "
   

# General config
tags-as-tasks = true
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

Tool Use as source Use as target
Clockify yes upon request
Everhour upon request upon request
FreshBooks upon request planned
Harvest upon request upon request
QuickBooks upon request upon request
Tempo yes yes
Time Doctor upon request upon request
TimeCamp upon request upon request
Timewarrior yes upon request
Toggl Track yes upon request
Zoho Books upon request planned

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
Owner
Gábor Boros
Passionate about web applications, clean code and architecture design.
Gábor Boros
Comments
  • refactor: update dependencies

    refactor: update dependencies

    Description

    Update dependencies and get rid of deprecated function calls. Also, this PR adds vulnerability checking to make lint

    Supporting information

    N/A

    Dependencies

    N/A

    Screenshots

    N/A

    Testing instructions

    N/A

    Other information

    N/A

    Checklist

    • [x] Documentation is updated
    • [x] Pull request is rebased onto main
    • [x] Commit history is clean
  • Fix Clockify tag handling

    Fix Clockify tag handling

    Description

    Using Clockify and the settings below, both Task and Summary columns' values are missing if no tag is set. This PR fixes that issue and a smaller hidden issue.

    Supporting information

    Fixes https://github.com/gabor-boros/minutes/issues/38

    Dependencies

    N/A

    Screenshots

    N/A

    Testing instructions

    1. create a new entry in Clockify with a title set, but no task or tags are assigned
    2. run minutes

    Other information

    N/A

    Checklist

    • [x] Documentation is updated
    • [x] Pull request is rebased onto main
    • [x] Commit history is clean
  • Rework tag parsing

    Rework tag parsing

    Description

    This PR refactors the way of tag parsing works and removes not needed arguments.

    Supporting information

    The tag parsing configuration was too verbose and did not add any extra value. By simplifying the tag parsing it is easier to maintain.

    Dependencies

    N/A

    Screenshots

    N/A

    Testing instructions

    1. Run minutes as without the remove config option

    Other information

    This PR unifies the empty regex checking as well.

    Checklist

    • [x] Documentation is updated
    • [x] Pull request is rebased onto main
    • [x] Commit history is clean
  • Fix multiple small issues

    Fix multiple small issues

    Description

    This PR fixes multiple smaller issues in the documentation, test command and CLI root.

    Supporting information

    Among many not reported issues, this patch fixes #34 as well.

    Dependencies

    N/A

    Screenshots

    N/A

    Testing instructions

    1. run tests
    2. read the doc changes

    Other information

    This PR should be cherry-picked to release/v0.2.x as well.

    Checklist

    • [x] Documentation is updated
    • [x] Pull request is rebased onto main
    • [x] Commit history is clean
  • feat: add Harvest as source

    feat: add Harvest as source

    Description

    This PR implements Harvest as a source.

    Supporting information

    Dependencies

    N/A

    Screenshots

    N/A

    Testing instructions

    1. Create an account on harvest
    2. Log time
    3. Configure minutes
    4. Run minutes with Harvest configuration
    5. Check the data is fetched and displayed in the overview

    Other information

    Harvest has no support for tags.

    Checklist

    • [x] Documentation is updated
    • [x] Pull request is rebased onto main
    • [x] Commit history is clean
  • Refactor client composition logic and remove unnecessary Toggl flag

    Refactor client composition logic and remove unnecessary Toggl flag

    Description

    This PR does a major refactor on how the client composition is done and simplify client logic. Besides that, this commit reduces the duplicated logic across clients and outsources the authentication setter.

    Additionally, it makes it easier to integrate new clients with more complex authentication methods, like Oauth2.

    Also, the commit contains a change that removes the illogical flag for setting Toggl Track client base URL, hence that never changes.

    Supporting information

    N/A

    Dependencies

    N/A

    Screenshots

    N/A

    Testing instructions

    • Run a fetch for every source
    • Run an upload for every target

    Other information

    This PR is kind of a requirement for integrating Zoho Books and other targets later on.

    Checklist

    • [x] Documentation is updated
    • [x] Pull request is rebased onto main
    • [x] Commit history is clean
  • feat: add filtering for projects and clients

    feat: add filtering for projects and clients

    Description

    This PR adds basic filtering on the "client" side, therefore it supports every source, even those that have no API to filter the result set returned by its API.

    Supporting information

    Resolves #1

    Dependencies

    N/A

    Screenshots

    N/A

    Testing instructions

    1. Run minutes using --filter-client and --filter-project flags
    2. Validate the displayed worklog are contains only those entries that are matching the filter regex.

    Other information

    Resolves #1

    Checklist

    • [x] Documentation is updated
    • [x] Pull request is rebased onto main
    • [x] Commit history is clean
  • Fix

    Fix "method_complexity" issue in cmd/root.go

    Function validateFlags has a Cognitive Complexity of 23 (exceeds 20 allowed). Consider refactoring.

    https://codeclimate.com/github/gabor-boros/minutes/cmd/root.go#issue_616de2ea2edb630001000037

  • Fix multiple quality issues

    Fix multiple quality issues

    Description

    This PR fixes a bunch of quality issues.

    Supporting information

    N/A

    Dependencies

    N/A

    Screenshots

    N/A

    Testing instructions

    • Run codeclimate

    Other information

    N/A

    Checklist

    • [x] Documentation is updated
    • [x] Pull request is rebased onto main
    • [x] Commit history is clean
  • Fix

    Fix "return_statements" issue in internal/pkg/client/clockify/clockify.go

    Method clockifyClient.FetchEntries has 5 return statements (exceeds 4 allowed).

    https://codeclimate.com/github/gabor-boros/minutes/internal/pkg/client/clockify/clockify.go#issue_616d28ced58640000100003a

  • Fix

    Fix "argument_count" issue in internal/pkg/client/client.go

    Function SendRequest has 5 arguments (exceeds 4 allowed). Consider refactoring.

    https://codeclimate.com/github/gabor-boros/minutes/internal/pkg/client/client.go#issue_616d28ced58640000100003b

  • [REQUEST] Usage telemetry

    [REQUEST] Usage telemetry

    Is your feature request related to a problem? Please describe.

    It is not visible how many users using what version of the app.

    Describe the solution you'd like

    Implement sending telemetry reports when the app starts. The telemetry should be optional and turned on by default. Also, the first start should warn the user about how to turn it off.

    Describe alternatives you've considered

    N/A

    Additional context

    N/A

  • [REQUEST] Update notifier

    [REQUEST] Update notifier

    Is your feature request related to a problem? Please describe.

    The fact of a new release is not shown when the app starts, hence it is harder to be informed about newer versions.

    Describe the solution you'd like

    Have a built-in mechanism for checking for newer versions at command start. The check should be optional and turned on by default.

    Describe alternatives you've considered

    N/A

    Additional context

    N/A

  • [REQUEST] Refactor sources and targets as plugins

    [REQUEST] Refactor sources and targets as plugins

    Is your feature request related to a problem? Please describe.

    Adding (and maintaining) more sources and targets would be harder over time and "pollutes" the core logic in some way.

    Describe the solution you'd like

    To have a more flexible and well separated structure, extract the sources and targets into plugins. This way the core logic would be somewhat simpler and sources/targets would be self-contained.

    Describe alternatives you've considered

    Additional context

  • [REQUEST] Parse tags from summary

    [REQUEST] Parse tags from summary

    Is your feature request related to a problem? Please describe.

    There are some sources that have no support for tags. In the case of these sources, like Harvest, the tags-as-tasks flag is not considered.

    Describe the solution you'd like

    Create a new flag and config option to parse tags from the Summary field of entries. Therefore, combining tags-as-tasks and the new flag would provide a similar user experience compared to sources that are supporting tags natively.

    The new flag should have a pair as well, which would stand for the regex used for parsing.

    An example call:

    minutes \
        --tags-in-summary \
        --tags-in-summary-regex '\[(\w+|\s+)+\]' \
        --tags-as-tasks \
        --tags-as-tasks-regex '[A-Z]{2,7}-\d{1,6}'
    

    Describe alternatives you've considered

    As an alternative tags-in-summary could replace tags-as-tasks. During the implementation it should be evaluated.

    Additional context

    N/A

  • [REQUEST] Upload data overrides

    [REQUEST] Upload data overrides

    Is your feature request related to a problem? Please describe.

    When uploading to a target, there is no way to override Client and Project parameters.

    Describe the solution you'd like

    In many cases, the target will have different Client and Project names compared to the source. For example, in the source (like Tempo) the Client is called "MC" (as per the AccountKey is "MC"), though in the target tool it is called "My Company", hence it will be printed on the invoice. In the case of Project names, the situation is similar.

    To eliminate this issue, create an override configuration, that can be configured per target. Why not source? Because sources have nothing to do with upload overrides.

    Describe alternatives you've considered

    N/A

    Additional context

    N/A

Related tags
A CLI tool for working with CloudWatch logs. It performs functions that I need at work.

CloudWatch Logs Utility A simple utility for working with CloudWatch Logs. AWS should probably build this themselves, but since they won't, I am here

Dec 31, 2021
Lightweight CLI tool to programmatically rescale your Hetzner virtual server daily to optimize your budget spending

Lightweight CLI tool to programmatically rescale your Hetzner virtual server daily to optimize your budget spending

Nov 28, 2022
Tnbassist - A CLI tool for thenewboston blockchain to perform various mundane tasks like taking daily accounts backup

TNB Assist is a CLI (Command Line Interface) tool for thenewboston blockchain to perform various mundane tasks like taking daily accounts backup, computing statistics, etc easier.

Feb 14, 2022
A simple CLI app to take notes daily on markdown file
A simple CLI app to take notes daily on markdown file

A simple CLI app to take notes daily on markdown file

Jul 29, 2022
a work time management CLI tool for any platform
a work time management CLI tool for any platform

english |日本語 jobgosh | job management tool made with golang for shell a multi-platform work time management CLI tool to track and improve your day to

May 16, 2022
Splasher is a tool to change desktop wallpaper random every 2 minutes from unsplash.

Splasher Splasher is a tool to change desktop wallpaper random every 2 minutes from unsplash. Download Latest Release: GitHub Release Installation & S

Jan 7, 2022
textnote is a command line tool for quickly creating and managing daily plain text notes.

textnote is a command line tool for quickly creating and managing daily plain text notes. It is designed for ease of use to encourage the practice of daily, organized note taking. textnote intentionally facilitates only the management (creation, opening, organizing, and consolidated archiving) of notes, following the philosophy that notes are best written in a text editor and not via a CLI.

Jan 2, 2023
A tiny command-line orientated PKM tool inspired by Taskwarrior and daily logging.

eden eden is a command line tool for creating and manipulating daily log notes. It started life as a series of different bash script that did various

Jan 20, 2022
CLI tool and library for generating a Software Bill of Materials from container images and filesystems
CLI tool and library for generating a Software Bill of Materials from container images and filesystems

A CLI tool and Go library for generating a Software Bill of Materials (SBOM) from container images and filesystems. Exceptional for vulnerability dete

Jan 6, 2023
Github-org-diff - Simple CLI tool to check a diff between 2 branches of all org repos

github-org-diff Simple CLI tool to list org repos that have diff between dev and

Jan 25, 2022
This package to make it easy to work with env

Go Env This package to make it easy to work with env Example usage package main

Jan 30, 2022
A tiny markup language for terminal output. Makes formatting output in CLI apps easier!
A tiny markup language for terminal output. Makes formatting output in CLI apps easier!

tml - Terminal Markup Language A Go module (and standalone binary) to make the output of coloured/formatted text in the terminal easier and more reada

Dec 14, 2022
Scrappy is a cli tool that allows multiple web scrappers to monitor periodically for a basic ruleset coverage and inform users when the criteria have been met.

Scrappy - A multi-type web scrapper with alerting Scrappy is a cli tool that allows multiple web scrappers to monitor periodically for a basic ruleset

Nov 7, 2021
PingMe is a CLI tool which provides the ability to send messages or alerts to multiple messaging platforms & email.
PingMe is a CLI tool which provides the ability to send messages or alerts to multiple messaging platforms & email.

PingMe is a personal project to satisfy my needs of having alerts, most major platforms have integration to send alerts but its not always useful, either you are stuck with one particular platform, or you have to do alot of integrations. I needed a small app which i can just call from my backup scripts, cron jobs, CI/CD pipelines or from anywhere to send a message with particular information. And i can ship it everywhere with ease. Hence, the birth of PingMe.

Dec 28, 2022
git-xargs is a command-line tool (CLI) for making updates across multiple Github repositories with a single command.
git-xargs is a command-line tool (CLI) for making updates across multiple Github repositories with a single command.

Table of contents Introduction Reference Contributing Introduction Overview git-xargs is a command-line tool (CLI) for making updates across multiple

Dec 31, 2022
CLI tool for manipulating GitHub Labels across multiple repositories

takolabel Installation Mac $ brew install tommy6073/tap/takolabel Other platforms Download from Releases page in this repository. Usage Set variables

Nov 3, 2022
git-xargs is a command-line tool (CLI) for making updates across multiple GitHub repositories with a single command
git-xargs is a command-line tool (CLI) for making updates across multiple GitHub repositories with a single command

git-xargs is a command-line tool (CLI) for making updates across multiple GitHub repositories with a single command. You give git-xargs:

Feb 5, 2022
Nebula Diagnosis CLI Tool is an information diagnosis cli tool for the nebula service and the node to which the service belongs.

Nebula Diagnosis CLI Tool is an information diagnosis cli tool for the nebula service and the node to which the service belongs.

Jan 12, 2022
It‘s a cmd-line tool like `make` and `task`, supporting nested args and alias using `cobra`

It‘s a cmd-line tool like `make` and `task`, supporting nested args and alias using `cobra`. It's a makefile alternative and a shell wrapper.

Oct 18, 2022