kasl-cli 1.0.0

kasl is a comprehensive command-line utility 🛠️ designed to streamline the tracking of work activities 📊, including start times ⏰, pauses ⏸, and task completion
Documentation

kasl - Key Activity Synchronization and Logging

Overview 📖

kasl is a comprehensive command-line utility designed to streamline work activity tracking, task management, and productivity reporting. It automatically monitors your work sessions, tracks breaks, manages tasks, and generates detailed reports for better productivity insights.

Current Version: 1.0.0

✨ Features

🔍 Activity Monitoring

  • Automatic work session tracking - Detects when you start and end your workday
  • Smart break detection - Automatically records breaks based on inactivity
  • Background monitoring - Runs silently in the background
  • Cross-platform binaries - Windows x64, Linux x64, and macOS arm64 releases; unix autostart integration lands in 1.0.0

📋 Task Management

  • CRUD operations - Create, read, update, and delete tasks
  • Task templates - Save frequently used tasks as reusable templates
  • Tagging system - Organize tasks with custom tags and colors
  • Progress tracking - Track task completion percentage
  • Batch operations - Edit or delete multiple tasks at once

📊 Reporting & Analytics

  • Daily reports - Comprehensive view of work intervals and tasks
  • Monthly summaries - Aggregated statistics and productivity metrics
  • Productivity calculation - Measure actual work time vs. presence time
  • Short interval detection - Identify and merge fragmented work periods
  • Export capabilities - Export data to CSV, JSON, or Excel formats

⚙️ Advanced Features

  • Time adjustment - Correct work times with preview before applying
  • Database migrations - Safe schema updates when upgrading (debug builds only)
  • API integrations - Connect with GitLab, Jira, and custom APIs
  • Autostart support - Start monitoring automatically on system boot
  • Debug logging - Detailed logs for troubleshooting

🚀 Installation

Quick Install (Recommended)

Via npm (downloads the prebuilt binary; Windows x64 for now):

npm i -g kasl-cli

Via cargo (builds from source on any platform; the crate is named kasl-cli, the binary stays kasl):

cargo install kasl-cli

Install Script

Install kasl using curl:

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

Or using wget:

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

Build from Source

Requirements:

  • Rust 1.70 or higher
  • Git
git clone https://github.com/lacodda/kasl.git

cd kasl

cargo build --release

cargo install --path .

📚 Quick Start

Initial Setup

# Configure kasl interactively

kasl init


# Start activity monitoring

kasl watch


# Enable autostart on system boot

kasl autostart enable

Daily Workflow

# Create a new task

kasl task add --name "Review pull requests" --completeness 0


# Update task progress

kasl task edit 1


# View today's report

kasl report


# Manually end workday (if needed)

kasl end


# Submit daily report

kasl report --send

📖 Command Reference

Core Commands

watch - Activity Monitoring

# Start monitoring in background

kasl watch


# Run in foreground (debug mode)

kasl watch --foreground


# Stop monitoring

kasl watch --stop

task - Task Management

# Create task

kasl task add --name "Fix bug #123" --comment "High priority" --tags "bug,urgent"


# Create from template

kasl task add --template daily-standup

kasl task add --from-template  # Interactive selection


# View tasks

kasl task list              # Today's tasks

kasl task list --all        # All tasks

kasl task list --tag urgent # Tasks with specific tag

kasl task show 5            # Show specific task by ID


# Edit tasks

kasl task edit 5   # Edit by ID

kasl task edit     # Pick several tasks to edit interactively


# Remove tasks

kasl task remove 1 2 3   # Remove by IDs

kasl task remove --today # Remove all today's tasks

Scripted flows can add -y/--yes to remove to skip the confirmation prompt, and add errors instead of hanging when --name is missing outside an interactive terminal.

inbox - Jira Inbox

kasl inbox                # List assigned open Jira issues

kasl inbox -n 5            # Top five by ranking (pin / Scoring / priority)

kasl inbox sync            # Poll Jira now

kasl inbox pin PROJ-123    # Keep an issue on top

kasl inbox open PROJ-123   # Open in browser

kasl inbox take PROJ-123   # Import into local tasks

The watcher polls Jira in the background and shows a desktop toast when a new issue is assigned to you (see the jira_inbox config section).

