node module: rtm-cli
GitHub repo: dwaring87/rtm-cli
This Node module provides a command line interface, written in JavaScript, for the popular Remember the Milk task list manager.
If you already have Node installed, this program can be
installed via npm:
npm install -g rtm-cliwhich will install the executable rtm into your $PATH.
Standalone executables, that do not require a pre-existing installation of Node, are available in the Releases page.
The main usage of the program:
Usage: rtm [options] <command> [command arguments]
Options:
-V, --version output the version number
-p, --plain do not use styled/colored text (overrides --color)
-c, --color force the use of styled/colored text
-s, --status toggle the display of the status spinner
-x, --completed [value] set display of completed tasks (true/false/number of days)
-d, --hideDue [value] hide tasks due more than n days from today (false/number of days)
-f, --config [file] specify configuration file
-h, --help output usage information
Commands:
add|a [task...] Add a new Task
addList|al [name] [filter...] Add a new List or Smart List
addTags|at [index] [tags...] Add one or more tags to a Task
comp|x [indices...] Complete one or more Tasks
decPri|- [indices...] Decrease the Priority of one or more Tasks
due [index] [due...] Set the Due Date of a Task
edit [index] [name...] Change the name of a Task
incPri|+ [indices...] Increase the Priority of one or more Tasks
lists|l Display all lists
login Add RTM User information
logout Remove RTM User information
ls [filter...] List all tasks sorted first by list then by priority
lsd [filter...] List all tasks sorted first by due date then by priority
lsp [filter...] List all tasks sorted first by priority then due date
move|mv [index] [list...] Move Task to a different List
planner [options] [filter...] Display tasks in a weekly planner (--start: sun, mon, today)
postpone|pp [indices...] Postpone one or more Tasks
pri|p [index] [priority] Change Task Priority
remove|rm [indices...] Remove one or more Tasks
removeList|rml [name...] Remove a List
removeTags|rmt [index] [tags...] Remove one or more tags from a Task
renameList|mvl [oldName] [newName] Rename a List
reset Reset cached task indices
tags|t Display all tags
uncomp|unc [indices...] Mark one or more Tasks as not complete
whoami Display RTM user information
today Display tasks with a priority, due or completed today, or overdue
An interactive mode is started when no commands are given to rtm, which
allows commands to be given sequentially.
Use the quit command to leave the interactive mode.
Display output text without any styling and/or colors. This option overrides the default in the configuration files.
Note: This option overrides --color, if provided, and will disable the
status/spinner text.
Default: Display styled/colored output.
Force the display of output text using special styling and/or colors. This option overrides the default in the configuration files.
Default: Display styled/colored output.
Toggle the display of the status/spinner text messages. This option will toggle the default value in the configuration files.
Note: When status messages are disabled, error messages will not be displayed and any errors encountered will be silently ignored.
Default: Display status/spinner messages.
Specify how completed tasks should be displayed. This option overrides the default in the configuration files. Valid values include:
| Value | Description |
|---|---|
| true | Display all completed tasks |
| false | Don't display any completed tasks |
| n > 0 | Display tasks completed within n days |
Default: 7
Hide tasks with due dates more than value days in the future. This option
overrides the default in the configuration files. Valid values include:
| Value | Description |
|---|---|
| false | Do not hide any tasks based on due date |
| n > 0 | Hide tasks with due dates more than n days from today |
Default: false
Specify a configuration file to use. Properties in this file will override the default configuration properties. RTM User information will be stored in this file.
Default: $HOME/.rtm.json
Display RTM CLI version
Display Usage Information
add [Task Name]
The Task Name can use RTM's Smart Add Syntax.
Additionally, to minimize the need to escape special characters at the command line,
the following properties can be specified:
- priority as
p:{priority} - list as
l:{list} - tags as
t:tag1 t:tag2 - due date as
due:{due date}
If Task Name is not provided, a prompt allowing multiple new task entries
will be displayed. Enter a blank line to finish adding new tasks.
Examples:
> add Buy Milk ^tomorrow !2 #Shopping
> add Feed The Cat today p:1 l:Chores t:pets *daily
addList [List Name] [Smart List Filter]
This command will add a new empty List to the User's account or if a
Smart List Filer is provided, a Smart List using the provided
advanced search criteria
will be created.
If no arguments are provided, a prompt allowing multiple new list names will be displayed. Enter a blank line to finish add new lists.
Examples:
> addList Bills
> addList Important priority:1 OR priority:2
addTags [index] [tags...]
This command will add one or more tags to a Task. Tasks are referenced by index number, which are displayed when listing tasks. Multiple tags can be provided as arguments to this command.
If no arguments are provided, a prompt allowing multiple task indices and tags to be entered will be displayed. Enter a blank line to finish adding tasks and tags.
Examples:
> addTags 1 rent
> addTags 5 rent bills
comp [indices...]
This command will mark the Tasks as complete. Tasks are referenced by index number, which are displayed when listing tasks. Multiple task indices can be provided as arguments to this command.
If no arguments are provided, a prompt allowing multiple task indices to be entered will be displayed. Enter a blank line to finish adding task indices.
Examples:
> comp 15
> comp 1 9 8
decPri [indices...]
This command will decrease the priority of the Tasks by 1. Tasks are referenced by index number, which are displayed when listing tasks. Multiple task indices can be provided as arguments to this command.
If no arguments are provided, a prompt allowing multiple task indices to be entered will be displayed. Enter a blank line to finish adding task indices.
Examples:
> decPri 15
> decPri 1 9 8
due [index] [due date]
This command will set the Due Date of a Task. Tasks are referenced by index number, which are displayed when listing tasks. Due Dates can be entered in any format that RTM can parse.
If no arguments are provided, a prompt allowing multiple task and due dates to be entered will be displayed. Enter a blank line to finish adding tasks and due dates.
Examples:
> due 1 tomorrow
> due 15 May 12
> due 3 days
edit [new task name]
This command will change the name of a Task. Tasks are referenced by index number, which are displayed when listing tasks.
If no arguments are provided, a prompt allowing multiple task indices and names to be entered will be displayed. Enter a blank line to finish adding indices and names.
Example:
> edit 1 Buy More Milk
incPri [indices...]
This command will increase the priority of the Tasks by 1. Tasks are referenced by index number, which are displayed when listing tasks. Multiple task indices can be provided as arguments to this command.
If no arguments are provided, a prompt allowing multiple task indices to be entered will be displayed. Enter a blank line to finish adding task indices.
Examples:
> incPri 15
> incPri 1 9 8
This command will display the names of all Lists. If the List is a 'Smart List', the search criteria will be displayed alongside the list name.
This command will remove any saved RTM user information and start the
login procedure. An Auth URL will be displayed and opened in the User's
browser. This URL will ask the User to grant RTM CLI access to their
account. Once authorized, the user's information (id, username, full name
and an Auth Token provided by RTM) will be saved locally ($HOME/.rtm.json
by default).
This command will remove any saved RTM user information. Any future requests to the RTM API Server will require the User to login again.
ls [filter]
This command will display the User's tasks sorted first by List then by priority. A filter, using RTM's Advanced Search Syntax can be used to filter the tasks displayed.
Examples:
> ls
> ls priority:1 AND list:Work
lsd [filter]
This command will display the User's tasks sorted first by Due Date (with tasks without a due date shown first) then by priority. A filter, using RTM's Advanced Search Syntax can be used to filter the tasks displayed.
Examples:
> lsd
> lsd priority:1 AND list:Work
lsp [filter]
This command will display the User's tasks sorted first by priority then by due date. A filter, using RTM's Advanced Search Syntax can be used to filter the tasks displayed.
Examples:
> lsp
> lsp priority:1 AND list:Work
move [index] [list name]
This command will move a Task to a different List. Tasks are referenced by index
number, which are displayed when listing tasks. The list name must be the
name of an existing List.
Note: This command will fail if there is more than 1 List matching the new List name.
Example:
> move 1 Work
planner [--start <sun, mon, today>] [filter]
This command will display this week's Tasks in a weekly planner table. The --start
option can be one of: sun, mon, or today and will set the first day
of the planner. An optional filter can be used to filter the displayed tasks.
Any incomplete tasks with a due date before the start of the planner and tasks
without a set due date will be displayed below the planner.
Examples:
> planner
> planner --start mon NOT due:never # Hide tasks with no due date set
postpone [indices...]
This command will postpone the due date of a Task by one day. Tasks are referenced by index number, which are displayed when listing tasks. Multiple task indices can be provided as arguments to this command.
Examples:
> postpone 1
> postpone 1 15 8
pri [index] [priority]
This command will set the priority of the tasks. Tasks are referenced by index
number, which are displayed when listing tasks. Acceptable priority values
include 1, 2, and 3 - any other value removes the priority from the task.
If no arguments are provided, a prompt allowing for multiple task and priority inputs is displayed. Enter a blank line to finish adding tasks/priorities.
Examples:
> pri 15 1
> pri 14 0
remove [indices...]
This command will remove the Tasks from the User's account. Tasks are referenced by index number, which are displayed when listing tasks. Multiple task indices can be provided as arguments to this command.
Examples:
> remove 1
> remove 1 15 8
removeList [name]
This command will remove the List matching the provided name from the User's
account. Any tasks remaining in the List will be moved to the User's Inbox.
Note: This command will fail if there is more than one List matching the provided list name.
If no list name is provided, a prompt allowing for multiple list names to be entered will be displayed. Enter a blank line to finish adding list names.
Example:
> removeList Bills
removeTags [index] [tags...]
This command will remove one or more tags from the Task. Tasks are referenced by index number, which are displayed when listing tasks. Multiple tags can be provided as arguments to this command.
Examples:
> removeTags 1 bills
> removeTags 15 bills rent
renameList [old name] [new name]
This command will change the name of the List from old name to new name.
Note: This command will fail if there is more than one List matching the
provided old name.
Note: This command is unable to rename a 'Smart List' (the RTM API considers a 'Smart List' to be read-only).
Example:
> renameList Food Groceries
This command will regenerate the cached lookup table used to reference a specific task to an index number. This is helpful when many tasks have been deleted and the task indices are getting large.
This command will display all tag names associated with the User's tasks. Next to each tag will be the number of incomplete and complete Tasks for that tag.
uncomp [indices...]
This command will mark the Task as incomplete. Tasks are referenced by index number, which are displayed when listing tasks. Multiple task indices can be provided as arguments to this command.
Examples:
> uncomp 1
> uncomp 15 8
Custom meta-commands can be added to your configuration file's aliases property.
This property is a list of aliased commands that reference an existing command
and can provide pre-defined arguments. This can be used to create a meta-command
that uses one of the existing display commands (such as ls) and a pre-set
filter string (using RTM's Advanced Search Syntax).
The included today command is a meta-command added to the default configuration.
To create your own meta command, add the alias property to your configuration file
(located at $HOME/.rtm.json by default). The example below creates the overdue
command listing overdue tasks with the existing lsp command.
{
"aliases": [
{
"name": "overdue",
"description": "Display all tasks that are overdue",
"command": "lsp",
"args": "dueBefore:today AND status:incomplete"
}
]
}The name property gives the command name, description is the command description
given in the help output, command is the existing command to map the new one to, and
args provide the arguments (such as the filter string) to the command.
RTM CLI has a number of properties that can be configured using a separate JSON
configuration file. The default user configuration file is located at $HOME/.rtm.json
but can be changed using the --config option.
The default configuration is as follows:
{
"dateformat": "ddd mmm-dd",
"plannerDateformat": "ddd",
"completed": 7,
"hideDue": false,
"plain": false,
"status": true,
"styles": {
"list": "yellow.underline",
"index": "dim",
"priority": {
"0": "reset",
"1": "red",
"2": "blue",
"3": "cyan"
},
"completed": "dim",
"notes": "reset",
"tags": "magenta",
"due": "green"
},
"aliases": [
{
"name": "today",
"description": "Display prioritized tasks and tasks due or completed today",
"command": "lsp",
"args": "(not priority:none and status:incomplete) or completed:today or (due:today and status:incomplete)"
}
]
}The following is a list of all configuration properties, their descriptions, and default values.
| Property | Type | Description | Default | ||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
client |
object |
RTM API Client Information
RTM CLI includes an RTM API client key/secret but you can override these with your own, if you prefer. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||
dateformat |
string |
Date Display Format This property describes how dates will be formatted when displayed in
the task lists generated by the The format is parsed by the |
ddd mmm-dd |
||||||||||||||||||||||||||||||||||||||||||||||||||||
plannerDateformat |
string |
Planner Date Display Format This property describes how dates will be formatted when displayed in the headers of the planner table. The format is parsed by the |
ddd |
||||||||||||||||||||||||||||||||||||||||||||||||||||
completed |
boolean or integer |
Display Completed Tasks The display of completed tasks can be changed to include all, none or some of the completed tasks with the following values:
This can be overridden using the |
7 |
||||||||||||||||||||||||||||||||||||||||||||||||||||
hideDue |
boolean or integer |
Hide Tasks Due in Future This property can be configured to hide tasks that have a due
date set more than
This can be overridden using the |
false |
||||||||||||||||||||||||||||||||||||||||||||||||||||
plain |
boolean |
Display Plain Text When set to This can be overridden using the |
false |
||||||||||||||||||||||||||||||||||||||||||||||||||||
status |
boolean |
Display Status Text When set to This can be overridden using the |
true |
||||||||||||||||||||||||||||||||||||||||||||||||||||
styles |
object |
Task Attribute Styles Different attributes of tasks can have different styles applied to them when displayed. Styles are applied using the
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||
aliases |
object[] |
Command Aliases This configuration property allows you to define your own meta-commands
that map a new command name to an existing command (such as
| |||||||||||||||||||||||||||||||||||||||||||||||||||||