Details

Here's a summary of the commands in Busy.

Output commands:

describe tells the most about an item or set of items
simple includes less detail than describe
base includes even less detail
resource shows the URL (if any) associated with an item
list is like describe but with sequence numbers
queues to lists all the queues
tags to lists tags from a queue

Commands that make changes:

add adds a new item
done marks an item as 'done' and gives the option of iterating - "done for today"
defer puts a task or set of items on the plan for a future date
pop moves a task or set of items to the top of a queue - "pop it to the top"
drop moves a task or set of items to the bottom of a queue - "drop it to the bottom"
pick moves one random item from the filtered set to the top of the queue - "pick one for me"
delete permanently removes a task or set of items from a queue
edit opens a text editor to edit items - the default is to edit only the top item
manage is the same as edit, but defaults to edit the whole collection
activate finds everything planned for today and adds it to the list - "activate my day"

Here are some of the options which apply to some or all of the commands:

filters to designate items to be acted upon, using sequence numbers or tags
the add command requires a description of the new item instead of filters
--queue if not the default tasks queue
--help to find out which options apply
--yes to skip confirmation of any command that requires it
--state to work on Items of a different state (todo, plan, done)
--when applies to the defer command
--defer applies to the done command

Sequence numbers

Sequence numbers appear in the output from the list command. Note that the numbering starts with 1, and is not an ID -- the number of a item will change when the collection is modified. So always reference the most recent output from the list command.

Sequence numbers are used with filters. To designate more than one item, separate the sequence numbers with a space.

Another choice is ranges. A range of sequence numbers is separated by a hyphen, with no whitespace, and is inclusive. For example, 4-6 designates items 4, 5, and 6. A hyphen without a number after it includes all the items from that item to the end of the queue. A hyphen on its own indicates the last item in the queue.

Below are some examples of task designations by sequence number.

busy pop 5 pops item number 5
busy drop 3-7 drops items 3 through 7 (4 items)
busy list 3- lists all the items from number 3 through the end of the list
busy delete 3 5 7 9 deletes only the items designated
busy defer - defers the last task
busy edit -4 is an error! Use busy edit 1-4 instead
busy manage allows you to edit the entire queue

Items will always be handled in the order they appear in the queue, regardless of the order the filter are provided. So for example, if a pop command designates some items, they will be moved to the top of the queue in the order, relative to each other, they currently appear in the queue.

The sequence numbers in the list command output are from the collection itself. So the list command does not modify the sequence numbers, even when item designation is applied.

Named Filters

Specific filters can be named for the plan and done queues to specify date ranges. Use a colon.

planmin:2024-09-28
planmax:2024-09-28
donemin:2024-09-28
donemax:2024-09-28

Default item designations

For the most part, commands that accept item designations default to only act on the top item in the queue. The exceptions are:

list and manage default to handle the entire collection
pop defaults to pop the last item in the collection to the top
activate defaults to activate plan items for today (more on that below)
add adds to the bottom of the todo queue

Alternate queues

Busy will manage any number of queues, which are entirely separate sets of items. For example, you might have a shopping queue for items to buy at the store, and a movies queue for films you'd like to watch. The default queue is called tasks.

To designate an alternate queue, use the --queue or -q option. For example:

busy add --queue shopping -d "Skimmed Milk"
busy list -q movies

Managing plans

Busy supports several specific commands related to planning -- that is, scheduling tasks for the future. They are done, defer, and activate. The task-specific commands handle items in the plan state and, in some cases, the done state.

The task commands accept filters. The done and defer commands reference the todo collection; the activate command references the plan collection. The default for done and defer is the top item in the collection; the default for activate is to activate only plans deferred to today or earlier.

Planning by date

Planning is by date, not time, and is relative to the current date according to the system clock.

In the done command, the date can be specified using the --defer option (or by inputting a value after issuing the command). If the option is omitted, then the date can be provided as input during confirmation.

The date may take any of the following forms:

A specific date in YYYY-MM-DD format, such as 2018-10-28. Slashes are also acceptable, but the order is always year, then month, then day.
A specific date without the year in MM-DD format, such as 7-4, which will defer the item to that date in the future (even if it's in the next year).
A specific day of the month as a simple integer, such as 12, which will defer the item to that day of the month, in either the current month or the next month.
An integer, a space, and the word day or days, such as 4 days, which will defer the item to that number of days from today.
An integer without a space and the letter d, such as 4d, which is a short form of 4 days.
The word tomorrow, which is also the default if no date is provided.
The word today, which is useful for activating tasks later in the day.

As an example, the following command will defer tasks 4, 5, and 6 from the todo collection to the date 4 days from today, keeping them in the plan collection until that date.

busy defer 4-6 -t "4 days"

Note that the plan collection keep the task information from the todo collection along with the date information (as an absolute date).

To pull tasks from the plan collection and put them back into the todo collection, use the activate command. There are two ways to use the activate command:

With no filter, in which case Busy activates all the tasks scheduled for today or earlier, bringing the todo list up to date
With designated items from the plan collection; note that the activate command accepts item designation from the plan queue itself so use busy list -s plan first to get the right list.

Finishing and iterating

The done command removes the designated Task (or the top task if none is designated) from the todo state and adds it to the done state, with today's date to indicate when it was completed.

Optionally, a task can have a repeat value by adding a right angle bracket and the word "repeat" with a time value.

check email > repeat in 1 day
phone mom > repeat on sunday
balance the checkbook > repeat on 6

The exact syntax for a Repeat is the word "repeat" followed by either "on" or "in" and a relative date phrase -- the same phrases that work with the defer command.

The done command uses the repeat value as the default for its iteration.

Editing items

The edit and manage commands launch the user's default text editor to directly edit a task, the whole queue, or part of a queue. Note that edit and manage are identical commands except for their default filter.

A text editor can be designated in a configuration file (.busy.yml) otherwise Busy uses Emacs.

The edit command with no filter will edit the top item in the list, and the manage command with no filter will edit the entire list. But it's also possible to designate items to be edited with both commands using a filter. The commands do their best to replace the edited items in place in the list order. So if you edit or manage a tag whose items are recently popped (at the top of the collection), then the edited items will still appear at the top. Even if you add items, they will be inserted after the last item in the edited set, not at the end of the queue. But all the items brought up in the editor will be edited. So if you remove an item in the editor, it will be deleted and the others will be moved up to take its place.

The editing process includes the full descriptions in BusyML.

Data storage

Busy keeps the collections in plain text files, so if the tool doesn't do something you want, you may edit the files. The files are in a directory together, referred to as the "root". Each file is the named according to the following convention:

<queue>.<state>.psv

If a required file is missing, it will be created automatically. So typically, the root includes tasks.todo.psv, tasks.plan.psv, tasks.done.txt, and any number of custom queue files.

Technically, Busy data files are pipe-delimited data files, though the todo collections only have one field ("description") while the plan and done files have only two fields (date and description).

Busy is not a database (yet). There is no support for managing separate fields in the Busy tool itself.

The default location for the files is a directory at ~/.busy, which will be generated as needed. Specify an alternative location using the --config option referencing a YAML file with the following format:

busy:
  storage:
    directory: /some/other/directory

Note that Busy does not support concurrency or locking in any form. If two commands are executing at the same time, they might overwrite each other. Overwriting is especially risky with the edit and manage commands, which keeps the user's editor open until they close it.

The format is designed to be simple but not idiot-proof. Experimentation might result in unintended consequences.

Even more details

BusyML item description markup