Quick, The Download

Please see

Project Status

CDargs is probably my most "successful" software project, small as it may be. Nevertheless, I consider this piece of software done. It does almost everything that I want (and implementing an incremental search would be too tedious).

The code is really bad, I know that. It was written during that phase when you start learning C++ after coding in C for quite a while... This is just another reason for never touching it again (unless, of course, I receive fixes for bugs not detected yet.)

I'd like to include some ZSH-code for completion into the distribution but I don't use ZSH and thus I won't write it. (see below for patches)

Since July 2010 there exists a friendly fork on github: Maybe someone else will take over the work on this and bring it to the modern age. Please look over there if you find anything that is broken or missing in version 1.35.



Current Version: 1.35

CDargs heavily enhances the navigation of the common unix file-system inside the shell. It plugs into the shell built-in cd-command (via a shell function or an alias) and thus adds bookmarks and a browser to it. It enables you to move to a very distant place in the file-system with just a few keystrokes. This is the kind of thing that power shell users invent when even the almighty and wonderful TAB-completion is too much typing. (Just as a side-note: there exists TAB-completion for cdargs ;-)

This little piece of software was inspired by an article Michael Schilli wrote for the German iX-Magazine]. There he showed a script which let you choose from a list of alternatives were to cd to, e.g. in your xterm. In the forum connected to this article some others enhanced this script.

When I wanted to change it even more and put some more features in it I discovered that it was not under the GPL so I decided to do a complete rewrite of the whole thing. Since I wanted to make sure that I shared no code with the original artwork I chose to use C/C++ together with the ncurses library. This program is the result of those efforts.


were heavily involved in this project. Please read the THANKS file in the distribution for a full list of contributors. It's amazing that such a small program can have so many people helping it.

Motivation and other notes

I have had reports of a segfault caused by cdargs. They could be avoided when the compiler option -Os was not used. If someone could find out where they come from, please drop me a note.
pushd, popd, dirs
Yes, I know about them. I didn't like them. It's only stackbased, not saved at the end of session and it just felt wrong in my hands. Honestly I tried it, long enough to create some aliases.
Speaking of aliases. Yes I could create aliases for jumping to directories. But I couldn't find a userfriendly, quick way of managing them.
Yes, I had a directory with symlinks to my hotspots once. I didn't use that long. Bad to maintain, the directory clobbers, no tab completion without going to that directory. And extra fun with resolved or not resolved symlinks in pathnames.
Stupid idea to begin with. I couldn't take that seriously.
cd -
Just one directory, but I use it all the time.
Yes, there are other possibilities offered by the shell or programms like midnight commander. I know that. No need to point that out. I wanted a graphical browser in the shell, I like the TAB completion, and features like hitting cursor-right on a bookmark or browsing the filesystem with the cursor-left working like it does in cdargs or managing your bookmarks while they are displayed, Those features are missing in all the other suggestions I have come across.

But then, Free Software is all about Choice. If you found another way to be more practical for you, that's fine with me. Be happy and quick with it. I am with cdargs.

Download, Install and Usage

Download the tarball from and unpack it. See the file INSTALL for installation details and how to use cdargs.

Bash and Friends

Since version 1.19 cdargs comes with a collection of shell functions for bash (written by Dan Allen) so you just have to put a line into your ~/.bashrc which sources this file. When you put it somewhere into your $PATH you just have to:


or you can put it wherever you want and give the full pathname to it, e.g.:

  source $HOME/src/cdargs/contrib/

Older version of cdargs need a shell function which calls the cdargs program and then changes the directory to the path found in the resulting file from cdargs (probably ~/.cdargsresult). Some examples for our bash:

     function cv () {
       cdargs "$1" && cd "`cat "$HOME/.cdargsresult"`" ;
     function cv () {
       cdargs "$1" && cd "`cat "$HOME/.cdargsresult"`" && pwd ;
     function cv () {
       cdargs "$1" && cd "`cat "$HOME/.cdargsresult"`" &&
       rm -f "$HOME/.cdargsresult";
     function cap () {
       cdargs --add=":$1:`pwd`" ;
             (thanks to Stephen Gildea and Juhapekka Tolvanen for noting the quoting issues!)

TCShell and Relatives

Since I don't use any other shell than bash I can't provide this easy setup and all the fine functions Dan wrote for tcsh. Sorry. But this is Free Software. I'd be more than happy to receive a translation to tcsh and put it into the distribution!

At least since version 1.20 cdargs ships with a simple tcshell wrapper file: cdargs-tcsh.csh which does not provide all the nifty functions of the bashish version.


Here is a patch I received early 2009 to enable ZSH-completion by just using the bash-completion from ZSH: cdargs-zsh-completion.patch


When you're within cdargs press 'H' (or '?' or 'C-h') for help and see what powers are at your hands... Otherwise take a look at the INSTALL file which contains the important information or read the man-page.

In short

Command or keystrokeFunction
cv in your shellinvokes the cdargs GUI
cv [TAB]gives you TAB-completion for your bookmarks
ca [label]add the current directory to your list of bookmarks optionally using LABEL as the description string.
cpb FILELIST [bookmark]copies a list of files to a directory you choose. Make sure that the optional BOOKMARK is not a directory where you are.
arrow keys in cdargsnavigate the list or the directories.
ENTERselects an entry
H,?,C-hcall for help



Now, let's see where CDargs was mentioned on the web... If you find an important link missing here, please drop me a note.

Close Relatives