Teleport: The Unix/Linux ‘cd’ command, improved

Summary: By keeping a history of the directories you've visited, the Teleport command is an improvement on the Unix/Linux cd command. By having a memory, Teleport lets you jump from one directory to any previously visited directory, easily.

January, 2015 Update: The Teleport command now supports Bash completion. For more details on this, see the Github file.

A few quick notes:

  • If you're just looking for the Download link, it's at the bottom of this article.
  • If you'd like to see the Teleport command in action, I created this Teleport command video on YouTube:
Back to top

The Teleport command

I've named the command "teleport", and it's intended to be a replacement for the Unix/Linux cd command. Really, it's a wrapper around the cd command, first doing all of its own work related to keeping a history, and then issuing the appropriate Linux cd command.

The teleport command (tp, for short) does everything the Linux cd command does, with these improvements:

  • It keeps a history, remembering the directories you've visited before.
  • It can display your history.
  • You can easily jump to any directory in your history.
  • And you can create aliases for your directories to make it even easier to jump to them.
Back to top

Teleport command help

Once installed, you can get help on the teleport command by issuing the -h flag, like this:

tp -h

This displays a usage statement similar to the following:

Usage:      tp [DIR]

Purpose:    Provide the same capabilities as the 'cd' command, but with a memory
            of directories that you have previously visited.

  -h        Show HELP (this output)
            JUMP to a directory found in your history (by partial directory name)
  -l        LIST the history of visited directories
  -n [NUM]
            Go to a directory by NUMBER. NUM corresponds to the number printed
            by the -l option. If NUM is not specified then a list of visited
            directories is shown and user can pick a number.
  -s DIR    SEARCH for and display a directory named DIR found in your history

Given that starter information, let's see what the teleport command can do.

Back to top

For basic use, tp is just like cd

For basic cases, you'll use the tp command just like the cd command. For instance, to move to your home directory, just type tp by itself, just like you would with the cd command:


Or, if you prefer more typing, you can add the ~ character:

tp ~

Either one of those commands will take you to your home directory, just like cd.

To move back to your last directory, just add a -, again, just like cd:

tp -

To move to a local subdirectory named Pictures, again just replace the cd command with tp:

tp Pictures

To move to an absolute directory, like /tmp, again tp works just like cd:

tp /tmp

And to move up two directory levels, again, tp is the same:

tp ../..

Nothing too exciting yet ... so far it it works just like the Unix/Linux cd command. Now let's have some fun.

Back to top

Basic teleporting

Where the tp command really shines is with its memory. For instance, let's say your current working directory is something like this:


Next, let's assume you want to move to another directory somewhere else in the filesystem, like this one:


With the cd command, you'd normally have to type something like this:

cd /home/al/Pictures/2008/AlaskaTrip/Talkeetna

But with the tp command, if you've already been to the Talkeetna subdirectory, all you have to type is this:

tp Talkeetna

The teleport command instantly takes you to that directory. In this case, that saves you over 30 characters of typing.

Here's an image showing a few more examples of how easily the Teleport command lets you jump around:

Teleport command examples

This is one example of what remembering your working directory history can do for you, and is the primary reason for the name "teleport".

Back to top

Listing your teleport history

The next nice thing teleport does is provide a listing of your teleport history. When you issue the teleport "list" command, like this:

tp -l

teleport will show you all the directories you've visited recently, like this:

43  /Users/al/Projects/DD/Sketch
44  /Users/al/Desktop
45  /Users/al/Projects/DD/Imagen/release
46  /Users/al/Projects/DD/Hyde/build
47  /Applications/MAMP/htdocs/minime/sites/all/modules/minime
48  /Applications/MAMP/logs
49  /Users/al/Projects/DD/Imagen/build
50  /Users/al/Working/Cato-CRUD-Generator
51  /Applications/MAMP/htdocs/cato
52  /Users/al/Projects/DD/Imagen
53  /Applications/MAMP/htdocs/cato/templates
54  /Applications/MAMP/htdocs/sleetmute

I like this feature because (a) I work on a lot of different projects every week, and (b) I have a bad memory. With the teleport command, it's much easier to remember where all my project files are located.

Also, once you've seen this history, you can teleport to any of those directories very easily. For instance, no matter where I am currently in the filesystem, if I want to go to this directory:


all I have to type is this command:

tp minime

and I'm instantly teleported to that directory. I think you'll agree that's a really nice time-saver.

Back to top

Teleport by number

The teleport command also includes an option to let you teleport to a directory by the number that is shown when you list the teleport history. For instance, using the listing shown above, I can teleport to the same 'minime' directory by typing this -n command:

