Skip to content

Installing the Flywheel CLI

The Flywheel command-line interface (CLI) is an additional Flywheel program you download to use on your computer's Command Prompt (Windows) or Terminal (Linux, Mac) app. It is helpful to have a basic understanding of how the Command Prompt and Terminal apps work to get the most out of the Flywheel CLI. Learn more about the Command Prompt and Terminal app in this introductory article by Codecademy.

Flywheel's CLI is a tool for uploading existing data into Flywheel and downloading data from Flywheel to work with offline.

The Flywheel CLI is also required to start jobs and build gears.

This article explains how to install the Flywheel CLI onto your computer.

Before You Begin

Ensure you have:

System Requirements:

  • Operating System: Windows, macOS, or Linux
  • Command line access: Command Prompt (Windows) or Terminal (Mac/Linux)
  • Basic command line knowledge: Helpful for navigating directories and running commands

Flywheel Account:

  • Active Flywheel account with access to your organization's Flywheel site
  • Appropriate permissions to generate API keys (most users have this by default)

For macOS Catalina (10.15) or Later:

  • You'll need to make a security exception for the CLI after download
  • See macOS Catalina CLI Setup for detailed instructions

Step 1: Download

To download the Flywheel CLI:

  1. Log into Flywheel.

  2. In the upper-right corner, select your account menu and select Profile.

    Screen_Shot_2018-08-29_at_11.13.53_AM.png

  3. Go to the Download Flywheel CLI section and select your computer's operating system.

    360044575253-DownloadFlywheelCLI-export.png

    A zip file with the following name is downloaded to your computer:

  4. Linux: fw-linux_amd64.zip

  5. OS X: fw-darwin_amd64.zip
  6. Windows: fw-windows_amd64.zip

Step 2: Generate an API Key

To start using the CLI to interact with your Flywheel site, generate an API key from your Profile page. Learn more about creating User API Keys from the Profile page.

Step 3: Navigate to the fw.exe or fw app

Follow the steps for your OS: Windows or Linux/Mac.

Windows

  1. Double-click fw-windows_amd64<version_number> to unzip the file. There will be a fw.exe file inside. This is the Flywheel CLI program.

  2. Open the Command Prompt as an administrator.

  3. From the start menu, search Command.

    Command Prompt appears as one of the results.

  4. Right click on Command Prompt and choose Run as Administrator.

    WindowsCommandPromptOpen.gif

  5. In the Command Prompt, navigate to the folder containing the Flywheel CLI or fw.exe. E.g., cd C:\Users\[username]\Downloads\windows_amd64*

    Cdtofw_exe.gif

    Tip

    To quickly add the file path to Command Prompt, drag and drop the folder icon containing fw.exe file. The filepath will automatically be added to the command.

  6. Continue to Step 4: Log in your Flywheel instance

Linux and Mac

  1. Open the Terminal app.
  2. Unzip the file.
  3. If you are using macOS 10.15 Catalina release (or later), follow these steps to make a security exception for the Flywheel CLI.
    1. Right-click on fw, and click Open.
    2. Click Open on the warning prompt.
  4. In Terminal, navigate to the Flywheel CLI. For example:
    • Mac: cd ~/Downloads/darwin_amd64*
    • Linux: cd ~/Downloads/fw-linux_amd64/linux_amd64*
  5. Continue to Step 4: Log in from the CLI

Step 4: Log in from the CLI

  1. Copy the API key generated from Step 2 above.

  2. In Terminal or Command Prompt, enter:

  3. Windows: fw.exe login <API_key>

    For example:

    fwloginWindows-highlight.png

  4. Mac/Linux: <filepath to fw> login <API_key>

    For example:

    macfwlogin-export.png

  5. The following message appears:

    1
    You are now logged in as <Flywheel username>!

The Flywheel CLI is now installed! Read our article about how to import data with the CLI.

Verify Success

Confirm your CLI installation is working correctly:

1. Check Authentication

Run the status command:

1
fw status

Expected output:

1
You are currently logged in to https://your-site.flywheel.io as your.email@example.com

2. Test Basic Commands

Try listing your available groups:

1
fw ls

This should display groups you have access to with your permission levels.

3. Check CLI Version

Verify you have the latest version:

1
fw version

Output example:

1
2
flywheel-cli
  version: 20.3.1

Next Steps

After successful installation:

Optional Step: Add fw to your PATH

Notice in the steps above that you must include the full filepath for the fw application when you enter a command. Add it to your system PATH to run commands from any directory without specifying the full path.

Adding the Flywheel CLI to your PATH means that you only need to use fw to invoke the Flywheel CLI. If you want to learn more about the PATH variable, see this article by Oracle.

Windows

  1. To begin, move the fw or fw.exe file to a more permanent location on your computer. For example: C:\Program Files\Common Files
  2. Open the start menu and search for advanced system settings, and click View advanced system settings.
  3. Click Environment Variables.
  4. Select PATH from the list, and click Edit.

  5. Click New, and enter the filepath to fw.exe.

    For example C:\Users\IEUser\FlywheelCLI

  6. Click OK in each window.

    AddfwtoPathwin10.gif

  7. In the command prompt, enter fw status.

    The CLI shows your login information.

Mac and Linux

  1. In Terminal, enter the following command:

    sudo mv ./fw /usr/local/bin

  2. To confirm fw was added to your PATH, enter: fw status

    fwStatusExport.png