CLI.txt: document proposed scp:-based CLI syntax

docs/CLI.txt

@@ -75,7 +75,164 @@ start using their changes.
 
 == Virtual Drive Manipulation ==
 
-TODO
+[NOTE: This is a work-in-progress: none of this actually works yet].
+
+
+These commands let you exmaine a Tahoe virtual drive, providing basic
+list/upload/download/delete/rename/mkdir functionality. They can be used as
+primitives by other scripts. Most of these commands are fairly thin wrappers
+around webapi calls.
+
+By default, all vdrive-manipulation commands look in ~/.tahoe/ to figure out
+which Tahoe node they should use. When the CLI command uses webapi calls, it
+will use ~/.tahoe/node.url for this purpose: a running Tahoe node that
+provides a webapi port will write its URL into this file. If you want to use
+a node on some other host, just create ~/.tahoe/ and copy that node's webapi
+URL into this file, and the CLI commands will contact that node instead of a
+local one.
+
+These commands also use ~/.tahoe/private/root_dir.cap to figure out which
+directory they ought to use a starting point. This is explained in more
+detail below.
+
+=== Root Directories ===
+
+As described in architecture.txt, the Tahoe distributed filesystem consists
+of a collection of directories and files, each of which has a "read-cap" or a
+"write-cap" (also known as a URI). Each directory is simply a table that maps
+a name to a child file or directory, and this table is turned into a string
+and stored in a mutable file. The whole set of directory and file "nodes" are
+connected together into a directed graph.
+
+To treat this collection of dirnodes as a regular filesystem, you just need
+to choose a starting point: some specific directory that you refer to as your
+"root directory". We then refer to everything that can be reached from this
+starting point as your "personal filesystem". The "ls" command would list the
+contents of this root directory, the "ls dir1" command would look inside the
+root for a child named "dir1" and list its contents, "ls dir1/subdir2" would
+look two levels deep, etc. Note that there is no real global "root"
+directory, but instead each user's personal filesystem has a root that they
+use as a starting point for all their operations.
+
+In fact, each tahoe node remembers a list of starting points, named
+"aliases", in a file named ~/.tahoe/private/aliases . These are short strings
+that stand for a directory read- or write- cap. The default starting point
+uses an alias named "tahoe:", and for backwards compatibility can be stored
+in a file named ~/.tahoe/private/root_dir.cap .
+
+The Tahoe CLI commands use the same filename syntax as scp and rsync, an
+optional "alias:" prefix, followed by the pathname or filename. Many commands
+have arguments which supply a default tahoe: alias if you don't provide one
+yourself, but it is always safe to supply the alias. Some commands (like
+"tahoe cp") use the lack of an alias to mean that you want to refer to a
+local file, instead of something from the tahoe virtual filesystem. Another
+way to indicate this is to start the pathname with a dot, slash, or tilde.
+
+When you're dealing with your own personal filesystem, the "tahoe:" alias is
+all you need. But when you want to refer to something that isn't yet in your
+virtual drive, you need to refer to it by its URI. The way to do that is to
+add an alias to it, with the "tahoe add-alias" command. Once you've added an
+alias, you can use that alias as a prefix to the other commands.
+
+The best way to get started with Tahoe is to create a node, start it, then
+use the following command to create a new directory and set it as your
+"tahoe:" alias:
+
+ tahoe set-alias tahoe `tahoe mkdir`
+
+After thatm you can use "tahoe ls tahoe:" and "tahoe cp local.txt tahoe:",
+and both will refer to the directory that you've just created.
+
+=== Command Syntax Summary ===
+
+tahoe mkdir
+tahoe mkdir [alias:]path
+tahoe ls [alias:][path]
+tahoe put [localfrom:-]
+tahoe put [localfrom:-] [alias:]to
+tahoe get [alias:]from [localto:-]
+tahoe cp [-r] [alias:]frompath [alias:]topath
+tahoe rm [alias:]what
+tahoe mv [alias:]from [alias:]to
+tahoe ln [alias:]from [alias:]to
+
+=== Command Examples ===
+
+tahoe mkdir
+
+ This creates a new empty unlinked directory, and prints its write-cap to
+ stdout. The new directory is not attached to anything else.
+
+tahoe mkdir subdir
+tahoe mkdir /subdir
+
+ This both create a new empty directory and attaches it to your root with the
+ name "subdir".
+
+tahoe ls
+tahoe ls /
+tahoe ls tahoe:
+tahoe ls tahoe:/
+
+ All four list the root directory of your personal virtual filesystem.
+
+tahoe ls subdir
+
+ This lists a subdirectory of your filesystem.
+
+tahoe put file.txt
+tahoe put ./file.txt
+tahoe put /tmp/file.txt
+tahoe put ~/file.txt
+
+ These upload the local file into the grid, and prints the new read-cap to
+ stdout. The uploaded file is not attached to any directory.
+
+tahoe put file.txt uploaded.txt
+tahoe put file.txt tahoe:uploaded.txt
+
+ These upload the local file and add it to your root with the name
+ "uploaded.txt"
+
+tahoe cp file.txt tahoe:uploaded.txt
+tahoe cp file.txt tahoe:
+tahoe cp file.txt tahoe:/
+tahoe cp ./file.txt tahoe:
+
+ These upload the local file and add it to your root with the name
+ "uploaded.txt".
+
+tahoe cp tahoe:uploaded.txt downloaded.txt
+tahoe cp tahoe:uploaded.txt ./downloaded.txt
+tahoe cp tahoe:uploaded.txt /tmp/downloaded.txt
+tahoe cp tahoe:uploaded.txt ~/downloaded.txt
+
+ This downloads the named file from your tahoe root, and puts the result on
+ your local filesystem.
+
+tahoe cp tahoe:uploaded.txt work:stuff.txt
+
+ This copies a file from your tahoe root to a different virtual directory,
+ set up earlier with "tahoe add-alias work DIRCAP".
+
+tahoe rm uploaded.txt
+tahoe rm tahoe:uploaded.txt
+
+ This deletes a file from your tahoe root.
+
+tahoe mv uploaded.txt renamed.txt
+tahoe mv tahoe:uploaded.txt tahoe:renamed.txt
+
+ These rename a file within your tahoe root directory.
+
+tahoe mv uploaded.txt work:
+tahoe mv tahoe:uploaded.txt work:
+tahoe mv tahoe:uploaded.txt work:uploaded.txt
+
+ These move a file from your tahoe root directory to the virtual directory
+ set up earlier with "tahoe add-alias work DIRCAP"
+
+
 
 == Debugging ==