JuliaHub CLI (jh)

Introduction

JuliaHubCLI (invoked as jh) is a command-line interface to the JuliaHub platform. It simplifies dataset management and job execution, ensuring a consistent Data API across multiple environments, including Linux, Windows, RStudio, and VS Code. The CLI is distributed as a standalone executable for ease of use.

Warning

The JuliaHub CLI is still experimental, and has not been loaded on any job images yet. It will be announced when it does! Take this documentation as a description of what you will be able to do with it, not what you can do with it right now.

jh allows you to do the following things:

  • Dataset management (jh dataset ...)
    • Download and upload datasets from Linux, Windows, RStudio, and VS Code — all with the same CLI. (jh dataset download someuser/somedataset path/to/local/dataset and jh dataset upload path/to/local/dataset dataset_name)
    • Download all datasets related to the current project. (jh dataset download --project /path/to/datasets)

Installation

jh comes installed automatically in all services and applications on the JuliaHub platform, including VSCode, Windows Workstation, and any batch jobs or Applications.

Note

If you are running RStudio Server, then you can simply use the RJuliaHub integration library that is pre-installed there, you don't need jh.

<!– To build the compiled jh executable, run:

julia --proj=build build/build.jl

This will generate the build/app depot and the build/app/bin/jh executable.

To make jh accessible from anywhere, ensure the executable is on the system PATH. You can achieve this by either:

  • Extending the system PATH
  • Symlinking build/app/bin/jh into /usr/local/bin (Linux/macOS) or an equivalent directory on Windows.

–>

Basic Usage

Running jh

jh is a command line tool, so you can only use it in a terminal. Most JuliaHub applications and environments will make this available to you. On Windows, you can access jh in PowerShell or the command prompt.

To access help and see all available commands, use:

jh --help

Output:

usage: jh [-h] {dataset|job|auth}

Utility for interfacing with JuliaHub

commands:
  dataset
  job
  auth login

optional arguments:
  -h, --help  show this help message and exit

Dataset Management

The jh dataset command supports:

  • download – Retrieve datasets from JuliaHub.
  • upload – Upload datasets to JuliaHub.
  • list – List available datasets.

Usage:

jh dataset {download|upload|list}
  • jh dataset download user/dataset localpath will download the dataset username/dataset to the path localpath on your machine.
  • jh dataset upload localpath user/dataset will upload the file or directory at localpath to a new dataset user/dataset.
  • jh dataset list {all|mine|shared} will list datasets, subsetting based on the first argument:
    • all: all datasets you have access to,
    • mine: all datasets under your username,
    • shared: all datasets shared with you.

If you have opened the application through a project, jh can detect that, enabling the --project flag. With this, you can download all your datasets to a specific location:

jh dataset --project download /tmp/mydata

and list all datasets associated with your project:

jh dataset list --project

Job Management

The jh job command allows users to monitor and list their current jobs on the JuliaHub platform. In the future, this will also allow you to start a job, but that is still under development.

Usage:

jh job ...

For now, you can list all of your currently running job and get the logs from a job (referred to by its job ID from list).

jh job list
# lists all currently running juliahub jobs for you
jh job logs JOB_ID

Authentication

The jh auth login command manages user authentication.

If running on a specific server (the most likely scenario), you can specify the server via the --server option, as below:

jh auth login --server=yourserver.juliahub.com