[tahoe-dev] CLI syntax

[Brian Warner]

Zooko and I just finished up a big discussion about CLI syntax. I'm trying to
overhaul the command-line tools and make them actually useable.

We eventually converged on using scp-like syntax, in which arguments that
refer to files and directories take the form of [alias:]path/name . Each
argument might refer to something in the tahoe virtual filesystem, or to
something on the local disk.

Each user has an "alias table", which maps an alias name to a directory cap.
The existing ~/.tahoe/private/root_dir.cap is treated as the user's "home
directory", and uses a simple alias name, which we haven't decided upon yet..
"tahoe:" is the working title, but ":" (the empty string) is zooko's current
favorite, and "root:", "home:", or "vdrive:" might also make sense.

The command set that we're looking at is something like:

 tahoe mkdir [NAME]
 tahoe ls [WHAT]
 tahoe cp [-r] FROM.. TO
 tahoe get FROM [LOCALTO|-]
 tahoe put [LOCALFROM|-] TO
 tahoe rm WHAT
 tahoe mv FROM TO
 tahoe ln FROM TO

The get/put commands are mostly for use with stdio.. the 'cp' command can be
used for any other purposes.

The arguments to the 'cp' command refer to local files by default, unless an
alias: prefix is used. The LOCALTO/LOCALFROM arguments to get/put can only
refer to local files. The other arguments default to tahoe:, unless otherwise
specified.

So to back up your home directory into a subdirectory of your tahoe space,
you could run:

 tahoe cp -r ~ tahoe:backups/2008-May-09

To list an old backup:

 tahoe ls backups/2008-Apr-15

To dump a file from that backup:

 tahoe get backups/2008-Apr-15/taxes.txt |grep Refund

If you've created a directory to share with your friend, and added an alias
to it named "to-zooko:", then you could add a file to that shared directory
with:

 tahoe cp work/presentation.pdf to-zooko:


There are more issues to resolve, but this should get me started on fixing
the CLI. The main thing to figure out here is where the alias table should
live. We're planning on the following restrictions for right now:

 aliases can use [a-zA-Z0-9._-] and nothing else

 there is no way to use URIs directly from the command line

 pathnames cannot contain colons

We'll find ways to relax all three restrictions eventually, but these allow
us to agree on the first steps and make some progress.

I'll send out another message to start the thread on how to use URIs from the
command line.

cheers,
 -Brian