iCommands is a collection of commands for Linux and Mac OS operating systems that are used in the iRODS system to interact with the CyVerse Data Store. Many commands are very similar to Unix utilities. For example, to list files and directories, in Linux you use ls, but in iCommands you use ils.

While iCommands are great for all transfers and for automating tasks via scripts, they are the best choice for large files (> 2 GB each) and for bulk file transfers (many small files). For a comparison of the different methods of uploading and downloading data items, see Downloading and Uploading Data.

iCommands can be used by CyVerse account users to download files that have been shared by other users and to upload files to the Data Store, as well as add metadata, change permissions, and more. Commonly used iCommands are listed below. Follow the instructions on Setting Up iCommands for how to download and configure iCommands for your operating system.

A CyVerse account is not required to download a public data file via iCommands. To see instructions just for public data download with iCommands, see the iCommands section on Downloading Data Files Without a User Account.

Before you begin, you may want to watch a CyVerse video about iCommands.

About setup and configuration

Regardless of whether you want to download and upload data as a CyVerse user, or download public data without an account as an anonymous user, iCommands must be set up and configured on each user's local machine or server. For information on downloading and setting up iCommands for your operating system, see Setting Up iCommands.

For information on downloading public data files anonymously, see Downloading Data Files Without a User Account. To share data with a user, the user at minimum must have Read permission to the parent directory that contains the file and any other parent folders within the folder hierarchy.

In addition to using iCommands to share data from the command line, CyVerse users can upload and download data within the Discovery Environment. For more information, see Sharing Data Files and Folders Via the Discovery Environment.

Commonly used iCommands

These sample commands are entered from the command line once you have installed and configured iCommands on your computer.

For more information on using these and other iRODS commands, see the iRODS Documentation on the iRODS website, or enter the iCommand and -h to view the help file in a terminal window.

Enter any of the following iCommands in a command line.

icd

bash-3.2$ icd tmp
bash-3.2$ ils
/iplant/home/yourusername/tmp:
  2011_UA_PLS340_Genomics.key
  2011_UA_PLS340_Genomics.key.pdf
  AllHandsAug162011.key
  gff_annotation_loader.pl

ichmod write

iexit full

iget

bash-3.2$ iget -K file_name.txt

iinit

bash-3.2$ iinit
One or more fields in your iRODS environment file (.irodsEnv) are
missing; please enter them.
Enter the host name (DNS) of the server to connect to:data.iplantcollaborative.org
Enter the port number:1247
Enter your irods user name:yourusername
Enter your irods zone:iplant
Those values will be added to your environment file (for use by
other i-commands) if the login succeeds.
#* Enter your current iRODS password:
bash-3.2$=

ils

bash-3.2$ ils
/iplant/home/yourusername:
  .bashrc
  ._.DS_Store
  .DS_Store
  .i-commands-auto.bash
  C- /iplant/home/yourusername/analyses
  C- /iplant/home/yourusername/backup
  C- /iplant/home/yourusername/collections
  C- /iplant/home/yourusername/data
  C- /iplant/home/yourusername/tmp
  C- /iplant/home/yourusername/utilities 

ils -A

? ils -A /iplant/home/user/directory
/iplant/home/user/directory:
        ACL - g:rodsadmin#iplant:own   user#iplant:own   de-irods#iplant:own   
        Inheritance - Disabled
  1ouput-trimmed.fasta
        ACL - rodsadmin#iplant:own   user#iplant:read object   
  2ouput-trimmed.fasta
        ACL - rodsadmin#iplant:own   user#iplant:write object   
  C- /iplant/home/user/directory/subdirectory

imkdir

bash-3.2$ imkdir NewDataDirectory

iput

bash-3.2$ iput -K file_name.txt

ipwd

bash-3.2$ ipwd
  /iplant/home/yourusername/tmp

irm

bash-3.2$ irm file_name.txt

irm -f

bash-3.2$ irm -f file_name.txt

irm -r

bash-3.2$ irm -r file_name.txt

irm -fr

bash-3.2$ irm -fr file_name.txt

bash-3.2$ irync -r local_directory_name i:data_store_directory_name 

Reliability and troubleshooting tips and tricks

If you are having problems with reliability, try the following command options:

-T

--retries

-X <checkpoint-file>

--lfrestart <checkpoint-lf-file>

-P

Troubleshooting a failed DE analysis that uses a file uploaded via iCommands

If the file used in the failed analysis was uploaded to the Data Store via iCommands, verify that the filename does not contain any special characters or spaces. This has been known to cause analyses to fail. For more information, see Using Special Characters in the DE and Renaming a Data File or Folder in the DE.

Examples

Bulk files transfer example

iput -K -P -b -r -T --retries 3 -X checkpoint-file my-files-to-transfer/

Single large file transfer example

iput -K -P -T --retries 3 --lfrestart checkpoint-lf-file my-file-to-transfer.txt 

In the above examples:

• -K: To ensure data isn't corrupted during data transfer via iCommands, which can happen anytime data are transferred across the internet, CyVerse highly recommends that you include the -K option with iget and iput. This causes iCommands to verify that transferred files weren't corrupted during the transfer by comparing the Checksums computed before and after the transfer.
• my-files-to-transfer/ is the example name of the directory or folder for bulk transfers.
• my files-to-transfer.txt is the example name for single file transfers.
• Any filename may be used for the checkpoint-file.