andreassiegel / timeular-cli

CLI that interacts with Timeular's public API to track time-activities

Timeular CLI

Command-line integration for Timeular to track activities and check the status of the currently tracked activity.

It can be used as an interactive CLI by asking the user questions or directly by setting the required input via the corresponding flags.

The current version does not require a Timeular Pro account. It uses only API features that are available in the free version.

Installation

While refactoring is ongoing and new features are being added, the application is not published to any registry yet.

Therefore, you need to check out the repository before you can actually install it:

$ git clone https://github.com/andreassiegel/timeular-cli.git
$ cd timeular-cli
$ npm install -g

Configuration

Timeular CLI is using the public Timeular API that requires authentication via your personal API key.

You can get your API credentials from the Timeular account page.

To be able to use Timeular CLI, you have to export the API credentials as environment variables, e.g., in your .profile or .bashrc or .zshrc file:

export TIMEULAR_API_KEY="XXXXXXXXXX"
export TIMEULAR_API_SECRET="YYYYYYYYYY"

Usage

$ timeular --help
Usage: timeular <command> [options]

Commands:
  timeular start [activityName]  Start tracking for a specific activity, stops current tracking
                                 before starting a new one
  timeular stop                  Stops tracking current activity
  timeular continue              Continues tracking of a previous activity
  timeular status                Shows the current activity tracking status
  timeular list                  Lists all activities that are available for tracking

Options:
  -h, --help     output usage information                                                  [boolean]
  -v, --version  output the version number                                                 [boolean]

Tracking Activity

Activities can be tracked in multiple ways:

Interactive Tracking

If you do not provide any options to the start command, you will be prompted to select the activity to track:

$ timeular start
0   Administration
1   ARC
2   DEV
3   Education
✔ Number of activity to track: · 0
✔ Note: · Prepare release
Stopped tracking: DEV - Working on Timeular CLI (1h 28m 11s)
Started tracking: Administration - Prepare release

The list includes all activities you configured in Timeular.

Tracking of a specified Activity

You can directly specify the activity in order to start tracking without selecting from the list:

$ timeular start <activity>

Nevertheless, you will be prompted for a note.

Tracking of a specified Activity with a Note

In addition, you can also add a note when you can directly specify the activity and start tracking immediately:

$ timeular start <activity> -m <note>

The note may contain tags (#tag) and mentions (@mention).

Continue Tracking of a previous Activity

If you want to continue an activity you tracked recently, use the continue command.

It retrieves the time entries you tracked during the three previous days and the current day so far, and then lets you select one from the last 10.

The options you can choose from are unique by the associated note and ordered by the time you stopped tracking. Tracked activities that did not have a note, are excluded from the selection.

Including the previous three days allows you to continue where you left before the weekend, for instance.

$ timeular continue
0   Working on Timeular CLI (DEV)
1   Prepare release (Administration)
2   Eating pizza (Break)
✔ Number of activity to continue: · 0
Started tracking: DEV - Working on Timeular CLI

Check the Tracking Status

Use the status command to check your current tracking status:

$ timeular status
Currently tracking: DEV - Working on Timeular CLI (1h 16m 2s)

The output includes the note of the current tracking, if available. The current duration is displayed as well.

Stop Tracking

To finish an activity, use the stop command:

$ timeular stop
Stopped tracking: DEV (4h 24m 51s)

List Activities

You can use the list command to print all activities that are available for tracking. The output is indexed and sorted alphabetically.

If the tracker is running, the currently tracked is highlighted.

$ timeular list
0   Administration
1   ARC
2   DEV  
3   Education

timeular-cli's Issues

As a user, I can add a note when I start to track an activity

I want to be more specific when tracking activities as they are usually just defining the general kind or category of what I am doing.

Thus, it should be possible to add a note or message to the tracked activity to add more details.

Use either environment variables or a config file to configure Timeular credentials

Environment variables should only be an alternative to credentials configured in a special location in the home directory as the Timeular credentials are not used for anything else.

As a user, I can list all of today's activities.

It should be possible to use an additional command to output a summary of today's tracked activities on the command line.

The summary should be sorted and grouped by activities. If multiple activities have the same note/message, the time amount tracked is summed up.

Add tests for current status

Before adding features or refactoring the application, the current state should be verified by tests.

As a user, I can use a command to check the tracked time for the day.

An additional command should allow for checking the current status, i.e., display the time tracked so far for the day, and maybe also information about the currently tracked activity if any.

As a user, I can use a command to configure credentials.

Setting up Timeular CLI should be convenient, i.e., if no API credentials are set yet, it should support configuring them in the config file.

Fetch activity information from Jira

Use the Jira API or Jira CLI to (optionally) add the issue title from Jira as the note of the tracked activity if an issue ID is provided when an activity is tracked.

As a user, I can continue tracking of a previous activity

During the day, I often switch between different activities without actually finishing them before, e.g., I work on some feature before heading to a meeting. Afterwards, I continue the work I was doing before.

Currently, I manually add the same note to be time entry so that I can easily see (or calculate) the total time amount spent on that feature.

It would be nice if that was automated with something like:

$ timeular continue // or
$ timeular track --continue

This could be an interactive command that displays the last n (maybe configurable) distinct activities and notes with identifiers:

$ timeular continue
0: Meeting - Discussing X
1: DEV - Working on feature A
2: DEV - Fixing bug B

$ timeular continue 2
Continuing tracking of previous activity: DEV - Fixing bug B

Update outdated dependencies

Code Climate Integration is broken

Code Climate always returns 404 for this repository.