CLI

Taskopen 2.0 Command Line Interface

This page documents the command line interface of taskopen 2.0.

Principles

One of the drawbacks of earlier taskopen versions was the lack of clarity in the command line interface. A lot of functionality was hidden in a plethora of single-character arguments. This originated from the goal of having a brief and clean interface (faster typing) similar to taskwarrior. Yet, it turned out to significantly limit the accessibility.

The new CLI therefore prefers clarify and generality over brevity. Ideally, arguments are self-explanatory. Depending on the personal use case, wrapper skripts or aliases can be used to reduce typing effort.

The drawback of this principle is the lack of backward compatibility. Yet, a migration guide shall help with the conversion from taskopen 1.x to 2.0.

Interface

For best compatibility existing command line parsers, the CLI shall follow the Unix command line style with case-insensitive short (-s) and long (--long) options (with or without values) as well as positional arguments. Moreover, positional subcommands as in git help with structuring the CLI. As a result, the command line has the following signature:

taskopen [subcommand] [options] [filter1 filter2 .. filterN]

Subcommands

The modes of taskopen can be made accessible via subcommands. The default subcommand of taskopen should be the normal mode. Consequently, subcommand batch and any will switch the mode of taskopen. In addition, subcommands version and diagnostics are used for printing version information and diagnostic information. It might also be worth considering individual actions as configurable subcommands to conventiently force taskopen to a certain action.

Options

Options of taskopen are subdivided into four categories: output control, config overrides, includes/excludes, and filter control.

Output control:

• -v/--verbose: Prints additional info messages (e.g. the command line to be executed by taskopen).
• --debug: Prints debug messages (includes -v).
• -h/--help: Prints help message.

Config overrides:

• -s/--sort key1+,key2-: Changes the default sort order of annotations.
• -c/--config filepath: Use a different config file.
• -a/--active-tasks filter: Changes the filter used by taskopen to determine active tasks.
• -x/--execute cmd: Overrides the command executed by taskopen for every action.
• -f/--filter-command cmd: Overrides filter command for every action.
• -i/--inline-command cmd: Overrides inline command for every action.
• --args arguments: Allows definition of arguments that will be available as $ARGS in taskopen actions.

Includes/excludes:

• --include action1,action2: Only consider the listed actions. Also determines their priority.
• --exclude action1,action2: Consider all but the listed actions.

Filter control:

• -A/--All: Query all tasks, including completed and deleted tasks.

A special case for --config is when the config file does not exist. Taskopen will ask the user whether the config file shall be created. When creating the config file, taskopen uses all options passed before the --config option as defaults.

Migration

Taskopen 1.x	Taskopen 2.0
-h	-h or --help
-v	version
-V	diagnostics
-l	-x or --execute
-L	-v or --verbose
-b	batch
-n	--include=notes
-N	--exclude=notes
-f	--include=files
-F	--exclude=files
-B	-f 'test ! -e $FILE
-t	--include=text
-T	--exclude=text
-a	-a
-A	-A
-D	--include=delete or delete
-r	--include=raw or raw
-m 'regex'	/regex/
--type 'regex'	-f "file $FILE | perl -ne 'if($_ !~ m/regex/){exit 1}'"
-s key1+,key2-	-s key1+,key2-
-e	-x 'vim $FILE'
-x 'cmd'	-x 'cmd'
-i 'cmd'	-i 'cmd'
-c filepath	-c filepath
-p cmd	automatic detection