What it is

Watson is a Python command-line application for tracking time spent on projects and activities. It lives in the open-source Python ecosystem, where it is distributed as td-watson on PyPI and as watson through Homebrew on OS X. The tool records work as frames, and each frame can have a project name, tags, a start time, and a stop time.

The concrete problem it solves is that people need to know how much time they spend on projects and need a way to produce reports for clients. Instead of asking users to maintain separate notes or use a graphical service, Watson lets them start and stop tracking from the terminal. It also provides commands for reviewing logged sessions and for filtering logs and reports by project, tag, and date.

Key capabilities

• Start tracking a project with a tag by running watson start world-domination +cats, which creates a new frame for the named project and tag.
• Stop the active frame with watson stop and view the tracked project, tags, and start information in the command output.
• Review recent frames with watson log, which lists entries by day and shows a frame identifier, start time, end time, duration, project, and tags.
• Filter logged sessions and reports by project, tag, and date, as described for the log and report commands in the README.
• Discover available commands through watson help or through the project documentation.
• Install and run the tool as a Python package with pip or pip3, or through Homebrew on OS X.

Who uses it and how

• Users who need to record time against named projects can start a frame before working and stop it when finished.
• Users who organize work by category can add tags during tracking and later filter logs or reports by those tags.
• Users who need client-facing summaries can review daily logs and generate reports with date, project, and tag filters.
• Terminal-based Python users can install td-watson locally and run the watson command as part of a shell workflow.

Getting started

On OS X, install Watson with brew update && brew install watson, and on other platforms install it with pip install td-watson or pip3 install td-watson. Start tracking with watson start project-name +tag, stop with watson stop, and review frames with watson log.

When to use it — and when not to

Use Watson when a user wants a command-line time tracker and needs project, tag, and date filtering for logs or reports. It may be less suitable for users who need a graphical dashboard, hosted service, or mobile client, because the provided facts describe a local Python CLI rather than those interfaces. The provided registry data lists 141 open issues and shows no contributor count, so evaluators should inspect maintenance status before making it a long-term dependency.

On OS X, the easiest way to install **watson** is using `Homebrew `_:

.. code:: bash

  $ brew update && brew install watson

On other platforms, install **watson** using pip or pip3, depending on which one is available:

.. code:: bash

  $ pip install td-watson

or:

.. code:: bash

  $ pip3 install td-watson

If you need more details about installing watson, please refer to the `documentation `_.

Usage
~~~~~

Start tracking your activity via:

.. code:: bash

  $ watson start world-domination +cats

With this command, you have started a new **frame** for the *world-domination* project with the *cats* tag. That's it.

Now stop tracking you world domination plan via:

.. code:: bash

  $ watson stop
  Project world-domination [cats] started 8 minutes ago (2016.01.27 13:00:28+0100)

You can log your latest working sessions (aka **frames**) thanks to the ``log`` command:

.. code:: bash

  $ watson log
  Tuesday 26 January 2016 (8m 32s)
        ffb2a4c  13:00 to 13:08      08m 32s   world-domination  [cats]

Please note that, as `the report command `_, the ``log`` command comes with projects, tags and dates filtering.

To list all available commands, either `read the documentation `_ or use:

.. code:: bash

  $ watson help

Contributor Code of Conduct
---------------------------

If you want to contribute to this project, please read the project `Contributor Code of Conduct `_

License
-------

Watson is released under the MIT License. See the bundled LICENSE file for
details.

.. |Build Status| image:: https://travis-ci.org/TailorDev/Watson.svg?branch=master
   :target: https://travis-ci.org/TailorDev/Watson
.. |PyPI Latest Version| image:: https://img.shields.io/pypi/v/td-watson.svg
   :target: https://pypi.python.org/pypi/td-watson
.. |Requires.io| image:: https://requires.io/github/TailorDev/Watson/requirements.svg?branch=master
   :target: https://requires.io/github/TailorDev/Watson/requirements/?branch=master
   :alt: Requirements Status
.. |Watson screenshot| image:: https://tailordev.github.io/Watson/img/watson-demo.gif
.. _Watson screenshot: https://asciinema.org/a/35918