tp -n 47

This is a nice feature for many purposes, especially when you have multiple directories that end with the same name.

New in Version 0.5: Thanks to a nice contribution by John Santos (somewhere in Portugal), the '-n' command has been significantly improved. Now, instead of typing '-l' and then using those results to feed the '-n' command, if you now type the -n command without a number, like this:

tp -n

the Teleport command will automatically give you the -l history list, and prompt you for a selection, like this:

50  /Users/al/Working/Cato-CRUD-Generator
51  /Applications/MAMP/htdocs/cato
52  /Users/al/Projects/DD/Imagen
53  /Applications/MAMP/htdocs/cato/templates
54  /Applications/MAMP/htdocs/sleetmute

Pick a number or press [Enter] to cancel: _ 

If you've used the Teleport command before, you know this is a sweet addition. I suspect most people will now just use the -n option, and -l will mostly hang around for legacy purposes.

Back to top

Bash completion with Teleport

Thanks to a nice addition by SneakyBobito, Teleport now supports Bash completion. This is described in detail in the Github file, but in short, if you have a directory named TwitterClient in your history and you begin to type this tp command at the Unix command prompt:

$ tp Twit

and then hit the [Tab] key, the new completion code will scan your Teleport history file, and if it finds any matches, it will automatically complete the directory name on the command line. For instance, I have a directory named TwitterClient in my .tp_history file, so when I type this:

$ tp Twit[Tab]

my command is expanded to this:

$ tp TwitterClient

This is a terrific new addition to the Teleport command.

In addition to all of these features, you can also use teleport aliases.

Back to top

Teleport aliases

Teleport aliases provide a simple way for you to create aliases to directories. If you want to resolve conflicts between multiple directories with the same name (as I just showed in the previous section), or you simply want to make sure teleport always knows about a certain directory, you can create an alias for that directory.

Currently the teleport alias works as a separate command named tpa. (I've thought about merging the tp and tpa commands into one command, but have not done so yet. After using the commands for a while, I'll be glad to hear your opinion on whether they should be merged together, or not.)

Here's the usage statement for the teleport alias (tpa) command:

Usage:           tpa ALIAS
Purpose:         Transport to a directory that has an alias ALIAS associated with it.

  -a ALIAS DIR   Add ALIAS as an alias/shortcut for the directory DIR
  -h             Show HELP (this output)
  -l             LIST the known directory aliases
  -r ALIAS       Remove ALIAS from your list of known aliases
Back to top

Adding/creating a teleport alias

To add a new teleport alias, use the -a option, and specify the alias first, followed by the actual directory name, like this:

tpa -a baz /tmp/bar/baz

After issuing that command you'll see output similar to this:

Alias "baz" was added for the directory "/tmp/bar/baz".
Back to top

Using a teleport alias

Once you've created an alias like that, no matter where you are on the filesystem, you can move to that directory using your alias with the tpa command, like this:

tpa baz
Back to top

Listing your teleport aliases

To list your teleport aliases, just use the -l option of the tpa command, like this:

tpa -l

This will list all of the aliases you've defined, like this:


(I need to improve this format, but that's the way it looks currently.)

Back to top

Removing an alias

To remove a tpa alias, just use the -r option and the name of the alias, like this:

tpa -r pub

The tpa command responds like this:

About to remove alias "pub" -- are you sure (y/[n])?: _
Remove operation cancelled.

At this point 'n' will cancel the remove operation, and 'y' will proceed with the remove.

Back to top

Teleport command - summary

I hope you like the teleport command. I think it makes some nice improvements to the standard Linux cd command.

The hardest part for me when I first started using it was remembering to type tp instead of cd. Once I made it through that mental hurdle, I now hate to work on systems where I haven't installed the teleport command yet.

Back to top

Teleport command - download

You can download the teleport command as a tar'd and gzip'd file from the following link:

This file will extract to a directory named teleport, and that directory will contain the following files:


Once you've extracted the contents of this file, you can proceed with the installation. See the INSTALL file for more information.

Back to top


Many thanks to everyone who has sent me emails about the Teleport command already. To answer your questions, yes, I will put this on a site like SourceForge or Google Code, and yes, I will try to add the other features soon.

Yes, I was aware of them, and I probably should have mentioned them (and the dirs command) here. I'll try to write up a little tutorial about them this week.

FWIW, I went with this approach b/c I like this being automated. I don't have to think about pushing and popping, it just happens.

Thanks for your comment. In my experience, not many people know about pushd and popd.

Sorry for the very long delay here, I've been busy, moved 4,500 miles, etc., but I've finally updated the teleport command to Version 0.3, with the primary visible change being that I now properly handle directories with spaces in them.

I've updated the Download link here. Any problems, just let me know.

Sorry again for the long delay here, but the tpa command should now be working with directory names that contain spaces. The latest version is 0.4, and it is now available here for download (see the download link). 


Thanks Alvin! I just updated teleport and all my directories with spaces work perfectly. This is a wonderful program!


I was planning to write exactly similar command. Searched hard on internet and found this.
Great work. one suggestion, may be a option of unique history of directory visited will be good too



Thanks so much for this command! Before tp I was making aliases for frequently visited dirs and using pushd/popd in a somewhat clumbsy way to facilitate navigating between them. tp just obliterated all that mess AND made things much more convenient in the process!

It would be totally awesome if tab completion would work properly...Is that possible somehow you think?

Thanks for the kind words. After reading these Git tips on the Pro Git website, it looks like command line completion (tab completion) is possible. That being said, I'm afraid I have too many things on my plate right now to tackle this myself (mostly trying to eek enough profit out of these websites so I don't have to go back to the consulting world).

