Tool of the Month: cdargs

This month, I’ll discuss cdargs, a tool that simplifies using the command line. cdargs is a handy little utility that provides browsing and bookmarks for cd.

Installing and using cdargs

I just recently dicovered cdargs, but it’s already proved to be a great application and big time-saver. It’s also easy to set up — just grab the source tarball and unpack it. Run configure
; make
then su to root and run make install-strip. I’m using cdargs on SUSE 9.0, but it should compile just fine on most recent Linux distros. (I’m not sure about the portability for *BSDs or other Unixes.)

You can use cdargs alone, but there’s also a nifty script for Bash users that makes cdargs even more useful. Recent releases of cdargs come with a script called, which provides several shell functions that you’ll want to use. Add this to your .bashrc with the following line:

source $HOME/src/cdargs/contrib/

Naturally, the path to will depend on your local setup. If you want to utilize the cdargs functions as root, you’ll need to do the same with the .bashrc for your root user account. Also, don’t forget that you’ll need to source the script in any current sessions or it will not take effect.

Note that there is also a similar file for tcsh and related shells in the same directory called cdargs-tcsh.csh, which will provide some of the same functionality, as well as an Emacs front-end for cdargs called cdargs.el. I haven’t actually tested either of these, since I’m not a heavy user of Emacs or shells other than Bash.

Now that we’ve got cdargs and so forth set up, let’s take a look at the usage. The first command you’ll want to acquaint yourself with is cv. This provides a directory browser that allows you to navigate directories with just a few keystrokes. While the standard tab-completion built into many shells is fast, using cv can be even faster.

When you use cv, you’ll see a list of all the current directory’s subdirectories numbered 0 through 9. If there are more than 10 directories in the current directory (which is fairly common) then the remaining directories will not be numbered. Hitting one of the number keys will take you to the numbered directory. For example, if you see a list something like this:

  [.       ]  /home/jzb
0 [Desktop ]  /home/jzb/Desktop
1 [Mail    ]  /home/jzb/Mail
2 [OpenOffi]  /home/jzb/OpenOffice.org1.1
3 [backups ]  /home/jzb/backups
4 [bin     ]  /home/jzb/bin
5 [doc     ]  /home/jzb/doc
6 [local   ]  /home/jzb/local
7 [public_h]  /home/jzb/public_html
8 [src     ]  /home/jzb/src
9 [tmp     ]  /home/jzb/tmp

Then, hitting 2 will move your cursor to the /home/jzb/OpenOffice.org1.1 entry, but you won’t be moved to that directory until you press Enter. Note that the current directory is not numbered. By default, hidden directories will not be shown. This setting can be toggled using the “.” key.

There are several ways to navigate this list. You can use the arrow keys or the standard vi movement keys. The up and down keys, or the k and j keys, will move you up and down the list of directories. If you want to navigate upwards in the directory tree, use the left or h key. Assuming a given directory has subdirectories, you can navigate further into the directory tree with the right key or l key. Users of vi-like editors will probably get great mileage out of cv.

The similarity to vi-like keybindings isn’t absolute, however. The “/” key will not perform a search, but rather switch to the root directory. If you’ve navigated outside your home directory and want to return to browsing your home directory, just hit the tilde (~) key. To move to the first entry in the list, use the Home key or CTRL-a. To move to the last entry, use End or CTRL-e.

This is cdargs‘ browsing mode. If you have directories that you use often, you can use the bookmark feature to add them to the list. To enter the list mode, hit the Tab key. If you don’t have any directories bookmarked, then it will just be a blank screen with a bar at the bottom with “L:” and the present working directory, otherwise both modes look the same except for the “B:” or “L:” in the lower left-hand corner. Unlike the browsing mode, hitting a number key will automatically move you into a directory in the list mode without needing to press Enter.

While browsing, hit the “a” key to add a directory to your list. If you want to give a description, hit “A” instead and you will be prompted to provide a description that will show up in the list mode. If you want to add the current directory to your list, simply hit the “c” key, or “C” if you want to add a description. (Do give your bookmarks short and memorable descriptions. More on that later.)

The “m” key will move an entry down the list, while “M” will move an entry up the list. To edit the list directly, simply hit “v” or “e” and you’ll be able to use your default editor to modify your bookmarked directories. If you’d like a quick “cheat” page with the navigation keys, hit “H” or “?” while in either list mode or browse mode. Finally, the “q” key will allow you to exit. It takes a little while to get used to using cv, but once you do, it is a major time-saver.

Even faster

Using the cv function for browsing or accessing your bookmarks is fast, but there’s an even faster way to go. Let’s say you’ve created a bookmark for a directory (/home/user/public_html, for example) and the description for that bookmark is “web”. You can navigate to /home/user/public_html by using cdb web.

The cdb function allows you to navigate directly to a bookmarked directory without having to fiddle about in the cdargs menu. I make a point of adding bookmarks for any directories that I access on a regular (several times a day) basis. I also try to give them very short and memorable descriptions, so that I can quickly switch between directories without needing to use the menu interface.

If you want to add the present directory to your list of bookmarks without entering the menu, you can use the ca function to add a bookmark to your list. Simply run ca description, which will add a bookmark for the present working directory to your list by the name of “description” (not that I’d recommend such a lengthy name for an actual bookmark). Note that ca will happily add another entry to your list with the same name. If this happens, and you run cdb description, then you’ll be placed in the directory browser and allowed to choose which directory you actually want to switch into. Several entries can co-exist with the same name with no major ill effects.

Beyond navigation

The cdargs functions go beyond simple browsing and navigation of the directory structure. The functions also include mvb and cpb. The mvb function allows you to move files to the bookmarked directory, while the cpb function allows you to copy files to the bookmarked directory.

Let’s say you’ve given the /tmp directory a description of “tmp,” and you want to move a file to your /tmp directory. Run mvb filename tmp and the file will be moved there. If you slip and type mvb filename tpm, you’ll be directed to the browser to locate the proper directory — you won’t receive an error unless you exit the browser without selecting a destination directory.

The cpb function operates in pretty much the same way. Simply run cpb filename
and the files will be copied to /tmp. Again, this takes a little getting used to, but it’s a major time-saver once you work it into your routine. You can easily download and install cdargs and have it set up in less than an hour. After a few days’ use, you’ll wonder how you ever lived without it.

Share and enjoy!

If you have a favorite tool that runs on Linux, *BSD, and other *nix OSes, drop me a note and let me know about it. I’m always interested in new and interesting free and open source tools that make life easier for *nix users.

(Originally written for and published on, rescued from the dustbin by and copypasta. Reposted because it still seems relevant today.)

Leave a Reply