tahoe-lafs/docs/CLI.txt

= The Tahoe CLI commands =

Tahoe provides a single executable named "tahoe", which can be used to create
and manage client/server nodes, manipulate the virtual drive, and perform
several debugging/maintenance tasks.

This executable lives in the source tree at "bin/tahoe". Once you've done a
build (by running "make"), bin/tahoe can be run in-place: if it discovers
that it is being run from within a Tahoe source tree, it will modify sys.path
as necessary to use all the source code and dependent libraries contained in
that tree.

If you've installed Tahoe (using "make install", or by installing a binary
package), then the tahoe executable will be available somewhere else, perhaps
in /usr/bin/tahoe . In this case, it will use your platform's normal
PYTHONPATH search paths to find the tahoe code and other libraries.

== CLI Command Overview ==

The "tahoe" tool provides access to three categories of commands.

 * node management: create a client/server node, start/stop/restart it
 * vdrive manipulation: list files, upload, download, delete, rename
 * debugging: unpack cap-strings, examine share files

To get a list of all commands, just run "tahoe" with no additional arguments.
"tahoe --help" might also provide something useful.

Running "tahoe --version" will display a list of version strings, starting
with the "allmydata" module (which contains the majority of the Tahoe
functionality) and including versions for a number of dependent libraries,
like Twisted, Foolscap, pycryptopp, and zfec.

== Node Management ==

"tahoe create-client [NODEDIR]" is the basic make-a-new-node command. It
creates a new directory and populates it with files that will allow the
"tahoe start" command to use it later on. This command creates nodes that
have client functionality (upload/download files), web API services
(controlled by the 'webport' file), and storage services (controlled by
"no_storage" and the like).

NODEDIR defaults to ~/.tahoe/ , and newly-created clients default to
publishing a web server on port 8123 (limited to the loopback interface, at
127.0.0.1, to restrict access to other programs on the same host). All of the
other "tahoe" subcommands use corresponding defaults.

"tahoe create-introducer [NODEDIR]" is used to create the Introducer node.
This node provides introduction services and nothing else. When started, this
node will produce an introducer.furl, which should be published to all
clients.

"tahoe create-key-generator [NODEDIR]" is used to create a special
"key-generation" service, which allows a client to offload their RSA key
generation to a separate process. Since RSA key generation takes several
seconds, and must be done each time a directory is created, moving it to a
separate process allows the first process (perhaps a busy webapi server) to
continue servicing other requests. The key generator exports a FURL that can
be copied into a client node to enable this functionality.

"tahoe start [NODEDIR]" will launch a previously-created node. It will launch
the node into the background, using the standard Twisted "twistd"
daemon-launching tool.

"tahoe run [NODEDIR]" will start a previous-created node in the foreground.
Some platforms are unable to run a daemon in the background: this command
provides a way to use a tahoe node on such platforms.

"tahoe stop [NODEDIR]" will shut down a running node.

"tahoe restart [NODEDIR]" will stop and then restart a running node. This is
most often used by developers who have just modified the code and want to
start using their changes.


== Virtual Drive Manipulation ==

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 a table of "aliases" 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 aliases are short
strings that stand in for a directory read- or write- cap. The default
starting point uses an alias named "tahoe:".

For backwards compatibility with Tahoe-1.0, if the "tahoe": alias is not
found in ~/.tahoe/private/aliases, the CLI will use the contents of
~/.tahoe/private/root_dir.cap instead. Tahoe-1.0 had only a single starting
point, and stored it in this root_dir.cap file, so Tahoe-1.1 will use it if
necessary. However, once you've set a "tahoe:" alias with "tahoe set-alias",
that will override anything in the old root_dir.cap file.

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. [TODO]
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 attached
to 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 add-alias tahoe `tahoe mkdir`

After that 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 add-alias alias cap
tahoe list-aliases
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 add-alias work DIRCAP

 This create an alias "work:" and configures it to use the given directory
 cap. Once this is done, "tahoe ls work:" will list the contents of this
 directory. Use "tahoe add-alias tahoe DIRCAP" to set the contents of the
 default "tahoe:" alias.

tahoe list-aliases

 This displays a table of all configured aliases.

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 ==

"tahoe find-shares STORAGEINDEX NODEDIRS.." will look through one or more
storage nodes for the share files that are providing storage for the given
storage index.

"tahoe catalog-shares NODEDIRS.." will look through one or more storage nodes
and locate every single share they contain. It produces a report on stdout
with one line per share, describing what kind of share it is, the storage
index, the size of the file is used for, etc. It may be useful to concatenate
these reports from all storage hosts and use it to look for anomalies.

"tahoe dump-share SHAREFILE" will take the name of a single share file (as
found by "tahoe find-shares") and print a summary of its contents to stdout.
This includes a list of leases, summaries of the hash tree, and information
from the UEB (URI Extension Block). For mutable file shares, it will describe
which version (seqnum and root-hash) is being stored in this share.

"tahoe dump-cap CAP" will take a URI (a file read-cap, or a directory read-
or write- cap) and unpack it into separate pieces. The most useful aspect of
this command is to reveal the storage index for any given URI. This can be
used to locate the share files that are holding the encoded+encrypted data
for this file.