Here is a sample custom agenda command as one might set it in an .emacs file:

( setq org-agenda-custom-commands '(( "c" "Desk Work" tags-todo "computer" ;; (1) (2) (3) (4) ((org-agenda-files '( "~/org/widgets.org" "~/org/clients.org" )) ;; (5) (org-agenda-sorting-strategy '(priority-up effort-down))) ;; (5) cont. ( "~/computer.html" )) ;; (6) ;; ...other commands here ))

The first line in this custom command contains:

the key to trigger the search ("c") a description of the search for the agenda dispatcher ("Desk Work") the type of search (todo items matching a tag) the tag to search for ("computer")

The next two lines (5) set local options for this agenda command only. Any options you set here will not interfere with your global agenda settings. In this particular command, the files widgets.org and clients.org will be searched and the agenda display will sort the todos first by priority (highest priority last), then by estimated effort (highest effort first)—regardless or your global org-agenda-sorting-strategy.

The last line (6) specifies that this agenda view should be exported as HTML to "~/computer.html" when the agenda export function is called (C-c a e).

And here is what the setting above looks like in an emacs customization buffer:

Of course, you need not include all of these components in every custom command. A more minimalistic set of instructions might look like this:

( setq org-agenda-custom-commands '(( "w" todo "STARTED" ) ;; (1) (3) (4) ;; ...other commands here ))

This will produce a list of all tasks with the todo keyword STARTED.[1]

[1] If you omit a description the agenda dispatcher will simply show the search type and search string in place of a description.

In addition to agenda views, custom agenda commands can also be used to store commonly used searches, such as sparse trees and occur trees. See the manual's section on sparse trees for further information.

As the examples above illustrate, agenda commands can range from simple stored searches to elaborate agenda views that diverge substantially from your normal agenda settings (different agenda files, different sorting strategies, different display options, etc.).

Now, let's look at a few usage scenarios.