From: Brian Warner Date: Sat, 10 May 2008 01:06:29 +0000 (-0700) Subject: CLI.txt: document proposed scp:-based CLI syntax X-Git-Tag: allmydata-tahoe-1.1.0~136 X-Git-Url: https://git.rkrishnan.org/tahoe_css?a=commitdiff_plain;h=0838f76e0fc2a6a031a652cf009d4586c6644ad2;p=tahoe-lafs%2Ftahoe-lafs.git CLI.txt: document proposed scp:-based CLI syntax --- diff --git a/docs/CLI.txt b/docs/CLI.txt index 0b1e731d..778c452e 100644 --- a/docs/CLI.txt +++ b/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 ==