• Specifying the tasklist and task
• Shortcuts
• Summary of available Switches (command-line options)
• Details for Switches

The behavior of ToDoList can be set on execution from the command-line. This is usually set in the shortcut used to execute the program (see below for setting up a shortcut), but can also be used as automation for another process to set values while the application is up.

Commands can also be executed as a User-Defined Tool (UDT). In this case, ToDoList re-executes itself, passing specific parameters in the command-line. This is essentially the program telling itself to do something - the result being a limited form of automation. An example might be a UDT to close a task, simultaneously changing the status and adding a comment.

As with most Windows programs that support options (also called “switches”, like a light on/off switch), the pattern to follow is:

  X:\path\to\executable\ToDoList.exe -a valuea -b "value b" -tid 000 "filepath"

In all of these examples, a value must be enclosed in quotes if it contains a space, otherwise quotes are not necessary.

The filepath to the affected tasklist .tdl file should be specified at the beginning or end of the command, either will work. However, if the filepath follows a sequence of values it will be included in those values, so the filepath should be first. Example:

  X:\path\to\executable\ToDoList.exe -tid 123 -c category1 category2 "filepath"

That results in three categories on the current tasklist, the third is the filepath. Instead use this format to get two categories on the specified tasklist:

  X:\path\to\executable\ToDoList.exe "filepath" -tid 123 -c category1 category2

In Windows, switches can be in upper-case or lower-case, it doesn't matter. In Linux, switches may need to be in lower-case.

