This command opens the task configuration file using the shell's default editor($EDITOR), unless the ``--skip-edit`` flag is provided. After the editor exits,the configuration file is validated and will prompt for retry if validationfails.

Start Task----------

$ focus on task_name

This starts the provided task, running any initial settings as indicated in thetask's configuration file.

End Task--------

$ focus end

This ends the current task, running any ending settings as indicated in thetask's configuration file.

*Note: this command is only available when a task is active.*

Edit Task---------

$ focus edit task_name [--skip-edit]

Like the ``make`` command, this command opens the task configuration file usingthe shell's default editor ($EDITOR). After the editor exits, theconfiguration file is validated and will prompt for retry if validation fails.

List Tasks----------

$ focus list [-v] [--verbose]

This will scan for existing tasks with valid configuration files and printthe names of the tasks found. Specify the ``-v`` or ``--verbose`` flag to alsoprint setting information for each task's configuration file. Invalid tasksare marked in red, while the active task is marked in green.

View Task---------

$ focus view [task_name]

This prints the setting information from the task's configuration file.If no task name is provided, the active task will be shown.

Rename Task-----------

$ focus rename old_task_name new_task_name

This commands gives the provided task a new name.

Delete Task-----------

$ focus destroy task_name [-f] [--force]

This commands removes the provided task after prompting for confirmation.Specify the ``-f`` or ``--force`` flag to skip confirmation.

Show Remaining Time for Active Task-----------------------------------

$ focus left [-s] [--short]

This commands prints the amount of time remaining, in minutes, for the activetask. Specify the ``-s`` or ``--short`` flag to print just the number ofminutes.

*Note: this command is only available if the active task has defined theduration option.*

Show Available Usage Statistics-------------------------------

$ focus stat [start]

This commands prints the daily task usage summaries, broken out per task, forevery day from the starting period through the current day.

where {n} is replaced with a number (e.g. ``1d`` for 1 day ago to today).If no starting period is provided, then ``today`` will be used.

Task Configuration==================

Each task is described by its associated configuration file. When a new taskis created, the `default task configuration file<https://github.com/xtrementl/focus/blob/master/conf/focus_task.cfg>`_ will beused.

The task configuration file is composed of a number of either non-block orblock options. Each value for an option may be quoted with either single ordouble quote, or may be unquoted if spaces and quotes are escaped.

The ``apps`` block allows for options to run, close, or block applications.Each option supports multiple values and can be repeated as multiple optiondefinitions.

The ``run`` option supports an arbitrary shell command, an application name, orthe path to an executable script. Arguments and shell redirection are alsopossible. This option will be initiated when starting a task.

The ``close`` option supports an arbitrary shell command, an application name,or the path to an executable script. Unlike ``run``, shell redirection is notsupported and all arguments provided are considered as part of thecommand/application name provided (e.g. "Google Chrome" not "Google" with"Chrome" argument). This option will be initiated when starting on a task.

The ``block`` option behaves exactly like ``close``, except that it runscontinously while the task is active (approximately once a second).

The ``run`` and ``close`` options also support the "end_" prefix which willinstead be activated when a task is manually ended.

For example: ::

