|
Command-line Quick Start Guide
Contents
- Why use a command-line tool?
- How to use these tools
- Download tool
- Upload tool
- Example scripts
- Join group for updates
Why use a command-line tool?
There are any number of imaginable scenarios that might require or at least suggest the use of a command-line client. Here are several:
- Automated tools: users can use the power of their environment (shell scripts, DOS batch script) combined with other tools (like cron) to automate uploads and downloads. The output of the tools makes aggregating information (hashes, directories) simple, which can be stored in files or databases with little additional work.
- Headless environments: If you work in any environment that does not offer desktop access (such as SSH or a GUI-less operating system), you can use the command-line interface in a familar way
- Less overhead: Requires less resources (memory and CPU) than GUI interface
- Quick, stable interface: The command-line arguments, along with return codes, are stabilizing, and we will aim for backwards compatability to maintain integrity of existing user tools and familiarity
Because the standard output is tightly controlled (see usage for individual tools) to help automate task, capturing information is quite simple. Furthermore, the status codes are useful for automated responses to many of the problems that might occur. (See example scripts.)
How to use these tools
Step 1: Click on any of the following links to download the tool (links will be provided in each section as well):
- Download the upload tool, ZIP archive
- Download the download tool, ZIP archive
Step 2: Unzip the downloaded archive
Step 3: In your shell, navigate to the unzipped directory
Step 4: Type the following, replacing NAME.jar with the proper name:
This will print out the usage information, which includes a description of the tool, arguments and return codes.
Note: If java is not in your system's path, you can either add it to your path or type the full path, e.g.:
Download tool
Download the download tool, ZIP archive
After unziping, run the following for information on options, return codes, etc.:
A minimal command would simply download a project with a certain hash. E.g.:
If you run the above command, you will download the Tranche fractal.
Some projects are encrypted, so you will need to provide a passphrase:
The password, "supersecret", will unencrypt the data. Without the password, the download will fail. If you run the above, you will get the same Tranche fractal—it was simply encrypted.
The standard output is the path to the directory for the downloaded directory. There are options as well for more verbose output. See the usage.
Upload tool
Download the upload tool, ZIP archive
After unziping, run the following for information on options, return codes, etc.:
A minimal command would simply upload a project. E.g.:
Some quick notes:
- bryan.zip.encrypted, and the passphrase to use it, "supersecret", is required to write data. You can log in (or apply) to download a user file at http://www.proteomecommons.org/autocert/.
- /home/besmit/data/DataForUpload is the path to the directory I am going to upload
While this minimal command will upload a project, users browsing the projects using other tools (e.g., GUI, web, etc.) will not see a title nor a description. To example this example:
You may also specify paths to plain-text files containing the title and description:
You may also encrypt the data using the -e flag:
Example scripts
This section provides example scripts. For examples on using the tools individually, see the respect sections in the contents.
Sample Unix Bash shell scripts
- download-hashes-from-file.sh: Downloads a list projects/files. The script accepts one argument: a path to an input file with one Tranche hash per file. (Note does not work for encrypted projects. You could adapt to read in passwords using the -e option.)
- upload-directories-and-store-hashes.sh: The script accepts one argument: a path to a directory containing other directories, which are uploaded as projects. (Non-directories are skipped.) Looks for files providing title and description for each project. Stores hashes for uploads in file. (If going to use, need to modify to use your user certificate and password.)
Join group for updates
If you use either the command-line tools or API to access the Tranche network, you should join our Google Group, ProteomeCommons.org Tranche Command-Line Tools and API (link: http://groups.google.com/group/proteomecommonsorg-tranche-command-line-tools).
As a member, you will receive occasional information about new updates, bug fixes, etc. This should be a low-activity group with minimal information so that users..