Flywheel CLI Usage and Examples
This document provides information on CLI usage and Examples.
Basic Setup
Check Version
To check the currently-installed version of the Flywheel CLI, run the fw version command:
Login
Before using any commands, you will need to use your API key to login to your instance of Flywheel:
Where <redacted> is substituted with your real API Key. Do not share your key with anybody else!
Security Tip
Everything entered on the command line is recorded in a history file on your computer in plain text -- this may include your API key if you enter it in-line with fw login <api-key>!
To prevent your API key from being stored in your command history, you may choose to store your API key in a text file instead. To do this, create a new text file (e.g., fw-api-key.txt) and place only your API key in it. Then, you can pipe it the contents of the file into the fw login command using xargs like so:
cat /path/to/fw-api-key.txt | xargs fw login
With this approach, your API key is still stored in clear text on your local computer, but it is at least only stored in a single place (the text file you created) instead of potentially being copied multiple times throughout your command history.
For even better security, consider encrypting your credentials file using using a tool like SOPS or by migrating to password manager like 1Password.
Getting Help
Try running fw without any arguments (with or without -h) to get a feel for what commands are available.
> fw -h
Flywheel command-line interface
Usage:
fw [command]
Available Commands:
cp Copy a local file to a remote location, or vice-a-versa
deid Create and test de-identification template
download Download a remote file or container
export Export data from Flywheel
ingest Ingest large datasets into Flywheel
job [DEPRECATED] Start or manage server jobs
login Login to a Flywheel instance
logout Delete your saved API key
ls Show remote files
status See your current login status
sync Sync files from Flywheel to storage
upload Upload a local file to a Flywheel container
version Print CLI version
Flags:
-h, --help help for fw
Use "fw [command] --help" for more information about a command.
You can append -h or --help to any command to get more information. For example, using the -h option with the fw download command will show:
> fw download -h
usage: fw download [-h] [--config-file CONFIG_FILE | --no-config] [-y] [--ca-certs CA_CERTS] [--timezone TIMEZONE]
[--debug | --quiet] [-o [OUTPUT]] [-p PREFIX] [-i INCLUDE] [-e EXCLUDE] [--zip]
src
positional arguments:
src The path to a flywheel file or container (e.g. fw://group/project)
options:
-h, --help show this help message and exit
--config-file CONFIG_FILE, -C CONFIG_FILE
Specify configuration options via config file
--no-config Do NOT load the default configuration file
-y, --yes Assume the answer is yes to all prompts
--ca-certs CA_CERTS The file to use for SSL Certificate Validation
--timezone TIMEZONE Set the effective local timezone for imports
--debug Turn on debug logging
--quiet Squelch log messages to the console
-o [OUTPUT], --output [OUTPUT]
Destination filename (-- for stdout)
-p PREFIX, --prefix PREFIX
Prefix for downloaded directory structure
-i INCLUDE, --include INCLUDE
Download only these types
-e EXCLUDE, --exclude EXCLUDE
Download everything but these types
--zip Download container in .zip archive format
Managing Data
Viewing
We can start with fw ls to explore the Flywheel hierarchy and locate data:
This lists the groups available to you, alongside your current permission level. For example, this user is an admin in each of these three groups: neuroscience, clinical, and psychology
Tip
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 fw ls further into the hierarchy, much as you would with your system ls command:
> 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.
Downloading
You can download a file with fw download in much the same way you use fw ls:
> fw download "neuroscience/Cerebellum Circuitry/InformedConsent_MRI.pdf"
Wrote 104 kB to InformedConsent_MRI.pdf
You can also download a project, session, or acquisition:
> fw download "neuroscience/Cerebellum Circuitry"
This download will be about 14 GB comprising 1865 files.
Continue? (yes/no):
# ...
Uploading
To upload a file, enter the name of the container in Flywheel and the path to the file on your local computer:
> fw upload "neuroscience/Cerebellum Circuitry" config.json
Uploaded file to neuroscience/Cerebellum Circuitry.
You can then see the file in by running fw ls:
$ 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
Learn More
There are many more commands available in the CLI, particularly for interacting with large volumes of data of various formats. More information about each command can found in the Command References documentation folder.