This CLI tool is for a specific use case that I have.
I use Toggl Track for keeping track of what I am spending my time on while working. I'm not a contractor though, so I don't have any hard requirement to ensure every minute of my day is accounted for. I do need to know though how many hours in a day or week that I have have been on the clock for reporting purposes.
This tool will, for a day or a week, report on:
- booked time, the total for tasks
- unbooked time, the total for unaccounted for time between tasks
- total time, the sum of booked and unbooked time
- break time, the sum of any times between a "marker" entry and the next task
In order to pick up on unbooked time and differentiate it from break time, I add entries with a tag of "marker". This is used to indicate the start of a break. The break is determined to end when the next entry starts.
This uses commander.js for supporting command line arguments. Running the program with a -h or --help flag will print out the usage instructions. Note if you have a .env file as below this will include the values from that file in the output.
npm run cli -- --help
> @devwithimagination/[email protected] cli /Users/david/Development/Projects/toggl-summary-cli
> ts-node ./src/cli.ts "--help"
Usage: cli [options]
Options:
-D, --debug output extra debugging
--api-key <api-key> api token, found in Toggle profile settings
--email <email> your email address
--workspace-id <workspace id> id of the Toggle workspace
-d, --day <date> day to report on (in yyyy-MM-dd format). If a date is not supplied
then this will default to today. (default: "2020-09-21")
-w, --week If specified, interpret the day as the start of a week.
--include-summary If specified, include client/project summary detail
-h, --help display help for command
This uses dotenv for supporting loading secrets from a .env file in directory the tool is ran from. This is used to provide default values for the required CLI options above. This file can contain:
API_TOKEN=<api token, found in Toggle profile settings>
EMAIL=<your email address>
WORKSPACE_ID=<id of the Toggle workspace>
If the program is called with a DOT_ENV_CONFIG environment variable set, then an alternative location can be specified for this configuration file.
An example of running this for a single day:
$ npx @devwithimagination/toggl-summary-cli -d 2020-09-18
# Totals for 2020-09-18 to 2020-09-18
* Booked time: 02:49:11
* Unbooked time: 00:54:20
* Break time: 00:00:00
* Total time (booked + unbooked): 03:43:31
An example of running this for a single day, including summary information:
$ npx @devwithimagination/toggl-summary-cli -d 2020-09-18 --include-summary
# Totals for 2020-09-18 to 2020-09-18
* Booked time: 02:49:11
* Unbooked time: 00:54:20
* Break time: 00:00:00
* Total time (booked + unbooked): 03:43:31
# Summary
* Client-1: 31.74% (01:10:57)
* UI: 55.39% (00:39:18)
* API: 44.61% (00:31:39)
* Unknown Client/Project: 24.78% (00:55:23)
* Unknown Client/Project: 100.00% (00:55:23)
* Unbooked Time: 24.31% (00:54:20)
Running for a single day, using a configuration file in an alternative location:
$ DOT_ENV_CONFIG=~/.toggl-summary-cli.env npx @devwithimagination/toggl-summary-cli -d 2020-09-18
# Totals for 2020-09-18 to 2020-09-18
* Booked time: 02:49:11
* Unbooked time: 00:54:20
* Break time: 00:00:00
* Total time (booked + unbooked): 03:43:31
Running for a week:
$ npx @devwithimagination/toggl-summary-cli -d 2020-09-14 -w
# Totals for 2020-09-14 to 2020-09-20
* Booked time: 28:21:26
* Unbooked time: 07:20:12
* Break time: 04:01:59
* Total time (booked + unbooked): 35:41:38
When running this from a locally checked out project, you need to pass -- to stop ts-node interpreting the arguments as its own.
$ npm run cli -- -d 2020-09-18
> @devwithimagination/[email protected] cli /Users/david/Development/Projects/toggl-summary-cli
> ts-node ./src/cli.ts "-d" "2020-09-18"
# Totals for 2020-09-18 to 2020-09-18
* Booked time: 02:49:11
* Unbooked time: 00:54:20
* Break time: 00:00:00
* Total time (booked + unbooked): 03:43:31
I use Day One as my journaling application of choice. This utility script was primarily created to produce the starter for a template for daily or weekly entries relating to work.
To create a daily entry, for the current day, I run:
$ dayone2 --tags work -- new $'End of Day Work Summary\n\n' "$(DOT_ENV_CONFIG=~/.toggl-summary-cli.env npx @devwithimagination/toggl-summary-cli )"
To create a weekly entry, for the current week, I run:
$ dayone2 --tags work -- new $'End of Week Work Summary\n\n' "$(DOT_ENV_CONFIG=~/.toggl-summary-cli.env npx @devwithimagination/toggl-summary-cli -d $(date -v -Mon +%Y-%m-%d) -w )"
This project uses jest with ts-jest for testing. Running npm test will run the test suites and output coverage reports into the coverage directory.