=====
Usage
=====

Using twodolib as a Python module
---------------------------------

Create a task::

    >>> from twodolib import TwoDoTask
    >>> my_task = TwoDoTask('Save the world.', priority=TwoDoTask.PRIO_HIGH)

    >>> my_task.url()
    u'twodo://x-callback-url/add?task=Save%20the%20world.&priority=3'

Create a task, save it to 2DoApp and retrieve the task id:

    >>> my_task = TwoDoTask('Save the world.', priority=TwoDoTask.PRIO_HIGH, for_list="inbox")

    >>> # save the task in 2DoApp
    >>> import subprocess
    >>> subprocess.call(['open', my_task.url()])
    0

    >>> # retrieve taskid
    >>> my_task.get_taskid()
   '181378c217dd4f029a6ec7a47e65550d'



Using twodolib from the command line
------------------------------------

You can call ``task2do`` with a whole bunch of options. But it is easy to
add a standard task. Just enter::

    task2do -d 1 "Dinner at 8pm."

And you will get the URL to add a task, which is due tomorrow::

    twodo://x-callback-url/add?task=Dinner%20at%208pm.&due=1

Use the URL with Safari or Alfred or another launcher to actually create the
task. Or just provide the ``-e, --execute`` option, to actually create the
task in your 2Do App::

    task2do -e -d 1 "Dinner at 8pm."

You'll get help with the ``-h, --help`` option::

   usage: task2do [-h] [-t {0,1,2}] [-l FOR_LIST] [--project IN_PROJECT]
                  [-n NOTE] [-p {0,1,2,3}] [-s] [--tags TAGS] [-d DUE]
                  [--dueTime DUETIME] [--start START] [--repeat {1,2,3,4}]
                  [-a ACTION] [-i] [-e] [-v]
                  task

   Program to create tasks in 2Do. The default behavior is to print the generated
   URL to stdout. Please use the '-e' or '--execute'' option, if you want to send
   the task directly to the 2DoApp.

   Examples
   ========

   Add a task due tomorrow:
   task2do -d 1 "Dinner at 8pm."

   Add a task with high priority:
   task2do -p 3 "High priority task."
   - or -
   task2do --priority 3 "High priority task."

   Add a task due today and repeated weekly:
   task2do "change clothes" -d 0 --repeat 2

   Add a task due at 6pm today
   task2do "Watch EX_MACHINA" --due 0 --dueTime 18:00

   Add a task due tomorrow, with tags, which is also starred and repeated monthly
   task2do "Monthly subscription." --tags bill,payment -s --due 1 --repeat 4

   Add a task with an url action (open a link)
   task2do "Read help text" -a url:https://www.2doapp.com/
   task2do "Read help text" --action url:https://www.2doapp.com/

   Add a Subtask in list personal in project errands:
   task2do "Buy milk." -l personal --project errands

   positional arguments:
     task                  Title of the task.

   optional arguments:
     -h, --help            show this help message and exit
     -t {0,1,2}, --type {0,1,2}
                           Type of task to create. The following options are
                           supported: 0 - Task (default), 1 - Project, 2 -
                           Checklist
     -l FOR_LIST, --list FOR_LIST
                           Name of an existing list in 2DoApp, case-insensitive.
                           If missing, the default list or the currently visible
                           list on screen is used.
     --project IN_PROJECT  Name of an existing project in 2DoApp, into which the
                           task will be pasted. So you can create subtasks.
     -n NOTE, --note NOTE  Notes for the task
     -p {0,1,2,3}, --priority {0,1,2,3}
                           priority: 0 (none), 1 (low), 2 (medium), 3 (high)
     -s, --starred         Mark task as starred.
     --tags TAGS           Comma separated list of tags to assign to the task
     -d DUE, --due DUE     Due date. Supports two formats: YYYY-MM-DD - Sets the
                           date on default due time (based on your settings),
                           unless due time is specified separately or
                           ignoreDefaults (-i) is given. OR: Number of days due
                           from today. Which means: 0 = today, 1 = tomorrow and
                           so on)
     --dueTime DUETIME     Due time. Supports 24h format HH:MM.
     --start START         Start date and time. Supports the format: "YYYY-MM-DD
                           HH:MM" - Sets the start date to the date and time
                           specified - OR - Any number with 0 = today, 1 =
                           tomorrow and so on)
     --repeat {1,2,3,4}    Repeat task: 1 (daily), 2 (weekly), 3 (bi-weekly), 4
                           (monthly))
     -a ACTION, --action ACTION
                           action: Supports the following formats: call:<number>
                           - Add a Call action to call the specified number
                           message:<number> - Add a Message action to send a
                           message to the specified number mail:<email> - Add a
                           Email action to send an email the specified email
                           address url:<url to visit> - Add a Browse action to
                           visit the specified URL address visit:<address> - Add
                           a Visit action to visit the specified location
                           google:<search term> - Add a Google action to search
                           the specified keyword Enter the arguments after the
                           colon without the angle brackets. For more details:
                           SEE https://www.2doapp.com/kb/article/url-schemes.html
     -i, --ignoreDefaults  Ignore default date / time settings of 2DoApp.
     -e, --execute         Actually add the task instead of only printing the URL
                           to stdout.
     -v, --version         show program's version number and exit

Examples
--------

Add a task due Tomorrow::

    task2do -d 1 "Dinner at 8pm."

Add a task with high priority::

    task2do -p 3 "High priority task."
    task2do --priority 3 "High priority task."

Add a task due today and repeated weekly::

    task2do "change clothes" -d 0 --repeat 2

Add a task due at 6pm today::

    task2do "Watch EX_MACHINA" --due 0 --dueTime 18:00

Add a task due tomorrow, with tags, which is also starred and repeated monthly::

    task2do "Monthly subscription." --tags bill,payment -s --due 1 --repeat 4

Add a Subtask in list business in project webpage::

   task2do "Make webpage GDPR compatible." -l business --project webpage

If you use a project, you must provide a list, too.