apps { run /path/to/file; # run app at task start close /path/to/file; # close app at task start end_run /path/to/file; # run app at task end (manual) end_close /path/to/file; # close app at task end (manual)

The ``duration`` option will automatically end the task after the specifiednumber of minutes. This option supports only a single value > 0 and theoption cannot be defined more than once.

This also enables the ``left`` command when running the ``focus`` program toview remaining task time.

Additionally, any options that support the "end_" prefix will also supportthe "timer_" prefix. They function similar to "end_" prefixed options, exceptthey are only activated after the task timer has elapsed.

Under the hood, Focus updates the system HOSTS file (/etc/hosts) with mappingsof the provided domains to the local machine. Because of this, you will have toprovide an entry for each relevant subdomain as well if necessary. As a result,this strategy won't scale when blocking a site with numerous subdomains.Perhaps, another solution like a local DNS server would be more appropriate(e.g. `dnsmasq <http://www.thekelleys.org.uk/dnsmasq/doc.html>`_).

As a convenience, any domains configured will also map the followingsubdomains: ``m``, ``www``, ``mobile``.

The ``play`` options for the ``sounds`` block support the path to a sound filethat is playable on your system via available external binaries (``mpg123``,``play``, and ``aplay`` [WAV only]). Only a single value is supported for eachoption, and each type of option cannot be defined more than once. Make sureyour preferred binary is installed and works correctly by manually running yoursound file through the program.

The ``show`` options for the ``notify`` block support a single message thatwill be shown as a system notification. Only a single value is supported foreach option, and each type of option cannot be defined more than once.

On Linux/Unix, the feature functions via the DBUS IPC bus. On Mac OSX, externalbinaries (``terminal-notifier`` and ``growlnotify``) will be used whenavailable; otherwise, a fallback alert dialog will be shown. If using Mac OSX,make sure your preferred binary is installed and works correctly, unless thefallback method is desired.

The ``im`` block allows for options to update the status information fora number of running instant messenger applications.

The ``status_msg`` option supports defining a name that can be referenced whenspecifying the ``status``, ``end_status`` and ``timer_status`` options. Theoption takes two arguments: the first being the identifier name, and the second,the value for the status message. The option can be defined more than once todefine multiple status messages to use.

For the optional message argument, a string value may be provided. To referencean existing ``status_msg`` option definition, simply provide the ``status_msg``name prefixed with ":" (e.g. :working, :brb, :omg). The ``status`` option alsosupports the "end_" and "timer_" prefixes which will instead be activated whena task is manually ended or after the timer elapses, respectively.

Focus provides a simple and flexible plugin system to extend the corefunctionality. In fact, plugins are used internally for everything.

Installing Plugins------------------

After running the ``focus`` command, the ``.focus`` directory is created inyour home directory ($HOME or ~). Under that lives a ``plugins`` subdirectory,where you can drop your .py python plugin files. If they are valid, the pluginswill automatically become available when running ``focus``. For commandplugins, running ``focus`` will print a help banner with the installedcommands, which will include your plugins.

*Remember, if the plugin is available only for active tasks, the appropriatetask must be active to see your plugin show up.*

Command Plugins---------------

Command plugins define the commands that are available for the Focus binary(e.g. ``on``, ``make``, etc.). These can be available always, only for tasksthat define certain options, or only for active tasks.

The ``command`` class attribute identifies the plugin as a command plugin andspecifies the actual command name to register with the plugin.

*Note: The command name should be unique.*

The plugin should define the ``execute()`` method for running the command. The``env`` argument represents the environment and the ``args`` argument is theresult of parsing the command-line arguments using the ``ArgumentParser``object.

To simply print an error message, use the ``env.io.error()`` method. If youneed to also return a specific error code along with printing an error messageraise a ``FocusError`` exception from the ``focus.errors`` module: ::

If the plugin needs to define any command-line arguments, it should define the``setup_parser()`` method. The ``parser`` argument is an instance of``argparse.ArgumentParser`` and should be updated as necessary to addarguments.

Task event plugins are only available for active tasks. They can be registeredto run at the start of the task, during the task loop (every second), at theend of a task, or some combination therein. These plugins will be run within adaemon process when the task starts.

The ``events`` class attribute identifies the plugin as a task event plugin andspecifies the events of the task that should be registered: ``task_start``,``task_run``, ``task_end``.

The plugin should define the ``on_taskstart()``, ``on_taskrun()``, or``on_taskend()`` methods corresponding to the values provided for the``events`` attribute. The ``task`` argument represents the active task, whichincludes ``name``, ``duration`` (minutes), and a few methods such as``start()`` and ``stop()``.

Two attributes exist to allow plugins to only be loaded for active tasks:

1. **options**

Set the ``options`` class attribute. This defines the options that, if provided in a task configuration file, will trigger the load of this plugin. Options are either non-block (e.g. ``duration``) or block (e.g. ``apps`` => { ``run``, ``close``, ``block`` }, ``sites`` => { ``block`` }, etc.). When this attribute is set, the plugin should define the ``parse_option()`` method in order to parse the values set in a task configuration file. See example below.

def parse_option(self, option, block_name, *values): # raise ValueError exception with a message to reject the provided # value. this will propagate up to the cli when loading a task

Here, the ``option`` and ``block_name`` names for the currently parsed option are provided. ``block_name`` will be ``None`` when parsing non-block options. ``values`` holds one or more values associated with the provided option.

2. **task_only**

Set the ``task_only`` class attribute, so the plugin will be available for any task once started.

**Plugin Snippet:** ::

class Foo(Plugin): ... task_only = True ...

Root Access-----------

If a plugin needs root access, it should define the ``needs_root`` attribute.When set, this installs a ``run_root()`` method on the plugin class, whichaccepts an arbitrary command string and returns a boolean for success orfailure. Internally, Focus uses the ``sudo`` command to temporarily escalateprivileges.