report - Report Generation

# View report

kasl report                      # Today's report

kasl report --last              # Yesterday's report


# Submit reports

kasl report --send              # Send daily report

kasl report --month             # Send monthly summary

end - Manual Workday End

# Manually end today's workday

kasl end

template - Task Templates

# Manage templates

kasl template add --name "standup"

kasl template list

kasl template show standup

kasl template edit standup

kasl template remove standup

kasl template search daily

tag - Tag Management

# Manage tags

kasl tag add urgent --color red

kasl tag list

kasl tag show urgent   # Show tasks with tag

kasl tag edit urgent

kasl tag remove personal

export - Data Export

# Export data

kasl export report --format csv

kasl export tasks --format json --date 2025-01-15

kasl export summary --format excel -o monthly_report.xlsx

kasl export all --format json  # Export everything

Utility Commands

sum - Monthly Summary

kasl sum  # View monthly working hours summary

pauses - Pauses and Missed Absences

kasl pauses                          # Today's pauses

kasl pauses list --date 2025-01-15   # Specific date

kasl pauses list --min-duration 10   # Filter by duration


# Record an absence the monitor missed

kasl pauses add --start 13:00 --minutes 60 --reason "lunch"

kasl pauses add --start 16:20 --minutes 10 --keep  # survives the filter

kasl pauses remove 42

autostart - System Integration

kasl autostart enable   # Enable autostart

kasl autostart disable  # Disable autostart

kasl autostart status   # Check status

update - Self-Update

kasl update  # Check and install updates

completions - Shell Completions

kasl completions bash        # bash, zsh, fish, powershell, elvish

eval "$(kasl completions bash)"

migrations - Database Management (Debug Only)

kasl migrations status  # Check database version

kasl migrations history # View migration history

Note: This command is only available in debug builds.

⚙️ Configuration

Configuration file is stored at:

  • Windows: %LOCALAPPDATA%\lacodda\kasl\config.json
  • macOS: ~/Library/Application Support/lacodda/kasl/config.json
  • Linux: ~/.local/share/lacodda/kasl/config.json

Configuration Options

{
  "monitor": {
    "min_pause_duration": 20,    // Minutes - minimum break to record
    "pause_threshold": 60,       // Seconds - inactivity before pause
    "poll_interval": 500,        // Milliseconds - activity check interval
    "activity_threshold": 30,    // Seconds - activity before workday start
    "min_work_interval": 10      // Minutes - minimum work interval
  },
  "si": {
    "login": "your.email@company.com",
    "auth_url": "https://auth.company.com",
    "api_url": "https://api.company.com"
  },
  "gitlab": {
    "access_token": "your-token",
    "api_url": "https://gitlab.com"
  },
  "jira": {
    "login": "your.email@company.com",
    "api_url": "https://jira.company.com"
  },
  "jira_inbox": {
    "enabled": true,
    "poll_interval_secs": 300,  // Seconds between Jira inbox polls
    "notify": true              // Desktop toast for new issues
  }
}

🔍 Debugging

Enable debug logging for troubleshooting:

# Enable debug mode with full formatting

KASL_DEBUG=1 kasl watch


# Use standard Rust logging

RUST_LOG=kasl=debug kasl report


# Trace level for maximum verbosity

RUST_LOG=kasl=trace KASL_LOG_FORMAT=full kasl watch

🗄️ Database

kasl uses SQLite for local data storage. The database is located at:

  • Windows: %LOCALAPPDATA%\lacodda\kasl\kasl.db
  • macOS: ~/Library/Application Support/lacodda/kasl/kasl.db
  • Linux: ~/.local/share/lacodda/kasl/kasl.db

Backup

Regular backups are recommended:

# Export all data

kasl export all --format json -o backup_$(date +%Y%m%d).json

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

# Clone repository

git clone https://github.com/lacodda/kasl.git

cd kasl


# Run tests

cargo test


# Run with debug logging

KASL_DEBUG=1 cargo run -- watch --foreground


# Build for release

cargo build --release


# Debug build (enables migrations command)

cargo build

Code Style

We maintain consistent code documentation standards. Please refer to our style guide:

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

📞 Support

Made with ❤️ by Kirill Lakhtachev