npm package: @lmoesle/time-tracking-utility
Description: <div id="top"></div>
Author: lmoesle
Latest version: 0.2.3

<div id="top"></div>

<!-- PROJECT SHIELDS -->
[![Contributors][contributors-shield]][contributors-url]
[![Stargazers][stars-shield]][stars-url]
[![MIT License][license-shield]][license-url]
<!-- END OF PROJECT SHIELDS -->

## About The Project

This is a simple command line application that shows your timetracking entries from clockify.

```bash
@lmoesle/time-tracking-utility view -p this-week

Date       | Start    | End      | Pause       | Duration    | Client                         | Description
-----------+----------+----------+-------------+-------------+--------------------------------+--------------------------------
2023-11-05 | 14:00:00 | 15:30:00 |  0 h  0 min |  1 h 30 min |                                | Personal Projects, 
-----------+----------+----------+-------------+-------------+--------------------------------+--------------------------------
Total:  1 h 30 min
```

**CSV Export**

To export the time entries as a csv file, you can use the `export` command. It saves the csv file to the users home directory

```bash
@lmoesle/time-tracking-utility export -p this-week -c <client>
```

**Time Sync**

To sync the time entries to another clockify, you can use the `sync` command. It will sync your time entries from one clockify instance to another.

```bash
@lmoesle/time-tracking-utility sync -p this-week -c <client>
```

## Documentation

```bash
@lmoesle/time-tracking-utility create --from <start-datetime> --to <end-datetime> --project <project-name> [--description <text>]
```

Create a single Clockify time entry by passing start/end timestamps, a project name, and an optional description.

```bash
Usage: index [options] [command]


    _____ _              _____             _   _                _   _ _ _ _       
    |_   _|_|_____ ___   |_   _|___ ___ ___| |_|_|___ ___    _ _| |_|_| |_| |_ _ _ 
    | | | |     | -_|    | | |  _| .'|  _| '_| |   | . |  | | |  _| | | |  _| | |
    |_| |_|_|_|_|___|    |_| |_| |__,|___|_,_|_|_|_|_  |  |___|_| |_|_|_|_| |_  |
                                                    |___|                    |___|
    

Options:
  -V, --version   output the version number
  -h, --help      display help for command

Commands:
  view [options]    View the time entries for the defined day, week or month
  export [options]  Export the time entries for the defined day, week or month
  sync [options]    Sync time entries for the defined day, week or month
  create [options]  Create a new time entry in Clockify
  help [command]    display help for command
```

### Installation

```bash
npm install -g @lmoesle/time-tracking-utility
```

**Setup Clockify API Key**

A clockify api key is required to use this tool. You can find your api key in your clockify profile settings.
You have to export the api key as an environment variable. You can do this by adding the following line to your
`.bashrc` or `.zshrc` file.

```bash
export clockifyApiKey=<your-clockify-api-key>
export clockifyMiragonApiKey=<your-clockify-miragon-api-key>
```

### Configuration

The utility looks for a `time-tracking-config.json` file which contains the
mappings used when syncing your entries to another Clockify workspace.
The file is bundled with the package and can be adjusted if necessary.
Set `"no-description": true` per mapping to send empty descriptions when syncing time entries.

Example:

```json
{
  "clockifyWorkspaceId": "<target-workspace-id>",
  "mapping": {
    "Client Name": {
      "projectId": "<clockify-project-id>",
      "taskId": "<clockify-task-id>",
      "billable": true,
      "no-description": false
    }
  }
}
```

### Usage

```bash
@lmoesle/time-tracking-utility view -p <time-period> -c <client>

# examples
@lmoesle/time-tracking-utility view -p today
@lmoesle/time-tracking-utility view -p yesterday
@lmoesle/time-tracking-utility view -p this-week
@lmoesle/time-tracking-utility view -p this-month
@lmoesle/time-tracking-utility view -p last-month
```

**Options**

| Option       | Description         | Required |
|--------------|---------------------|----------|
| -p, --period | Time period to view | yes      |
| -c, --client | Client to view      | no       |
| -f, --from | Start datetime for create | yes (create) |
| -t, --to | End datetime for create | yes (create) |
| -p, --project | Project name for create | yes (create) |
| -d, --description | Description for create | no (create) |

<p align="right">(<a href="#top">back to top</a>)</p>

## License

Distributed under the [MIT](LICENSE).

<!-- MARKDOWN LINKS & IMAGES -->
<!-- https://www.markdownguide.org/basic-syntax/#reference-style-links -->

[contributors-shield]: https://img.shields.io/github/contributors/lmoesle/time-tracking-utility.svg?style=for-the-badge

[contributors-url]: https://github.com/lmoesle/time-tracking-utility/graphs/contributors

[stars-shield]: https://img.shields.io/github/stars/lmoesle/time-tracking-utility.svg?style=for-the-badge

[stars-url]: https://github.com/lmoesle/time-tracking-utility/stargazers

[license-shield]: https://img.shields.io/github/license/lmoesle/time-tracking-utility.svg?style=for-the-badge

[license-url]: https://github.com/lmoesle/time-tracking-utility/blob/main/LICENSE