By trial and error I have found that in org-agenda (org-agenda-todo 'done) marks the entry at point as "DONE".

Can you explain why?

How can I modify the argument to the org-agenda-todo function (or which other function should I use) to mark the entry some other state, e.g. "WAITING"?

1 Answer 1


org-agenda-todo calls the org-todo function interactively and in doing so, the it passes its own argument as it is to org-todo1.

From C-h f org-todo, you will get a complete understanding of what the values of ARG mean to org-todo (and org-agenda-todo):

org-todo is an interactive compiled Lisp function in `org.el'.

(org-todo &optional ARG)

Change the TODO state of an item.
The state of an item is given by a keyword at the start of the heading,
     *** TODO Write paper
     *** DONE Call mom

The different keywords are specified in the variable ‘org-todo-keywords’.
By default the available states are "TODO" and "DONE".
So for this example: when the item starts with TODO, it is changed to DONE.
When it starts with DONE, the DONE is removed.  And when neither TODO nor
DONE are present, add TODO at the beginning of the heading.

With C-u prefix arg, use completion to determine the new state.
With numeric prefix arg, switch to that state.
With a double C-u prefix, switch to the next set of TODO keywords (nextset).
With a triple C-u prefix, circumvent any state blocking.
With a numeric prefix arg of 0, inhibit note taking for the change.
With a numeric prefix arg of -1, cancel repeater to allow marking as DONE.

When called through ELisp, arg is also interpreted in the following way:
‘none’             -> empty state
""(empty string)  -> switch to empty state
‘done’             -> switch to DONE
‘nextset’          -> switch to the next set of keywords
‘previousset’      -> switch to the previous set of keywords
"WAITING"         -> switch to the specified keyword, but only if it
                     really is a member of ‘org-todo-keywords’.

1 I learned the above by looking at the source code of org-agenda-todo.

So it might be useful to email [email protected] with a request to add more information to the doc-string of org-agenda-todo.. Something along the lines of "Refer to the documentation of org-todo to learn how ARG is used.".

  • Got it! To set the todo state to WAITING one needs to use '"WAITING" notation in (org-agenda-todo '"WAITING") and I was trying 'WAITING. Mar 21, 2016 at 22:10
  • BTW, do you know what nextset and previousset mean? Do they mean the first keyword in a set? Mar 21, 2016 at 22:14
  • You do not use a quote before a string. The right way would be (org-agenda-todo "WAITING"). Also for that to work, "WAITING" has to be a part of org-todo-keywords alist. The next/previous set, I believe, is not very widely used (I may be wrong though). But for that to work, org-todo-keywords needs to contain multiple sequences; example: (setq org-todo-keywords '((sequence "TODO" "DONE") (sequence "TODO2" "DONE2"))). Then (org-todo 'nextset) will toggle the todo keyword between "TODO" and "TODO2". Mar 22, 2016 at 2:47

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.