#################
Ellclockin Client
#################

Ellclockin client is a command-line application for Elektroline developers'
project clock tracking.

General
=======

Prerequisites
-------------

- The application and the server need to be installed, see :ref:`installation`.
- The server needs to be running, see :ref:`Ellclockin Server#Running <server-running>`.

Login information
-----------------

When running the application, you need to specify your username and password.
The password gets SHA-1 hashed and this combination is then used for connecting
to the server.

The application will ask for these every time it is ran:

.. code-block:: console

  $ ellclockin
  Username: your-username
  Password for your-username:

but you can also enter your username using the ``-u`` or ``--username`` parameters,
in which case the application will only ask for the password:

.. code-block:: console

  $ ellclockin -u your-username
  Password for your-username:

Server information
------------------

By default the server address is ``localhost:3755``.

If you want to specify a custom server address, use the ``-a`` or ``--address``
parameters:

.. code-block:: console

  $ ellclockin -a 198.168.0.42

If you want to specify a custom port, use the ``-p`` or ``--port`` parameters:

.. code-block:: console

  $ ellclockin -p 8086


Version information
-------------------

To print the name of the application with its version name, use the ``--version``
parameter:

.. code-block:: console

  $ ellclockin --version
  ellclockin 0.1.0

Commands
========

The application supports multiple commands. Each command also supports various
parameters, see individual commands for more information.

.. contents:: :local:

ls
--

Prints a list of all child nodes of the node on the specified path. If called
without a parameter, lists all child nodes of the home node:

.. code-block:: console

  $ ellclockin ls
  ['.app', '.broker', 'clockin']

Specify a path
^^^^^^^^^^^^^^

To specify a path for which all child nodes should be listed, use the ``-p`` or
``--path`` parameters:

.. code-block:: console

  $ ellclockin ls -p PATH
  ['item42', '.sample', 'xyz']

project
-------

This command handles all functions related to project management.

Whenever the project name needs to be specified, it is sanity checked.
For example:

.. code-block:: console

  $ ellclockin project -i nonexistent-project
  Project nonexistent-project does not exist!

Check completion
^^^^^^^^^^^^^^^^

To check if a project is complete, use the ``--checkComplete`` parameter:

.. code-block:: console

  $ ellclockin project --checkComplete project-in-progress
  Project project-in-progress is still in progress.
  $ ellclockin project --checkComplete completed-project
  Project completed-project is completed.

Clockin to a project
^^^^^^^^^^^^^^^^^^^^

To clockin to a project, use the ``-i`` or ``--clockin`` parameters:

.. code-block:: console

  $ ellclockin project -i sample-project
  Successfully clocked into sample-project.

Clockout from the current project
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To clockout from your current project, use the ``-o`` or ``--clockout`` parameters:

.. code-block:: console

  $ ellclockin project -o
  Successfully clocked out from the current project.

Retroactively
"""""""""""""

If you fail to clockout when intended, you can also clockout retroactively.
To do so, use the ``-r`` or ``--retroactive`` parameters:

.. code-block:: console

  $ ellclockin project -r 2011-11-04T00:05:23
  Successfully clocked out from the current project at 2011-11-04T00:05:23.

The provided datetime (in ISO 8601 format) will be used as the clockout time.

The provided datetime is also sanity checked, for example:

.. code-block:: console

  $ ellclockin project -r 2035-10-15T07:15:42
  You cannot clockout in the future!

Create a new project
^^^^^^^^^^^^^^^^^^^^

To create a new project, use the ``-n`` or ``--new`` parameters:

.. code-block:: console

  $ ellclockin project -n new-project-name
  Successfully created project new-project-name.

Get user's contributions
^^^^^^^^^^^^^^^^^^^^^^^^

To get the contributions of a user in a project, use the ``-c`` or
``--contributions`` parameters:

.. code-block:: console

  $ ellclockin project -c username sample-project
  Contributions of user username in project sample-project: 256

List all projects
^^^^^^^^^^^^^^^^^

To list all projects, use the ``-l`` or ``--list`` parameters:

.. code-block:: console

  $ ellclockin project -l
  Projects: ['project1', 'project2', 'sample-project']

worker
------

This command handles all functions related to worker management.

Register a new worker
^^^^^^^^^^^^^^^^^^^^^

To register yourself as a new worker, use the ``-n`` or ``--new`` parameters:

.. code-block:: console

  $ ellclockin worker -n
  Successfully created worker your-username.

If you're already a registered worker, the application will warn you as such:

.. code-block:: console

  $ ellclockin worker -n
  You are already registered as a worker!

List all workers
^^^^^^^^^^^^^^^^

To list all current workers, use the ``-l`` or ``--list`` parameters:

.. code-block:: console

  $ ellclockin worker -l
  Workers: ['self', 'other-worker', 'your-username']