Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

kasl

kasl: Key Activity Synchronization and Logging 🕒


Overview 📖

kasl is a comprehensive command-line utility 🛠️ designed to streamline the tracking of work activities 📊, including start times ⏰, pauses ☕, and task completion ✅. It automates the collection of work data 📈, facilitates task management 📋, and generates daily reports 📝, simplifying workflow and productivity tracking 🚀.

Features 🌟

  • Automatic Data Collection 📊: Tracks the start of work sessions and pauses without manual input.
  • Task Management 📋: Easily add tasks and update completion percentages.
  • Daily Reports 📝: Auto-generates daily reports summarizing work activities.
  • API Integration 🌐: Sends daily reports to a specified API for easy access and storage.
  • User-Friendly 😊: Designed with a focus on simplicity and ease of use.

Getting Started 🚀

Prerequisites 📋

  • Ensure you have a compatible operating system (Windows, macOS, or Linux) 💻.
  • Requires Node.js and npm (or an equivalent package manager) for running the utility 📦.

Installation 🛠️

Install kasl now. kasl is installed by running one of the following commands in your terminal. You can install this via the command-line with either curl or wget.

Install kasl via curl

sh -c "$(curl -fsSL https://raw.githubusercontent.com/lacodda/kasl/main/tools/install.sh)"

Install kasl via wget

sh -c "$(wget https://raw.githubusercontent.com/lacodda/kasl/main/tools/install.sh -O -)"

This will make the kasl application globally available in your system.

Usage 📚

To start kasl and begin tracking:

kasl --help

Roadmap 🗺️

  • Enhance task management with categories and priorities.
  • Integrate with more APIs for report submission.
  • Implement machine learning for predicting task completion time.
  • Add support for team collaboration features.
  • Develop a graphical user interface (GUI) version.

How to Contribute 🤝

Contributions are welcome! If you have ideas for new features or improvements, feel free to fork the repository, make your changes, and submit a pull request.

License 📄

kasl is open-source software licensed under the MIT license. See the LICENSE file for more details.

Commands

  • event: Manages and displays events related to the application's operations Learn more
  • report: Generates and optionally sends a report covering the day's events and tasks Learn more
  • task: Facilitates task management, including creating, displaying, and updating tasks Learn more

event Command

The event command in kasl is used for managing and displaying events related to the application's operations. This command allows users to insert new events or display information about existing events, depending on the provided arguments.

Usage

kasl event [OPTIONS] <EVENT_TYPE>

Options

  • <EVENT_TYPE>: Specifies the type of the event to insert. Defaults to start. The EVENT_TYPE can be either start or end, representing the beginning and the end of an event, respectively. This option is used when adding a new event and is not required when simply viewing events.

  • -s, --show: Displays the events information. When this option is provided, the command will fetch and display information about events instead of inserting a new event.

Examples

  • Inserting a new start event:

    kasl event start

  • Inserting a new end event:

    kasl event end

  • Displaying information about events:

    kasl event --show

Description

The event command operates in two modes: insert and display.

  • Insert Mode: When called without the --show option, it inserts a new event of the specified type into the application's database. By default, it inserts a start event unless another event type is specified via the --event_type option. This mode is useful for tracking the start and end of events within the application.

  • Display Mode: When the --show option is used, the command fetches events from the database, merges them based on certain criteria, calculates durations, and formats them for display. It then prints a summary of the working hours and details of each event. This mode is intended for reviewing the events and their durations over time.

Implementation Notes

  • The command uses the local system time (chrono::Local) to display the current date when showing events.

  • It leverages the application's Events, EventType, FormatEvents, EventGroup, and View modules for database operations, event handling, and output formatting.

  • The command is designed to be robust, with error handling that ensures graceful failure in case of issues accessing the database or processing events.

Error Handling

The event command returns an error if there are issues accessing the database, merging events, or any other operation-related failures. It ensures that errors are properly boxed and communicated back to the caller, facilitating debugging and resolution.