When ToDoList is executed from a command-line: If the application is not open it is opened. If the application is already open, the most recent active/existing instance is used. (See Multiple Instances.) The <filepath> parameter *must* be used when sending a command to a list or task, or the command will transparently fail. (The <filepath> does not need to be specified in a shortcut when re-opening a collection of tasklists, as the .ini file includes the list of tasklists to open. A command targeting a list or task without a filepath will always open a new instance of the application but it won't do anything.) If the specified tasklist is not already open it will be opened and this becomes the currently selected tasklist. If the -tid switch is used, the indicated task then becomes the currently selected task, otherwise the currently selected task will be operated on.

To create a Windows shortcut:

• Use the right-mouse on ToDoList.exe.
• Select Create Shortcut. This creates file “ToDoList.exe - Shortcut”.
• Move this file to your desktop.
• Rename the shortcut file to something like, um “ToDoList'.

To modify the command-line used by that shortcut:

• Right-mouse the shortcut file and select Properties.
• Select the Shortcut tab if it's not already selected.
• The Target field already has a full “x:\path\ToDoList.exe”. Modify this with any of the options from this page.
• Since we're here… You may need to execute ToDoList with Administrator privileges so that it can write to files or download updates. To do this, on the Shortcut tab, click Advanced. Then check “Run as Administrator”. Then click OK.
• When done, click OK to save and exit.

The text following the -ab switch simply sets the Allocated By field to the value following the switch. This is the person (company, department, entity) assigning the task. For example, '-ab Sales' or '-ab “Renee Schmidt”'. There is only one Allocated By entity.

The text following the -at switch sets the Allocated To field to the value(s) following the switch. This is the person (company, department, entity) to whom the task is being assigned. Multiple Allocated To values can be specified, where more than one entity is responsible for completion of the task. Examples:

todolist.exe -at Sales
todolist -at “Dave Jones”
todolist -at Connie Dave
todolist “C:\path\list.tdl” -tid 4 -at “Dave Jones” “Connie Smith”

To set all values, removing prior values, just follow the switch with the name(s) as seen above. To add entities, see Adding Values.

To clear all values, use two consecutive double quotes ( ”“ ): -at ”“

Used with the -nt switch to create a New Task, the -bid switch causes the new task to be added after and at the same level as the specified task ID. To create a sub-task, use -pid.

The -c switch must be followed by a category name. Multiple categories are separated by spaces (prior to 7.0.1 the delimiter was comma). If a category includes a space, enclose the value(s) in quotes. Examples:

todolist.exe -c MyCategory
todolist -c “My Category”
todolist -c First Second
todolist “C:\path\list.tdl” -tid 4 -c “Cat 1” “Cat 2”

To set all values, removing prior values, just follow the switch with the name(s) as seen above. To add entities, see Adding Values.

To clear all values, use two consecutive double quotes ( ”“ ): -c ”“

Concerns…

• Category names are case-INsensitive. If you specify the “docs” category, and the “Docs” category already exists, the field will be set to “docs” and the tasklist-wide list of available categories will then include the lower-case version. This could present issues with case-sensitive use of data outside of the application.
• The switch value will be used even if it is not defined in Preferences > Tasks > Defaults > Task Attributes > Dynamic Droplists, and with the “Make this list read-only” checkbox set. The application user interface (UI) does restrict entry when that option is set, but the command-line switch is not limited by the option.
• Setting a category adds it to the list of selectable values for the specific tasklist. Once added these cannot be removed (at this time) without editing the .tdl file.

See Dates and Times for specifics on formatting of date and time values. When not specified, the default completion time is 11:59PM.

Here are examples for using the -cd switch:

todolist -tid 6 -cd 8/18
todolist -cd 2015-8-18
todolist -cd “8/18/15 14:15”
todolist -cd “7-31-15 4:20pm”
todolist -i ”.\myconfig.ini“ “mylist.tdl” -tid 3 -cd ”“
todolist -tid 6 -cd 2015-07-30T08:19

A number of days can be added or subtracted to the date field by appending a + or - to the value:

-cd +7
-cd -1

Relative dates can also be used:

-cd M+1

When the completed date is set, the Status is set to Complete and the Completed Date checkbox is set.

To clear the completion date simply use the -cd switch without an associated value.

When setting a completed date for a parent task when child tasks are not complete, ToDoList will open a Yes/No dialog to ask if you want child tasks to also be flagged as complete. This can be an issue with automation. There is currently no way to suppress the dialog.

The specs for this -cd command are exactly the same as for the -dd switch for setting the Due Date. Similarly -ct and -dt function in the same way.

The text following the -cm switch is added to the Comment field. This is very useful in automation which logs task activity. Line breaks are specified with \n, which is a common way to add a line feed or x0A value. So to add 3 lines to the current Comment field : -cm “Line 1\nLine 2\nLine 3”

• There is currently no mechanism to change the comment format between plain and rich text.
• There is currently no mechanism to get the app to generate the Date and Time into a comment. The command-line processor must generate this value and insert it into the text being assigned to the comment.
• There is currently no mechanism to clear comments. This -cm switch is used to Append text, not replace it.

When ToDoList is opened it can be set to go directly to any command offered in the menu system. Every menu option has an ID which is used with this command. To find the ID for a specific menu item, go to menu > Tools > Preferences > Keyboard Shortcuts. At the bottom of the form, check “Show menu item IDs”. The ID number displays next to every menu option. So to open ToDoList and force it to go to Transform Tasklist (under Tools), use : -cmd 33024

At this time text and other selections cannot be forced to a dialog/window once it opens. So with the Transform example, the window will open but a user must enter specs and click OK to continue.

Multiple commands can be executed by joining them with the '|' (pipe) character.

This allows attribute values to be copied between different attributes, subject to the following conditions:

• 'attrib1' and/or 'attrib2' can reference:
  • Built-in attributes, using the corresponding command-line identifiers elsewhere on this page
  • Custom attributes, using their unique identifier name
• Creation Date and Created By cannot be changed
• The two attributes must have equivalent types ie. Text, Numbers, People
• Some built-in attributes can only be copied to custom attributes and not to other built-in attributes: case Cost, Recurrence, Colour, Percent Completion, Comments, Dependencies, File Links.

Examples:

The task gets set with any valid integer or floating-point number (doesn't need to be dollars and cents or have two decimal places). Examples:

-cs 1050
-cs 899.98
-cs 123.4567
-cs ”“
-cs 0

A value can be added or subtracted to the cost field by appending a + or - to the value:

-cs +250.25
-cs -1

See the -cd switch for full information about the Completion Date and Time. This switch allows for setting the time value only.

This switch does not currently support a +/- prefix to add/subtract to the time. Support for this is coming in 7.3.

The task ID which follows the -dp switch must be complete before the current task can be flagged as completed. Stated another way, the specified task is a requirement/prerequisite for the current task. More than one such tasks can be specified by enclosing the task IDs in a single space-delimited, quoted value: todolist -tid 10 -dp “2 6 7”

The -dd switch sets the Due Date and Time. -dt sets time-only. All of the details are exactly the same as for the -cd switch that sets the completed date/time, except that the Status is not changed and the Completed flag is not set.

See Dates and Times for specifics on formatting of date and time values. When not specified, the default due time is 11:59PM.

See the -dd switch about the Due Date and Time. This switch allows for setting the time value only.

This switch does not currently support a +/- prefix to add/subtract to the time. Support for this is coming in 7.3.

If todolist.exe is run without the -i option, the default .ini file is used, and the list of most recently used tasklists from the .ini are used to open tasklists.

If the -i option is used, the tasklists from the specified .ini are used.

If only one tasklist is required, the <filepath> spec parameter can be used. The <filepath> is really the value associated with a default -f switch, so a single -f with a filepath is the same as a single <filepath> with no switch.

With the -f switch, two or more .tdl tasklists can be specified. While a single <filepath> doesn't require the -f switch, all other lists must be preceded by the -f switch. When opening more than one tasklist file, it's advisable to be consistent and use the -f switch for all files.

For example: todolist “c:\path\list1.tdl” -f “c:\path\list2.tdl”
todolist -f “c:\path\list1.tdl” -f “c:\path\list2.tdl” -f “c:\path\list3.tdl”
todolist -i “c:\special.ini” -f “c:\path\list1.tdl” -f “c:\path\list2.tdl”

The INI governs the behaviour of all tasklists that are opened in this manner. Be careful about using more than one INI against a given tasklist, as the data could be confusing and might be modified in a manner that is inconsistent for someone using a different INI.

Each task can have one or more file links associated, for documents, web pages, etc. The -fr switch is followed by a filename to add the specified file to the File Link list. The path is converted from an absolute path to a path relative to the Resources folder of the ToDoList.exe install folder. Verify. (Through v7.0.0, only one file link could be added per command-line. This was fixed in 7.0.1.)

To set all file links, removing prior links, just follow the -fr flag with the file names: -fr “c:\path\file1.ext” file2.ext ..\file3.ext

To add file links to the existing list, prefix only the first link with a plus sign ”+“: -fr +additional_file.ext “d:\temp\some other additional file.ext”

To clear all file links, use two consecutive double quotes ( ”“ ): -fr ”“

Do not add a plus to all files, only the first one. The first file triggers the addition of file names - adding a plus to subsequent file names results in “undefined” behaviour.

Turns on the application's logging system which is primarily used for checking the performance of loading and saving tasklists.

Sometimes it is also used to debug specific reported issues that are proving difficult to reproduce.

The log file can be found in the application folder and has the name 'ToDoList.log”.

With any of the three switches, -h, -help, or -?, a window opens to display a summary of the available switches. This should not be used by “headless” automation.

Multiple instances of ToDoList can be executed simultaneously, with each using a different .ini Configuration file. If not specified in the command-line, the default configuration file is ToDoList.ini, in the root folder along with the .exe and .dll files. C:\SpecialApps\ToDoList\ToDoList.exe -i “C:\Users\me\Documents\Tasks\ToDoListLive.ini”

The ini full path follows the -i option. The file name does not need to be the default ToDoList.ini.

This option also brings application window to the foreground.

There are two types of task link both of which must be prefixed by the TDL protocol

tdl://

1. Specify only the ID of the task to be selected in the currently active tasklist.

Example: tdl://2

See also: Edit > Copy As > Task Link

2. Specify the fully qualified, and escaped, path of a tasklist to be opened/selected, followed by a question mark, and then the task ID of interest.

Example: tdl://C:/My%20Tasklists/My%20Tasklist?3

See also: Edit > Copy As > Task Link (full)

Imports the specified file

The creation date can only be specified on a new task created with the -nt switch. The creation date cannot be set on an existing task. Example: todolist.exe -i “my_default_config.ini” -nt “Tasks for Monday” -md 9/6

See Dates and Times for specifics on formatting of date and time values.

Creates a new task in the active tasklist with the specified title. Use the -bid switch along with -nt to add the task as a sibling of another. Use with the -pid switch to create a sub-task. Defaults not set from the command-line will be set according to the currently active .ini preferences and tasklist-specific defaults.

Example: todolist.exe -i “my_default_config.ini” -nt “New Task Title”

See the -pid switch to specify the parent task ID for new tasks, or -bid to specify a sibling task ID. When no other task is specified, a new task is added to the top of the tasklist tree.

Valid values are from 0 to 10 (lowest to highest), or “n” for None. If the value “n” is used, it must be in quotes, otherwise the value is set to zero.

A value can be added or subtracted to the priority field by appending a + or - to the value:

-p +1
-p -1

• The “n” value may not work correctly in 7.0.8.
• There is currently no mechanism for reversing the order of the priority, for example so that the highest priority is #1.
• An attempt to set the value lower than 0 or higher than 10 results in the request being discarded. The min/max value is not set automatically.

Valid values are from 0 to 100. Do not use the percent sign in the value.

A value can be added or subtracted to the priority field by appending a + or - to the value:

-pc +1
-pc -1

• An attempt to set the value lower than 0 or higher than 100 results in the request being discarded. The min/max value is not set automatically.

Used with the -nt switch to create a New Task, the -pid switch causes the new task to be added after and as a sub-task of the specified task ID. To create a sibling task, at the same level as another, use -bid. When no other task is specified, a new task is added to the top of the tasklist tree.

Valid values are from 0 to 10 (lowest to highest), or “n” for None. If the value “n” is used, it must be in quotes, otherwise the value is set to zero.

A value can be added or subtracted to the risk field by appending a + or - to the value:

-r +1
-r -1

• The “n” value may not work correctly in 7.0.8.
• An attempt to set the value lower than 0 or higher than 10 results in the request being discarded. The min/max value is not set automatically.

The specified value is assigned to the Status field.

Cautions:

• The switch value will be used even if it is not defined in Preferences > Tasks > Defaults > Task Attributes > Dynamic Droplists, and with the “Make this list read-only” checkbox set. The application user interface (UI) does restrict entry when that option is set, but the command-line switch is not limited by the option.
• Setting a status adds it to the list of selectable values for the specific tasklist. Once added these cannot be removed (at this time) without editing the .tdl file.

This is the date/time when the task is expected to start, or when it actually did start.

See Dates and Times for specifics on formatting of date and time values. When not specified, the default start time is 12:00AM.

Setting the time without the date using -sd currently results in an erroneous date of 12/30/1899. See the -st switch to set the time without the date.

A number of days can be added or subtracted to the date field by appending a + or - to the value:

-sd +7
-sd -1

When using the Transform functionality, a new XML tasklist file is created which is a subset of the currently selected list. This subset is filtered and sorted as required. The .xslt transform is then run against this intermediate file, and then the file is deleted. It's often helpful to see this temporary file to diagnose issues in a transformation. The -si switch will cause any transform-generated temporary tasklists to be saved to your Temp folder so that you can inspect them.

To see this file, after setting the -si option, opening the application, and doing a transform: In the Windows Explorer address bar, type “%temp%” and Enter to open the folder. There you should find nameOfYourTasklist.intermediate.txt. You can also find this from C:\Users\yourname\AppData\Local\Temp.

New in v7. See the -sd switch for full information about the Start Date and Time. This switch allows for setting the time value only.

This switch does not currently support a +/- prefix to add/subtract to the time. Support for this is coming in 7.3.

The estimated time to complete the task gets set with any valid integer or floating-point number. See -ts to set the actual time spent. Examples:

-te 12
-te 3.5
-te “”
-te 0

As of 7.0.2, using this switch resets the Time Estimate Units to Hours. Do not use this switch yet to set days, months, or years.

This switch follows the same rules as the -c switch to set Categories

This executes ToDoList and forces the selection to move to the specified task so that subsequent editing operations can be performed. A task ID without a tasklist specification isn't useful. To open a specific tasklist add the path to the file to the end of the command-line. For example: C:\SpecialApps\ToDoList\ToDoList.exe -tid 291 “C:\Users\me\Documents\Tasks\HomeStuff.tdl”

To get a UDT to perform an operation on a specific task ID, set the argument as follows: -tid $(selTID)

And to prompt for a task ID in a UDT: -tid $(userText, var, “Task ID”)

Note that issues have been reported if -tid is used to specify a task that does not exist. Do not use -tid with -nt to create a new task - the ID for a new task cannot be specified.

The actual time spent on the task gets set with any valid integer or floating-point number. See -te to set the estimated time versus the actual time. Examples:

-ts 12
-ts 3.5
-ts “”
-ts 0

Time can be added or subtracted to the time spent field by appending a + or - to the value:

-ts +2.5
-ts -1

Cautions:

• From v7.0.2 to v7.0.7, using this switch resets the Time Spent Units to Hours. This was fixed in v7.0.8.
• The time value is always hours, even if the time spent units is not. For example, if the units is Days, -ts +1 adds one hour, not one day. Calculate the desired units from hours when setting the value. 5 minutes = 5/60 etc.
• Setting this value via the command-line can conflict with the Preference to aggregate (calculate) the time spent value from child tasks.

This is freeform text which is intended to identify a version/release ID where an issue was reported, fixed, or where a fix will be deployed. Usage is entirely defined by the user. The value is added to a tasklist-specific list which is available to all other tasks after first usage. Clear the field using ( “” ) as the value.

Forces ToDoList to startup visible regardless of its last saved state

Turns off password prompting except when first loading an encrypted tasklist

This is freeform text which is intended to identify an ID in an external tracking system, like Bugzilla or GitHub Issues. Usage is entirely defined by the user. The value is added to a tasklist-specific list which is available to all other tasks after first usage. Clear the field using ( “” ) as the value.

Historically, all settings related to a TaskList have been stored in ToDoList.ini for all TaskLists. This isn't a problem until the TaskList is shared on many computers. An example of a problem that arises is that you have to manually say which column is visible on each PC. Columns visibility is just one setting. Also, if you move your TaskList to another computer, your settings don't follow automatically. This can especially be a pain when the new computer already has ToDoList, and you have to manually copy some parts of one ToDoList.ini to another. (This information comes from @PatriceTorchet.)

The -z option is the first step to move tasklist-specific settings from the .ini file into the tasklist .tdl file.

Are there any other steps? Might help to get a list of all config values moved in, and then to get details on where those values are stored in the tdl.

A date can be in almost any valid format when following a switch. Simple/standard date formats are recommended. Local conventions are used to distinguish between YY-MM-DD, MM-DD-YY, etc. Also valuid is the format MMM-DD or DD-MMM, where MMM is the first three letter of a month name.

The time can follow the date if the entire value is surrounded by quotes, or with a space delimiter (“mmm-dd hh:mm”). Comma and “T” may work as the delimiter, but it is not advised to get creative with this. When used in ISO format like the last example below, the date must be in YYYY-MM-DD format, and the time must be in 24-hour (military) format.

Without a specified time, the time for a Start date defaults to 12:00am, while the default for a Completed date is 11:59PM (prior to v7.0.x this was also 12:00AM). Without a specified date, the date should remain unchanged though as of v7.0.2 there are still examples of this not being the case. Use an explicit date wherever possible.

Examples: 8/1 13:30
1-aug 7:15
jan-1 12pm
2015-07-30T08:19

To add values to an existing list, prefix only the first value with a plus sign “+”. This applies to Allocated To, Categories, Tags, and perhaps other alpha fields: -at +Sales
-c +additional_category “some other additional name”
-tg +london sydney
The “+” sign is only required on the first value. Other values do not need a +sign but will be added to the list of values.

When a name is quoted, the plus can be inside or outside of the quotes: -c +“add this” and_this
-c “+add this” and_this

• Currently, the entry field does not immediately reflect a +change but the value is changed.
• Do not add a plus to all categories, only the first one.
• The first name triggers the addition of categories to the existing list - adding a plus to subsequent names results in “undefined” behaviour.
• Using a comma to delimit categories does not result in multiple categories, but in a single category with embedded commas: “first,second”.
• The -value syntax for removing values is not yet available for alpha/list fields.