I am attempting to create a custom org-agenda menu (Q) with subitems (Qa and Qb) by using add-to-list in my init.el file:

(add-to-list 'org-agenda-custom-commands
             '(("Q" . "Custom queries")
               ("Qa" "Archive tags search" org-tags-view ""
                ((org-agenda-files (file-expand-wildcards "~/Documents/*.org"))))
               ("Qb" "Archive search" search ""
                ((org-agenda-files (file-expand-wildcards "~/Documents/*.org"))))

However, I am getting the error: Wrong type argument; listp, "Custom queries". I suspect the syntax is wrong. I tried to use the customize-variable function, but it was even harder to decode it.

  • You might find @gusbrs's comments in this question useful.
    – NickD
    Commented Mar 17, 2022 at 12:10
  • 1
    Start with the simplest example possible: the second one on the page, then try the first one which is slightly more complicated. You should also read the doc string of org-agend-custom-commands carefully: it's a complicated variable. And you should start by reading the Custom Agenda Views section in the manual.
    – NickD
    Commented Mar 17, 2022 at 14:36
  • Thanks, @NickD. The response below helped to with the right syntax. I couldn't find anywhere in the manual how to add-to-list org-agenda-custom-commands having a hierarchy of commands. Nowhere. Commented Mar 18, 2022 at 6:23

2 Answers 2


The level is wrong. You should check the value you modified and the doc of org-agenda-custom-commands carefully before ask question.

I suggest use setq, if you really want to use add-to-list, try:

(add-to-list 'org-agenda-custom-commands
             '("Q" . "Custom queries"))
(add-to-list 'org-agenda-custom-commands
             '("Qa" "Archive tags search" org-tags-view ""
               ((org-agenda-files (file-expand-wildcards "~/Documents/*.org")))))
(add-to-list 'org-agenda-custom-commands
             '("Qb" "Archive search" search ""
               ((org-agenda-files (file-expand-wildcards "~/Documents/*.org")))))
  • THANK YOU!!! This really worked and I couldn't find anywhere how to add-to-list org-agenda-custom-commands having a hierarchy of commands. Commented Mar 18, 2022 at 6:23
  • If you want examples, just search on Github like github.com/… or cs.github.com/… Commented Mar 18, 2022 at 9:05

[This is a supplement to @TianshuWang's answer, primarily aiming to answer the OP's complaint that he could not find any examples with add-to-list used to form a hierarchical, multi-level command structure. It's my attempt to explain how to get hold of an unfamiliar data structure. Hope it's helpful.]

org-agenda-custom-commands is a list. Each element of it is a single custom command (another list). A custom command consists of a key (a string), a description (a string), a type (one of a given set of symbols), a matcher (a string which is supposed to be empty for many of the types, although it should be non-empty for some of them, e.g. tag searches where it specifies the tag to search for), a list of local settings, and a list of files (for exporting the agenda).

You can get this information from the doc string of the variable. Looking at examples helps but only if you take the trouble to map the example back to the documentation: that way you will understand the data structure and be able to understand an unfamiliar example or construct an example of your own.

Once you have this information ("It's a list"), then you know that you can construct the org-agenda-custom-commands list like any other list: you can set it to a given list of elements (the elements are custom commands in this case):

(setq org-agenda-custom-commands '(elt elt ... ))

OR you can add an element to a preexisting list:

(add-to-list 'org-agenda-custom-commands elt)

Just like any other list.

The only thing that's special to org-agenda-custom-commands is that its elements are custom commands, i.e. lists of a specific form as described above.

Now the doc string also describes a special case where you can group a bunch of commands under a prefix key. And that adds another wrinkle to what can be considered an element of the list. But once you understand that this is acceptable, then you know how to add it to the list: the same way as before.

You say that you could not find an example with add-to-list: so what? The number of programs that can be written is infinite, so it is hardly surprising that you cannot find an explicit example of each. The point is that you need to get an understanding of the language and the data structures it supports beyond just being able to copy an existing example.

And you also need to read the docs carefully: there is an example of a hierarchical org-agenda-custom-commands in the variable's doc string: all you have to do is C-h v org-agenda-custom-commands. It says:

When using several characters as key to a command, the first characters are prefix commands.  For the dispatcher to display useful information, you should provide a description for the prefix, like

 (setq org-agenda-custom-commands
   '(("h" . "HOME + Name tag searches") ; describe prefix "h"
     ("hl" tags "+HOME+Lisa")
     ("hp" tags "+HOME+Peter")
     ("hk" tags "+HOME+Kim")))

It shows you an example of the list constructed by listing its four elements. But you know it's a list, so you know you can also construct it by adding one element at a time with add-to-list (as in @TianshuWang's answer).

The problem of course is that at first, all you see is a meaningless jumble of symbols and parentheses and you don't know how to get hold of this thing: but you know it's a list so you just have to step back and forget about the details and look at it as a list of elements; once you can identify the individual elements (which may themselves be pretty complicated) then you can look at each element in turn, until you have comprehended the structure all the way down.

So don't get lost in the details and don't waste your time looking for examples all over the internet: look at the structure and think about it. After you've done that in a dozen simple and not-so-simple cases, you'll get the knack of it. Inevitably, there will be times when things seem too complicated. Then you ask a question, but when you get an answer, you should go back and ask yourself: in the light of the answer, how could I have figured it out myself? Then next time, you'll have a better chance of doing exactly that.

  • Thanks, that was very informative. Commented Mar 19, 2022 at 15:45

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.