CLI Usage and Examples
Introduction
This document provides information on CLI usage and Examples.
Instruction Steps
Basic Usage
Once the CLI is installed, use your API key to login to your instance of Flywheel:
Login
Try running fw without any arguments to get a feel for what commands are available.
Getting Help
With any command, you can add -h or --help to get more information. For example, with the download command that we will see in the next section:
Help
$ fw download -h
Download a remote file or container
Usage:
fw download [source-path] [flags]
Flags:
-e, --exclude stringSlice Download everything but these types
-f, --force Force download, without prompting
-h, --help help for download
-i, --include stringSlice Download only these types
-o, --output string Destination filename (-- for stdout)
Instruction Steps
Viewing, Downloading, and Uploading
We can start with fw ls:
Viewing
This lists the groups available to you, alongside your current permission level.
Note: Site Admin users can access all groups and projects (similar to Manage Site mode in the Web UI) by adding the -a or --all flag to the CLI command.
You can ls further into the hierarchy, much as you would with your system ls command:
ls
$ fw ls neuroscience
admin Amygdala Structure
admin Cerebellum Circuitry
$ fw ls "neuroscience/Cerebellum Circuitry"
admin May 7 08:42 ccirc_sub_1 ccirc_sub_1_ccirc_ses2_protB
admin Jan 7 17:30 ccirc_sub_1 ccirc_sub_1_ccirc_ses1_protA
# ...
admin Jun 14 16:52 InformedConsent_MRI.pdf
This shows projects, and then sessions. For sessions, you can see the timestamp and subject code.
The last entry is an attachment on the project. You can download a file the same way you ls:
Project Session
$ fw download "neuroscience/Cerebellum Circuitry/InformedConsent_MRI.pdf"
Wrote 104 kB to InformedConsent_MRI.pdf
You can also download a project, session, or acquisition:
Download
$ fw download "neuroscience/Cerebellum Circuitry"
This download will be about 14 GB comprising 1865 files.
Continue? (yes/no):
# ...
To upload a file, enter the name of the container, and then the file path:
Upload
$ fw upload "neuroscience/Cerebellum Circuitry" config.json
Uploaded file to neuroscience/Cerebellum Circuitry.
You will then see the file in your next ls:
Result
$ fw ls "neuroscience/Cerebellum Circuitry"
admin May 7 08:42 ccirc_sub_1 ccirc_sub_1_ccirc_ses2_protB
admin Jan 7 17:30 ccirc_sub_1 ccirc_sub_1_ccirc_ses1_protA
# ...
admin Jun 14 16:52 InformedConsent_MRI.pdf
admin Sep 8 16:38 config.json
Running a Job
You can launch a job from the command-line the same way you would from the web UI.
First, have a look at what gears are available:
Jobs
$ fw job list-gears
**dcm2niix**DCM2NIIX: dcm2nii DICOM to NIfTI converter
**dicom-mr-classifier** SciTran: DICOM MR Classifier
**mriqc** MRIQC: No-reference image quality metrics for quality assessment of MRI
Let's run the dcm2niix gear.
DCM2NIIX
This gear requires one file as its input. The full available configuration can be see by adding -h:
Input
$ fw job run dcm2niix -h
Start a job.
Usage:
run [flags]
Flags:
--anonymize_bids string Anonymize BIDS (y/n, default n)
--bids_sidecar string Output BIDS sidecar in JSON format. Options are 'y'=yes, 'n'=no, and 'o'=only (whereby no NIfTI file will be generated). Default='n'.
--compress_nifti string Compress output NIfTI file (y/n/3, default y) [y=pigz, n=no, 3=no,3D]. Note that if option '3' is chosen, the filename flag will be set to '-f %p_%s' to prevent overwriting files
--convert_only_series string only convert this series number - can be used up to 16 times (default convert all). Provide series numbers in a space-separated list e.g., '12 13'
# ...
For this example, we're only going to provide the file. The path to a file is specified the same way you would ls, and set it as the flag requested earlier:
Profile File
$ fw job run dcm2niix --dcm2niix_input "clinical/Lung/anx_s2_anx_ses1_protA/fMRI high-res/468_8_1_fmri.dcm.zip"
Job configuration:
{
"anonymize_bids": "n",
"bids_sidecar": "n",
"compress_nifti": "y",
"crop": "n",
"decompress_dicoms": false,
"filename": "%f",
"ignore_derived": "n",
"merge2d": "n",
"philips_scaling": "y",
"single_file_mode": "n",
"text_notes_private": "n"
}
Job 59b2cac6ac35d80017d289c3 has been queued.
You can check on the status of your job, or wait for it to complete:
Check Status
The exit status of fw job wait will indicate if the job succeeded.