The iBridges Command Line Interface (CLI)

In the previous chapter, we learned how to connect to an iRODS server and explore data using the iBridges GUI.
The GUI gives you a visual overview of collections, metadata, permissions, and replicas.

In this chapter, we use the same configuration and perform the equivalent operations using the Command Line Interface (CLI).
The CLI exposes every action as a command, making it ideal for automation, scripting, and reproducible workflows.

iBridges help system

To list all available commands:

ibridges -h

Each subcommand also includes its own help:

ibridges <command> -h

This mirrors the GUI’s menu structure: every action is discoverable and documented.

Connect

Before interacting with iRODS, we must ensure that the correct environment configuration is active.

Inspect existing configurations

ibridges alias

Example output:

* [no alias] -> /Users/christine/.irods/irods_environment.json
  geo        -> /Users/christine/.irods/irods_environment_geo.json

The asterisk marks the currently active environment.

There is always one configuration with no alias/name that points to the default location for your irods_environment.json file. Other libraries such as the icommands and python-irodsclient will use this file by default.

Adding or removing configurations

In case you have access to multiple iRODS instances, or you have different configurations for one iRODS instance, you might want to use multiple configurations at the same time. This can be done with the ibridges alias command:

ibridges alias a_new_alias /path/to/some/irods_environment_file.json

You can of course also delet aliases when you don’t need them anymore:

ibridges alias a_new_alias --delete

Switching environments

Activate a configuration by its path:

ibridges init /Users/christine/.irods/irods_environment.json

or by its alias:

ibridges init surf

We only need the init to switch between configurations or when our passwords are expired and need to be refreshed.

Browsing through data

The CLI provides several commands that correspond directly to the GUI’s Browser view.

Listing collections

ibridges ls

This shows the contents of the current iRODS directory.

Navigating

Use cd to change directories:

ibridges cd demo

To go up one level:

ibridges cd ..

Creating collections

ibridges mkcoll demo2

Viewing the hierarchy

ibridges tree

This prints a tree‑like structure similar to the GUI’s folder table.

TipExercise Navigation (5 minutes)

See Exercise slide.

Transferring data

Explore the help of the relevant commands:

ibridges upload -h
ibridges download -h

Uploading and downloading

Upload your hello.txt file:

ibridges upload hello.txt irods:demo

Download it again:

ibridges download irods:demo/hello.txt .

Synchronising

ibridges sync

This synchronises a local folder with an iRODS collection.

TipExercise Uploading, Downloading, .. (15 minutes)

See Exercise slide.

Recap: why the irods: prefix?

The CLI must distinguish between local paths and iRODS paths.
The prefix irods: marks a path as remote, ensuring the command knows which side of the transfer you mean.

Metadata

You can inspect metadata using:

ibridges ls -m demo

To add metadata:

ibridges meta-add demo type example_data

Overwriting metadata

Try adding the same key again with a different value:

ibridges meta-add demo type ascii

As in the GUI, iRODS allows multiple triples with the same key and value if the units differ.

TipExercise: Downloading metadata only (5 minutes)

See Exercise slide.

Searching for data

The CLI mirrors the GUI’s search functionality.

Inspect the help:

ibridges search -h

Try searching for the metadata you discovered earlier.

TipExercise: Searching for data (10 minutes)

See Exercise slide.

The iBridges Shell

The iBridges CLI also has a special command: ibridges shell. This opens up a new shell where you can perform many of the same commands as the normal CLI. The main advantages:

• Commands (such as ls) are much faster, since the session is maintained
• Autocompletion is supported (not for Windows)
• History for shell commands
• You don’t have to type ibridges before every command.

You can start the shell with:

ibridges shell

And submit commands, for example:

ibshell:home>ls
game
ibshell:home>cd game
ibshell:game>ls
a_very_nice_game.bin

While working in the shell you can also quickly open up the GUI by typing:

ibshell:some_col>gui

In this case the GUI will start without you having to login, and it will navigate to the collection that you were in while working in the shell.

Summary

The CLI gives you full control over iRODS operations:

• Switching configurations
  
• Navigating collections
  
• Uploading, downloading, and synchronising data
  
• Creating and editing metadata
  
• Searching for data
  
• Inspecting permissions and replicas (via ls flags)

It mirrors the GUI but exposes every operation as a command.

GUI vs CLI

The GUI and CLI are two views on the same iRODS concepts.

Overview Table

Concept	GUI	CLI
Configuration	Configure → Add Configuration	ibridges alias, ibridges init
Connect to iRODS	Connect → Connect to iRODS	Uses active environment; no explicit “connect” command
Browse collections	Browser view, navigation bar	ibridges ls, ibridges cd, ibridges tree
Create collection	Button: Create Collection	ibridges mkcoll
Upload data	Upload pop‑up	ibridges upload
Download data	Download pop‑up	ibridges download
Metadata	Metadata panel	ibridges ls -m, ibridges meta-add, meta-rm, meta-edit
Search	Search tab	ibridges search
Synchronisation	Synchronisation tab	ibridges sync
Permissions	Permissions tab	ibridges ls -A
Replicas	Replicas tab	—

Working with data

In the GUI, you interact with collections and data objects through buttons, tables, pop‑ups and the synchronisation tab.
In the CLI, you perform the same operations using explicit commands such as ibridges ls, ibridges upload, and ibridges meta-add.

Metadata

The GUI shows metadata in a dedicated panel.
The CLI exposes metadata through flags (-m) and commands (meta-add, meta-rm, meta-edit).
Both interfaces follow the same iRODS rules: metadata triples must be unique only in their full Key‑Value‑Unit combination.

Permissions and replicas

The GUI provides visual tabs.
The CLI uses flags (-A for accession permissions) to show the same information. The CLI currently does not show the replicas stored under the digital object.

Policies

In both interfaces, policies are not “visible” as code, you observe them through their effects:
automatic metadata, ownership changes, or other server‑side actions.

Exercise Slides

Open slides in a new tab