aw-client

Client library for ActivityWatch in Python.

Please see the documentation for usage, and take a look at examples/.

• Documentation
• API Reference

How to install

Install from pip: pip install aw-client

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

To install from a cloned version:

• clone repo: git clone https://github.com/ActivityWatch/aw-client.git
• cd into the directory: cd aw-client
• run poetry install (will create a virtualenv, if none activated)
  • If you don't want to use poetry you can also use pip install ., but that 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

Server URL configuration

To connect through an HTTPS reverse proxy, set baseurl in the [server] section of your aw-client configuration file:

[server]
baseurl = "https://aw.example.com/activitywatch"

Use the URL prefix before /api/0; a path prefix and a trailing slash are supported. Only HTTP(S) URLs without embedded credentials, a query or a fragment are accepted. TLS certificate verification remains enabled.

baseurl takes precedence over configured hostname/port and the constructor's protocol. An explicitly passed host or port (including CLI --host/--port) opts out of baseurl and uses the existing protocol/host/port behavior. An absent or empty baseurl preserves that behavior too. A profile is an isolated instance with its own configuration directory, so set baseurl in the [server] section of that profile's own aw-client.toml (for example ~/.config/activitywatch-research/aw-client/aw-client.toml). No [server-<profile>] section is needed, with one exception.

The testing profile: the built-in configuration already defines [server-testing], and that section wins over [server]. So with --testing (an alias for --profile testing), set baseurl in [server-testing] of the testing profile's own aw-client.toml:

[server-testing]
baseurl = "https://aw-testing.example.com/activitywatch"

Local API-key discovery and proxy bypass use the configured URL's actual host and port, not the default loopback address. Remote URLs do not receive a key read from the local server configuration.

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.
• working_hours.py - computes hours worked per day (matching a "work" category rule), and exports matching events to a JSON file (for auditing).
• load_dataframe.py - loads events from a host using a categorizing & AFK-filtering query, put result in a pandas dataframe, and export as CSV.
• 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.