hxmmxh / aw-client

Client library for ActivityWatch

aw-client

Documentation

Client library for ActivityWatch in Python.

Please see the documentation for usage and examples.

How to install

To install the latest git version directly from github without cloning, run pip install git+https://github.com/ActivityWatch/aw-client.git

To install from a cloned version, cd into the directory and run poetry install to install inside an virtualenv. If you want to install it system-wide it can be installed with pip install ., but that has the issue that it might not get the exact version of the dependencies due to not reading the poetry.lock file.

Usage

For the CLI:

$ aw-client --help
Usage: aw-client [OPTIONS] COMMAND [ARGS]...

  CLI utility for aw-client to aid in interacting with the ActivityWatch
  server

Options:
  --host TEXT     Address of host
  --port INTEGER  Port to use
  -v, --verbose   Verbosity
  --testing       Set to use testing ports by default
  --help          Show this message and exit.

Commands:
  buckets    List all buckets
  canonical  Query 'canonical events' for a single host (filtered,...
  events     Query events from bucket with ID `bucket_id`
  heartbeat  Send a heartbeat to bucket with ID `bucket_id` with JSON `data`
  query      Run a query in file at `path` on the server
  report     Generate an activity report

Debugging

• Run python with LOG_LEVEL=debug to get additional debugging output
• If invalid events have been queued for submission, you may need to delete the file-based queues generated by this library
• To use the development version of this library use aw-client = {path = "../aw-client" } in pyproject.toml

Examples

The examples/ directory contains a couple of example scripts, including:

• time_spent_today.py - fetches all non-afk events and sums their duration to get the total active time for the day.
• merge_buckets.py - merges two buckets with non-intersecting events by moving all events from one into the other.
• redact_sensitive.py - redact sensitive events.