Getting Started

This guide will help you get up and running with kasl quickly.

Installation

One line on Windows (PowerShell):

irm https://raw.githubusercontent.com/lacodda/kasl/main/tools/install.ps1 | iex

One line on macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/lacodda/kasl/main/tools/install.sh | sh

Via npm:

npm i -g kasl-cli

Via cargo:

cargo install kasl-cli

Or download the archive for your platform from Releases (Windows x86_64, Linux x86_64, macOS arm64), unpack and put kasl on your PATH.

Installer options

Both scripts read three environment variables:

Variable	Effect
`KASL_VERSION`	Install this tag (`vX.Y.Z`) instead of the newest release
`KASL_INSTALL_DIR`	Where the binaries land; defaults to the directory of the `kasl` already on your `PATH`, and without one to `%LOCALAPPDATA%\Programs\kasl` on Windows and `~/.local/bin` elsewhere
`KASL_NO_ALIAS`	Set to `1` to skip the short `ka` alias

Upgrading with the installer

Run the installer again to upgrade: it replaces the kasl already on your PATH in place rather than installing a second copy beside it, stops a running watcher for the swap and starts it again from the new binary. On Windows it also points the autostart entry at the upgraded binary, and removes a second copy that an earlier installer left in %LOCALAPPDATA%\Programs\kasl. A copy it did not put there (cargo, npm, by hand) is only named, for you to remove.

The `ka` alias

The installers and the npm package also set up ka as a short second name, so ka report is the same as kasl report. It is a link to the same binary - a hard link on Windows, a symlink elsewhere - so both names always answer with the same code and neither can fall behind. It is skipped when something else in your PATH already answers to ka, and self-update re-points it after replacing the binary.

Installing through cargo install gives you kasl only: cargo installs binaries, and ka is a link the installers create. Make it yourself if you want it, beside the binary cargo installed.

Build from Source

Requirements:

Rust 1.95 or higher
Git

git clone https://github.com/lacodda/kasl.git
cd kasl
cargo build --release
cargo install --path .

Verify Installation

Check that kasl is installed correctly:

kasl --version

Initial Configuration

Interactive Setup

Run the interactive configuration wizard:

kasl setup

This will guide you through setting up:

Monitor settings (pause thresholds, activity detection)
API integrations (GitLab, Jira, SiServer)
Server configuration for report submission

Manual Configuration

Configuration files are stored in:

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

Example configuration:

{
  "monitor": {
    "min_pause_duration": 20,
    "pause_threshold": 60,
    "poll_interval": 500,
    "activity_threshold": 30,
    "min_work_interval": 10
  },
  "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"
  }
}

First Steps

1. Start Activity Monitoring

Begin tracking your work sessions:

# Start monitoring in the background
kasl watch

# Or run in foreground for debugging
kasl watch --foreground

2. Enable Autostart (Optional)

Configure kasl to start automatically on system boot:

kasl autostart enable

3. Create Your First Task

Add a task to track your work:

kasl task add --name "Set up kasl" --completeness 100

4. View Your Report

Check your work summary:

kasl report

Daily Workflow

Morning Routine

Check yesterday’s report (if needed):
Terminal window
```
kasl report --last
```

Create today’s tasks:

kasl task add --name "Code review" --completeness 0
kasl task add --name "Team meeting" --completeness 0

Start monitoring (if not already running):
Terminal window
```
kasl watch
```

During the Day

Update task progress:
Terminal window
```
kasl task edit 1  # Edit task by ID
```

Add new tasks as needed:

kasl task add --name "Bug fix" --completeness 0

View current status:
Terminal window
```
kasl task list  # Show today's tasks
```

End of Day

View today’s report:
Terminal window
```
kasl report
```
Submit report (if configured):
Terminal window
```
kasl report --send
```
End workday manually (if needed):
Terminal window
```
kasl end
```

Common Tasks

Task Management

# Create a task
kasl task add --name "Task name" --comment "Description" --completeness 0

# List tasks
kasl task list

# Edit a task
kasl task edit 1

# Remove a task
kasl task remove 1

# Use templates
kasl task add --from-template

Absences the monitor missed

The monitor only sees the keyboard and the mouse, so an hour in a meeting room leaves no trace. Record it yourself:

# A 40-minute absence starting at 15:00
kasl pauses add --start 15:00 --minutes 40 --reason "offsite meeting"

# See what was recorded
kasl pauses list

Data Export

# Export today's data
kasl export --format csv

# Export all data
kasl export all --format json

# Export to specific file
kasl export --output my_report.csv

Monthly Summary

# View monthly summary
kasl sum

# Submit monthly report
kasl sum --send

Troubleshooting

Check if Monitoring is Running

kasl watch --stop  # Stop any running instances
kasl watch --foreground  # Start in foreground to see logs

Debug Mode

Enable debug logging:

KASL_DEBUG=1 kasl watch --foreground

Reset Configuration

If you need to start over:

kasl setup --delete

Next Steps

Read the Features guide to learn about advanced capabilities
Explore API Integrations for external service connections
Check the Configuration guide for detailed settings
Review Commands for complete command reference