OpenNeuro command line interface

This tool allows you to upload and download OpenNeuro.org datasets without a browser.

Install

  1. Install Deno via any supported installation method.

  2. In a terminal type: deno run -A jsr:@openneuro/cli --help

To download annexed files, you will need the git-annex special remote for OpenNeuro.

# A script is provided to wrap the CLI as a special remote
curl https://raw.githubusercontent.com/OpenNeuroOrg/openneuro/refs/heads/master/bin/git-annex-remote-openneuro -o git-annex-remote-openneuro
# Make this executable and move this script to your path
chmod +x git-annex-remote-openneuro

Setup

The setup step is needed for both uploading and downloading data from OpenNeuro.

Run deno run -A jsr:@openneuro/cli login to configure credentials. This prompts you for the required configuration fields and these are saved in Deno’s local storage.

deno run -A jsr:@openneuro/cli login will require you to enter an API key.

You can obtain an API key via a browser on OpenNeuro after logging to the OpenNeuro platform via one of the provided authentication services (for example ORCID).

You can also specify this as an option or environment variable.

# For scripts
export OPENNEURO_API_KEY=<api_key>
deno run -A jsr:@openneuro/cli login --error-reporting true

Usage

Uploading datasets

To upload a new dataset:

# Path to the dataset root (directory containing dataset_description.json)
deno run -A jsr:@openneuro/cli upload --affirmDefaced path/to/dataset

Your dataset must pass validation to upload but warnings can be skipped with deno run -A jsr:@openneuro/cli upload --ignoreWarnings path/to/dataset.

To resume an interrupted upload or add files to an existing dataset:

# Add files to an existing dataset
deno run -A jsr:@openneuro/cli upload --dataset ds000001 path/to/dataset

where <accession_number> is a unique dataset identifier that can be found in the URL. For example accession number for https://openneuro.org/datasets/ds001555 is ds001555.

This command will add or replace any files in the dataset but does not delete any files that are only present in the server copy of the dataset.

Downloading datasets

Downloads using the CLI will create a DataLad dataset and configure a special remote to retrieve the larger annexed files from OpenNeuro.

To download a snapshot:

deno run -A jsr:@openneuro/cli download <accession number> <destination directory>

To download the current draft files:

deno run -A jsr:@openneuro/cli download --draft <accession number> <destination directory>

If the destination directory does not exist, it will be created.

To download the annexed objects, use DataLad or git-annex.

cd ds000001
# Make sure you have the `git-annex-remote-openneuro` script available in your path
git-annex get <path or paths to download>
# DataLad is supported as well
datalad get <path or paths to download>

Debugging issues

# To debug issues - enable logging and provide this log to support or open a GitHub issue
export OPENNEURO_LOG=INFO
deno run -A jsr:@openneuro/cli upload --affirmDefaced path/to/dataset

Implementation Notes

This tool uses isomorphic git to download, modify, and push datasets using OpenNeuro’s git interface. Other tools that support git and git-annex repositories such as DataLad can also be used with the local copy.