watson

Start monitoring time in project

$ watson start [project]

$ watson start [project] +[tag]

$ watson stop

$ watson log

$ watson edit

$ watson remove

watson [global-options] <command> [command-options] [arguments]

Examples:
watson start <project> [<tag>...]
watson stop
watson report [--from <date>] [--to <date>]

-h, --help
    Show a help message for the command or subcommand and exit.

-v, --version
    Show watson's version number and exit (global option).

-c <file>, --config=<file>
    Specify an alternative configuration file for watson (global option).

--verbose
    Print more detailed information, useful for debugging (global option).

--at <time>
    For commands like start or edit, sets the start time of the frame explicitly. Format can be 'HH:MM' or 'YYYY-MM-DD HH:MM'.

--gap
    For start, starts a new frame even if another frame is already running, creating a time gap.

--from <date>
    Filter results (e.g., for report, log) to include entries from a specific date. Date formats vary (e.g., 'YYYY-MM-DD', 'yesterday').

--to <date>
    Filter results (e.g., for report, log) to include entries up to a specific date.

--project <project>
    Filter results (e.g., for report, log) by a specific project name.

--tag <tag>
    Filter results (e.g., for report, log) by a specific tag.

--csv
    Output the report in CSV (Comma Separated Values) format (for report).

--json
    Output the report in JSON (JavaScript Object Notation) format (for report).

--year, --month, --week, --day
    Filter the report by a specific period (e.g., current year, last month) (for report).

watson is a command-line time tracking application designed to be simple, unobtrusive, and powerful. It allows users to easily start and stop tracking time on various projects and tasks using tags. The tool records time spent on activities, storing this data locally, typically in your home directory's configuration folder. This local storage ensures privacy and offline usability.

One of watson's core strengths lies in its minimalist approach, making it quick to log entries without leaving the terminal. It provides robust reporting capabilities, enabling users to generate summaries of time spent daily, weekly, or over custom periods, filtered by project or tag. Reports can be output in various formats, including plain text, CSV, or JSON, facilitating integration with other tools.

As a Python-based utility, watson is highly portable and can be easily installed using pip. It's a preferred choice for developers, freelancers, and anyone seeking an efficient, low-overhead method to manage and analyze their time spent on different activities, fostering better time management and productivity.

watson is not a standard Linux utility; it must be installed separately, typically using Python's pip package manager. As a command-line tool, it does not provide a graphical user interface (GUI) by default. Its data is stored locally, which is great for privacy and offline work but means it doesn't inherently support multi-user collaboration or cloud synchronization without external tools or custom scripts.

watson stores its configuration and data files in the user's home directory, typically under ~/.config/watson/. This includes config.ini for customizable settings (like display formats, data paths, and aliases) and data files (e.g., frames.json) that hold all recorded time entries. Users can edit config.ini to tailor the tool to their specific needs.

watson supports a plugin system, allowing users to extend its functionality with custom commands or modify existing behaviors. This extensibility enables integration with other services, creation of specialized reports, or adding features not present in the core application, making it highly adaptable to various workflows.

watson was developed by TailorDev as an open-source, lightweight, and user-friendly command-line time tracking solution. It emerged as a response to the need for a simple yet powerful tool for developers and individuals to log time without the overhead of more complex or proprietary solutions. Its development has been community-driven, focusing on a clean interface and extensibility since its inception.

timewarrior(1), at(1)