report Command

The report command in kasl is designed to generate and optionally send a comprehensive report covering the day's events and tasks. This command aggregates data from events and tasks, formats it, and displays or sends it as specified by the user.

Usage

kasl report [OPTIONS]

Options

  • --send: When this option is provided, the command will attempt to send the generated report. If not specified, the command will display the report for the current day without sending it.

Examples

  • Generating and displaying a report for today:

    kasl report

  • Generating and sending today's report:

    kasl report --send

Description

The report command operates in two main modes based on the provided options:

  • Display Mode: By default, without the --send option, the command fetches today's events and tasks, merges and formats the events, and displays a report. This report includes a summary of the events and a list of tasks for the current day.

  • Send Mode: When the --send option is used, the command performs the same data fetching and processing as in display mode. Additionally, it attempts to send the formatted report. If no tasks are found for the day, it notifies the user that no tasks are available. On successful submission, a confirmation message is shown, indicating that the report has been sent.

Implementation Notes

  • The command utilizes local system time (chrono::Local) for timestamping and report dating.

  • It leverages multiple modules from the application, such as Events, Tasks, Config, and Si for database operations, configuration management, and server interaction.

  • Data from events is serialized into JSON format for sending. The Si module is responsible for transmitting this data based on application configurations.

  • Error handling is built into the command to manage and report issues with fetching data, reading configuration, or communicating with the server.

Error Handling

The command is designed to handle various errors gracefully, including database access issues, configuration problems, and network communication errors. Errors are reported to the user with sufficient detail to identify and address the underlying problem.

This documentation provides users with a clear understanding of how to use the report command within the kasl utility, including its options, operation modes, and handling of different scenarios.

task Command

The task command in kasl facilitates task management, including creating, displaying, and updating tasks. It supports various operations through command-line options, providing flexibility in how tasks are handled within the application.

Usage

kasl task [OPTIONS]

Options

  • -n, --name <NAME>: Specifies the name of the task. This option is used for creating a new task or updating an existing one.

  • -c, --comment <COMMENT>: Adds a comment to the task. This is optional and can be used for providing additional information about the task.

  • -p, --completeness <COMPLETENESS>: Indicates the completeness of the task as a percentage (0-100). This can be used to update the task's progress.

  • -s, --show: Displays tasks based on the specified filter. Without additional filtering options, it defaults to showing today's tasks.

  • -a, --all: When used with --show, displays all tasks, overriding the default filter of today's tasks.

  • -i, --id <ID>: Specifies one or more task IDs. When used with --show, filters the displayed tasks to those with the given IDs.

  • -f, --find: Finds and allows the user to update incomplete tasks. This option triggers a user interface for selecting incomplete tasks and updating their completeness.

Examples

  • Creating a new task:

    kasl task --name "New Task" --comment "This is a test task" --completeness 50

  • Displaying today's tasks:

    kasl task --show

  • Displaying all tasks:

    kasl task --show --all

  • Finding and updating incomplete tasks:

    kasl task --find

Description

The task command allows for comprehensive task management. It supports creating new tasks, displaying tasks with various filters, and updating task completeness. The command integrates user inputs and selections for a smooth task management experience.

Implementation Notes

  • Uses clap for command-line argument parsing and dialoguer for interactive prompts and selections.

  • Leverages the Tasks module for database operations, including fetching, creating, and updating tasks.

  • Task filtering is versatile, supporting filters like Today, All, and ByIds, making it easy to display tasks as needed.

  • The View module is used for formatting and displaying tasks, ensuring a consistent user experience.

Error Handling

The command includes comprehensive error handling to address potential issues with database operations or user input. It provides clear feedback to the user in case of errors, facilitating troubleshooting and correction.

This documentation outlines the task command's functionality within the kasl utility, including options, usage examples, and details on its operation and error handling.