Skip to content

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:

1
2
3
> fw version
flywheel-cli
  version: 18.3.0

Login

Before using any commands, you will need to use your API key to login to your instance of Flywheel:

1
2
> fw login <redacted>
You are now logged in as John Doe!

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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
> 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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
> 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:

1
2
3
4
> fw ls
admin neuroscience
admin clinical
admin psychology

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:

1
2
3
4
5
6
7
8
9
> 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:

1
2
> fw download "neuroscience/Cerebellum Circuitry/InformedConsent_MRI.pdf"
Wrote 104 kB to InformedConsent_MRI.pdf

You can also download a project, session, or acquisition:

1
2
3
4
5
> 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:

1
2
> fw upload "neuroscience/Cerebellum Circuitry" config.json
Uploaded file to neuroscience/Cerebellum Circuitry.

You can then see the file in by running fw ls:

1
2
3
4
5
6
$ 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.