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
While iCommands are great for all transfers and for automating tasks via scripts, they are the best choice for large files (2-100 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 must be installed and configured for your system. Once set up, CyVerse users can use iCommands to access files that have been shared by other users, as well as manage metadata, change permissions on data files and folders you own, and more.
Even if you don't have an account, you can download public files using iCommands. For more information, see the page. For information on using iCommands, see Using iCommands.on the
For common Linux distributions, there are NetCDF iCommands available. Please see the NetCDF iCommands section.
For common Linux distributions, there are NetCDF iCommands available. Please see the NetCDF iCommands section for more information.
Setting up iCommands
iCommands must be set up and configured on each user's local machine or server, as outlined below, before you can transfer data to (with a CyVerse user account) and from the CyVerse Data Store using iCommands. Note that iCommands cannot be used to upload files into Data Store via URL from other sites (ftp, http, etc.). Without a CyVerse account, you can download public data from the Data Commons Repository (DCR).
For account users, you can download data from an external site using iCommands. To do so, download the file to a local machine using
wget or a similar mechanism and then use
iput to upload it to the Data Store. If you have a significant amount of external data to import from an external site, you may want to perform the transfer using a utility, such as Import by URL in the DE (not available using iCommands), or an Atmosphere instance.
Before you begin, you may want to watch a CyVerse video about iCommands.
Step 1: Download iCommands for your operating system
Because CyVerse products are interdependent with iRODS iCommands and iRODS products such as FUSE, the instructions for downloading iCommands vary according to your OS.
Installation via Package Manager
If you are using Linux and have the ability to install software (that is, you have sudo or root access) through a package manager such as yum or apt, you may install the
irods-icommands package obtainable from one of the following links.
The CentOS packages require the the yum be configured to access the EPEL repository. The Ubuntu 14 package appears to also work for Ubuntu 16.04. Run the package installation commands appropriate for your package manager, replacing the filename as appropriate for your distribution version, as in the following examples.
Next , continue to Step 2 to configure iCommands.
Installation for Unprivileged Users
If you cannot use one of the packages from iRODS, we provide some installers for CentOS and Ubuntu that don't require special privileges to use. To do so, do the following.
Download the correct installer.
From a terminal window, run the installer with
For example, if you were installing iCommands on an Ubuntu 14.04 system as the user
cyverse-user, you would do something like the following example. The iCommands would end up being placed in the directory
Important: To make the changes take effect in the current shell, you will need to source your
.bashrcfile by entering either
If you aren't using bash, or if your .bashrc file can't be edited, the environment variable
IRODS_PLUGINS_HOMEwill need to be set to
$INSTALL_BASEis the directory you provided to the installer. It is also recommended that you add the iCommands to your path.
Open a new terminal window, if necessary, and run
ienvto check that the new version was installed.
Continue to Step 2 to configure iCommands.
iRODS does not currently offer a 4.1 download for Mac OS. However, CyVerse has created a custom build of the iRODS 4.1.9 iCommands. To obtain these, do the following.
- Mac OS X iCommands 4.1.9 installer .
- Find the downloaded package, hold down the control button, and select the downloaded package.
- Click Open to give permission for Mac to open the package.
- Use the installer and follow the instructions .
- Open a new terminal window, if necessary, and run
ienvto check that the new version was installed.
- Continue to Step 2 to configure iCommands.
iRODS does not currently offer a 4.1 download for Windows users. If you are running Windows 10, iCommands can be run on the Linux subsystem. See https://docs.microsoft.com/en-us/windows/wsl/install-win10 for information on installing the Linux subsystem. Then follow the iCommands for Linux instructions to install iCommands.
Step 2: Initialize/start the iRODS connection and configure the settings (One-time only or after changing your configuration)
The first time you use iCommands, or after you change a configuration detail such as resetting your CyVerse password, you must initiate the connection to iRODS.
In a terminal window, enter
iinit to initialize iCommands and your Data Store connection. For example, here's what you would do if your iRODS user name is cyverse-user:
Here are the values to enter.
For this line:
(your CyVerse username)
(your CyVerse password)
|Default Resource||(leave blank)||Defaults to whatever is available|
iinit has finished, use
ils to check that the iCommands is working. You should see your home directory at /iplant/home/your_user_name
iexit full. (To log back in on the same device, enter iinit.
After you are successfully connected, you do not need to reenter your password to use the CyVerse Data Store from that computer unless you log out.
Advanced configuration settings (for power users only)
A full list of iRODS environment variables that may be set can be determined from
~/.irods/irods_environment.json section of the official iRODS documentation. The names environment variables are the all capitals version of the corresponding JSON field. Only
IRODS_ZONE_NAME are required for using the iCommands.
Setting up Bash autocomplete for iCommands
If using the Bash shell, you can enable tab auto-complete when using iCommands:
In your home directory, rename
.bash_profile, enter the following:
For the Linux distributions CentOS 6 and 7 and Ubuntu 12.04 and 14.04, there are three extra iCommands that support common NetCDF operations.
inc performs data operations on a list of NetCDF files.
incarch archives a open ended time series data.
incattr performs operation on attributes of NetCDF files. Each of these commands accepts the
-h command line option. When a command is called with this option, it displays the command's help documentation. Please see the help documentation for more information.
It is assumed that the core iCommands are already installed on your system. To install the NetCDF iCommands, root or
sudo access is required.
Before the NetCDF iCommands can be installed, the version 4.1.10 of the iRODS run time library needs to be installed. Please install the appropriate version of the
irods-runtime-4.1.10. The distribution specific packages can be found on RENCI's website.
Once the run-time library is installed, the iCommands can be installed. Please use appropriate link to download the installation package and install it.
To learn more about using iCommands and some common commands to use, see Using iCommands.