Skip to main content

Command Line Interface

The Riverscapes Command Line Interface (rscli) is a small, lightweight application for interacting with the Riverscapes Data Exchange and the associated API. Using rscli simplifies the process of uploading and downloading data from the Riverscapes Data Exchange. It handles authenticating your user account and validating data uploads.

Prerequisites

You must have Node.js version 18 installed on your computer to use rscli. You can download the latest version of Node.js from the official website. At the time of writing, it must be version 18, preferably the Long Term Support (LTS) version.

Installing and Updating rscli

Open a command-line terminal (such as Windows Terminal, macOS Terminal, or a Linux terminal) and run the following command. Follow the instructions on the official Node.js web site for the steps specific to your operating system. To update Node.js to latest version, use the same command as for installation.

npm install -g @riverscapes/cli

Using rscli

Since rscli is a command line application, to use it open the command line prompt used to install it (above) and run the rscli command. The application has excellent POSIX help for all the available commands and options. To see the help, run the following command:

rscli --help

Uploading Projects

For help uploading data, run the following command:

rscli upload --help

When uploading a riverscapes project you should have a folder on your local computer that contains the project itself. You will also need to know the entity that will own the project once it is uploaded. This is typically a Riverscapes Data Exchange organizations, but might also be a single user account. Optionally you might also want to provide some tags to associate with the project. You can change both the owner and tags after the upload, it's just easier if you provide them at the time of upload.

In the following example the operator is attempting to upload a project. They have already navigated their command terminal so that the prompt is inside the folder where the project.rs.xml resides. This allows the upload to refer to the project location using a single period, i.e. the current folder. The uploaded project will be owned by an organization, in this case the Utah State University RAM laboratory, identified by the GUID. Two tags are also specified, delineated by commas.

rscli upload --org a52b8094-7a1d-4171-955c-ad30ae935296 --tags tag1,tag2 .

Running this command will pop open a browser to authenticate your Riverscapes Data Exchange account. It will check that you have contributor (or higher) permissions for the specified organization. It will then validate the project to be uploaded, checking that all files mentioned in the project.rs.xml file are indeed present on the local file system. It will also validate that the project.rs.xml XML syntax is valid. Only then will the upload begin, after prompting you one last time whether to proceed. Progress bars will appear for each file uploaded.

After the command has finished the command line will show the URL of the uploaded project. Copy this URL and paste it into a web browser to view the project in the Riverscapes Data Exchange.

upload

Note that rscli can also be used to update projects that already exist on the Riverscapes Data Exchange. You cannot specify a new owner when doing this, but it is a useful mechanism if you have made changes to a project on your computer and want to synchronize them to the Data Exchange.

warning

Use caution when updating existing projects. Your local copy of the project will overwrite any changes that have been made in the Data Exchange (e.g. project description or metadata) since you downloaded the project.

Downloading Projects

The most common rscli use case is to download projects from the Riverscapes Data Exchange. The syntax for the download command is below; replace <local_empty_folder> with a path on your computer to folder where the project will be downloaded or updated. Replace the <project_guid> with the GUID of a project.

rscli download <local_empty_folder> --id <project_guid>

You can obtain this GUID from the URL when viewing the project details in the Data Exchange and copy it using the copy buttons that are available in several places throughout the data exchange.

copying GUID from data exchange

The Data Exchange can sometimes struggle to zip very large projects ( > 1.5 GB). Because rscli does not download a zip file, but instead downloads individual files, it can be used as an alternative for downloading large projects. rscli also works with file regex making it useful if you only want to download one or two known files within a project and not the whole project itself (see below).

Requirements

You must have read permissions to access the project before you can download it. If you can see the project details and download it in the Data Exchange then you should be able to download the project using rscli. While downloading projects from the Data Exchange results in a zip file, rscli download the project as individual uncompressed files to the specified root project directory.

Downloading a project to your machine that does not already exist locally - from the command line

If you want to download a project to your machine in folder that does not exist, you need to:

  1. Navigate to the path where you wish to download and create a project folder, (you can only download a new project to a completely empty folder). This folder and path can have other files and folders in it, but when you type the command prompt, you will append to the end of it the name of the folder you wish to create that will be empty.
  2. Copy the path of this folder (case-sensitive)
  3. Obtain Project GUID for project you wish to download
  4. Start a command line (e.g. in windows type in the search bar cmd)
  5. Navigate to the drive (folder position does not matter) you wish to download to. For example if you are at a command prompt in the c:\ and wish to download to d:\ type d:\ at command prompt. Or if you started your CLI in C:\Users\YourName, type cd\ at command prompt to return to root drive.
  6. Type the download command and follow the prompts.

It is sensitive to case, if the folder you specify to download to exists (it will not work), and command prompt path from which the command is invoked.

For example, to download this BRAT project with Project ID 9f771a97-41d8-4edf-876f-de64d47ec7b4 to an empty folder you created at: C:\0_RS\BRAT\Spokane_BRAT, you would type (note that the subfolder SpokaneBRAT does not exist and will get created by this command):

rscli download C:\0_RS\BRAT\SpokaneBRAT --id 9f771a97-41d8-4edf-876f-de64d47ec7b4

See illustration of this example in this video:

Using download to update a project that already exists on your machine

The download command can also be used to smartly update an existing project that you have already downloaded but was changed (locally) or remotely, so that the downloaded copy matches that on that data exchange.

  1. Navigate to the path of the root folder for the existing riverscapes project. This folder must at least contain the correct project.rs.xml project file in it!
  2. Copy the path of this folder (case-sensitive)
  3. Obtain Project GUID for project you wish to download (you can do this by opening the project.rs.xml and
  4. Start the command line
  5. Navigate to the drive (folder position does not matter) you wish to download to. For example if you are at a command prompt in the c:\ and wish to download to d:\ type d:\at command prompt. Or if you started your CLI in C:\Users\YourName, type cd\ at command prompt to return to root drive.
  6. Type the download command and follow the prompts.

As with above, rscli is sensitive to case, whether or not folder is empty, and command prompt path from which the command is invoked.

For example, to update locally this existing BRAT project downloaded to my machine with Project ID 9f771a97-41d8-4edf-876f-de64d47ec7b4 to an existing folder at: C:\0_RS\BRAT\Spokane_BRAT, you would type:

rscli download C:\0_RS\BRAT\SpokaneBRAT --id 9f771a97-41d8-4edf-876f-de64d47ec7b4

See illustration of this example in this video:

Command line help downloading

For help downloading data, run the following command:

rscli download --help

Downloading specific files from a project

The --file-filter option allows you to download only files that match a specific pattern, described using regex. The project.rs.xml file is always downloaded, and the files are downloaded respecting the folder structure of the project.

Here are some examples.

Download only the project bounds file

rscli download <local_empty_folder> --id <project_guid> --file-filter "project_bounds\.geojson"

Explanation: Replace <your_local_folder> and <project_guid> with the actual values, no angle brackets.

Download only GeoPackages

rscli download <local_empty_folder> --id <project_guid> --file-filter "\.gpkg$"

Explanation: The $ character in regex means "end of the line", so this pattern will match any file that ends with .gpkg.

Download set of specific files

This will download any file with vegetation in the name, the nhdplushr.gpkg file, the dem_hillshade.tif file, and the project bounds file.

rscli download <your_local_folder> --id <project_guid> --file-filter "(vegetation|nhdplushr.gpkg|dem_hillshade.tif|project_bounds.geojson)"

Explanation: The file filter is a regex pattern, so the | character is used to separate the patterns. The . in regex means "any character", so if there was a file called dem_hillshade-tif.jpg, that would match as well.