Installing the Command–Line Interface (CLI)

  • Updated

The Flywheel command-line interface (CLI) is an additional Flywheel program you download to use on your computer's Command Prompt (Windows) or Terminal (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 (you can learn more about the Command Prompt and Terminal app in this introductory article by Codcademy.)

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 as well as how to add the Flywheel CLI to your PATH.

Step 1: Download

To download the Flywheel CLI:

  1. Log in to 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.

    DownloadFlywheelCLI-export.png

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

  • Linux: fw-linux_amd64.zip

  • OS X: fw-darwin_amd64.zip

  • 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.

    1. Go back to your Flywheel User Profile from Step 1.
    2. Scroll down to the API Key section.
      FlywheelUserProfile-export.png
    3. Click Generate API Key.
      Caution
      Do not share your API key with anyone – even Flywheel support. Treat the API> key like a password used to sign in to Flywheel.

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

Follow the steps for your OS either Windows or Linux and Mac

Windows

  1. Double-click fw-windows_amd64<version_number> to unzip the file. You should see a fw.exe file inside. This is the Flywheel CLI program.
  2. Open the Command Prompt as an administrator.
    1. From the start menu, search Command.
      Command Prompt appears as one of the results.
    2. Right click on Command Prompt, and choose Run as Administrator.
      WindowsCommandPromptOpen.gif
  3. In the Command Prompt, navigate to the folder containing the Flywheel CLI or fw.exe
    For example: cd C:\Users\[yourusername]\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. The file path is automatically added to the command.

Linux and Mac

  1. Open the Terminal app.
  2. Unzip the file by double clicking on it. Now the fw app is located  in your Downloads folder.
  3. If you are using macOS 10.15 Catalina release (or later), you need to add the Flywheel CLI as a security exception. If you are using an earlier macOS version or Linux, continue to step To add the Flywheel CLI as a security exception:
    1. Right-click on fw, and click Open.
      fwWarning.png
    2. Click Open on the warning prompt.
  1. In Terminal, navigate to the Flywheel CLI. For example:
      • Mac: cd ~/Downloads/darwin_amd64*
      • Linux: cd ~/Downloads/fw-linux_amd64/linux_amd64*
        To quickly add the file path to Command Prompt, drag and drop the fw icon from the Downloads folder to the Terminal window.> The file path will automatically be added to the command.
  1. Continue to Step 4: Log in from the CLII

Step 4: Log in from the CLI

  1. Copy the API key generated from Step 2 above.
  2. In Terminal or Command Prompt, enter:
      • Windows: fw.exe login <APIkey>
        For example:fwloginWindows-highlight.png
      • Mac/Linux: <filepath to fw> login <yourAPIKey> 
        loginCLIexampletext-export.png
  1. The following message appears: You are now logged in as <Flywheel username>!

The Flywheel CLI is installed! Learn more about how to import data with the CLI or other examples for using the CLI. 

Optional Step: Add fw to your PATH

You may have noticed in the steps above you have to include the full file path for the fw application when you enter a command. If you plan to use the Flywheel CLI often, you may want to add it to your computer’s PATH. Adding the Flywheel CLI to your PATH means that you only need to use fw to use the Flywheel CLI. If you want to learn more about the PATH variable, see this article by Oracle.

Below are steps for adding fw to your PATH on Windows or Mac and Linux computers.

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 file path to fw.exe.
    For example: C:\Users\IEUser\FlywheelCLI
  1. Click Ok in each window
    AddfwtoPathwin10.gif
  1. In the command prompt enter: fw status
    The CLI shows your login information

Mac and Linux

  1. Verify you are in the darwin_amd64 folder in Terminal
  2. In Terminal, enter the following command:sudo mv ./fw /usr/local/bin
  3. Enter your password.
    Note that Terminal does not show characters as you type your password.
  4. To confirm fw was added to your PATH, enter: fw status 
    AddfwToPathTerminal-exampletext.png
  5. You should see your Flywheel username and the site you are signed in to.