If anyone else would like to tackle it, I agree, it would be a very nice feature. If not, I'll put it on the "tp feature requests" list.


When I first read about Linux in PCMagazine (or something like that in 1992) I was amazed by the ability to create our own commands. Thanks Alvin! Today I can die in peace, because my dream was fulfilled tp_command.


The tp function seems to be working fine in the default bash shell of Mac OS X, too. Very nice, since the BSD command set of this environment doesn't even include pushcd and popcd. Only install adjustment was to add the function "load" line by editing ~/.profile instead of ~/.bash_profile

Thanks! This is nice and will be used a lot!


Greetings from Portugal!
This command is fantastic. Just what I was looking for. However I find that sometimes I need to list the commands and then jump to a number. This involves using tp twice. Example:

tp -l
tp -n XX

I have improved the command. Tp still works exactly like before, with this added feature: if the user types 'tp -n' without specifying a number then tp will automatically do a 'tp -l' (to show the list) and then prompt for a number. Example:

/Users/John>tp -n

1 /mnt/sdb1/website
2 /mnt/sdb1/backups
3 /etc/ssh

Pick a number or press to cancel: 3


If you decide that you do not want to specify a number you can just press ENTER to cancel, and stay in the directory you were in.

I wish to contact Alvin so I can send him the altered code for him to review, and hopefully add it in. So if anyone knows how to contact him I would appreciate it.

Thanks for letting me know this. I just saw this problem using Chrome, but it seems to work fine with Firefox, Safari, and the curl command, all of which I just tested with on my Mac system.

It looks like Chrome is turning the "tgz" file into a "tar" file, possibly because of an Apache server configuration I have wrong. If you run a "tar tvf" command on the file you download (intentionally skipping the 'z' parameter you would normally use), you'll see that it is a tar file instead of a tgz file. If you'll then (a) change the extension on the file to .tar, (b) gzip the file, then (c) use md5 again, you'll see the correct checksum value.

Or, you can just download the current teleport version using curl like this:

curl -o tp.tgz

Assuming I have an Apache config error somewhere, I'd like to fix it, but I'm currently traveling, and don't have the time to do it right now. Sorry for the inconvenience.


cool tool!

... how can i change default behavior of "$ tp" not changing to home directory but instead behave like "$ tp -n"?

and is it possible to implement "$tp -5" instead of "$tp -n 5"?

thanks anyway for the tool.

Hi Sebastian,

Thanks for the comments. Personally, I'm trying to keep the tp command as consistent with the cd command as I can, so I'm going to keep '$ tp' behaving just like '$ cd', which is to take me to my home directory.

Obviously, feel free to modify your own copy of the tp command. Though I'm not looking at the code at the moment, the first change you suggest should be pretty easy. Just look for the code that handles the move to the home directory, and modify it. The second one is probably a little more work, you'll have to test for command line options that don't exist, but it should also be do-able.

I'm sorry I'm not much help right now. I'm currently trying to finish writing the Scala Cookbook for O'Reilly, and it has all of my attention at the moment.

Best wishes,


Added this to my cygwin .bashrc

[[ -f ${HOME}/tp_command ]] && source ${HOME}/tp_command && alias cd='tp'

Also an alternative to tp would be wcd command. But I prefer tp here :)

Add new comment

Anonymous format

  • Allowed HTML tags: <em> <strong> <cite> <code> <ul type> <ol start type> <li> <pre>
  • Lines and paragraphs break automatically.