search

alexdewar / clockify-tui

An unofficial terminal UI for the Clockify time-tracking app.
BSD 3-Clause "New" or "Revised" License
0 stars 0 forks source link

readme

Clockify TUI

Clockify TUI is an unofficial terminal interface for the Clockify time tracking app, written in Python.

While there are official apps for a range of platforms, I wanted to make something a bit simpler that can be operated from the terminal. Thankfully, there is a well-documented public API we can use. The current plan is to use blessed for the UI and clockify-api-client for interactive with the Clockify API.

It is currently under development, but the initial goals of the project are to:

  1. Provide a simple terminal UI displaying the current running task and previous tasks
  2. Allow for stopping the current task and starting a new one via the keyboard

This will require some additional machinery:

  1. A way to select the current workspace (#4)[^1]
  2. A way to obtain a list of projects (required so that the user can start a new task)
  3. Some way to store configuration data, such as the API key (a user-configurable TOML file?) (#3)

I also have some less pressing, nice-to-have features in mind:

  1. Allow for opening the web interface from the UI (#8)
  2. Provide a wizard for generating and editing the user config file (#10)
  3. Make the appearance of the app configurable via the config file (#12)

[^1]: Even if you only ever use one workspace, you still need to tell the Clockify API which workspace that is.

Getting started

To get started, you will need a Clockify account. You can sign up for free here.

You will also need to generate an API key so that you can connect to the Clockify API. Once you have created an account and logged in, you can generate a new one in the advanced tab of the preferences page.

For developers

This is a Python application that uses poetry for packaging and dependency management. It also provides pre-commit hooks for various linters and formatters and automated tests using pytest and GitHub Actions. Pre-commit hooks are automatically kept updated with a dedicated GitHub Action.

To get started:

  1. Download and install Poetry following the instructions for your OS.

  2. Clone this repository and make it your working directory

  3. Set up the virtual environment:

    poetry install

  4. Activate the virtual environment (alternatively, ensure any Python-related command is preceded by poetry run):

    poetry shell

  5. Install the git hooks:

    pre-commit install

  6. Run the main app:

    python -m clockify_tui