Fioctl CLI Installation

Fioctl is a simple tool that interacts with the Foundries.io REST API for managing a Factory. It is based on the ota-lite API, also built by Foundries.io.

Fioctl, is used to manage:

Installation

Manual Installation

We use Github Releases to distribute static X86_64 golang binaries.

  1. Download a Linux binary from the Github Releases page to a directory on your PATH, make sure you have Curl installed

    For example, to download version v0.23 on Linux, define the version:

    FIOCTL_VERSION="v0.23"
    

    Download the binary with curl:

    sudo curl -o /usr/local/bin/fioctl -LO https://github.com/foundriesio/fioctl/releases/download/$FIOCTL_VERSION/fioctl-linux-amd64
    
  2. Make the Fioctl binary executable:

    sudo chmod +x /usr/local/bin/fioctl
    

You can execute this again in future to overwrite your binary, therefore updating or changing your version.

  1. Download a Darwin binary from the Github Releases page to a directory on your PATH, make sure you have Curl installed

    For example, to download version v0.23 on macOS, define the version:

    FIOCTL_VERSION="v0.23"
    

    Download the binary with curl:

    curl -o /usr/local/bin/fioctl -LO https://github.com/foundriesio/fioctl/releases/download/$FIOCTL_VERSION/fioctl-darwin-amd64
    

    Note

    For MacOS running on a Apple M1 processor, replace fioctl-darwin-amd64 with fioctl-darwin-arm64, and set FIOCTL_VERSION to v0.21 or newer.

  2. Make the Fioctl binary executable:

    sudo chmod +x /usr/local/bin/fioctl
    

You can execute this again in future to overwrite your binary, therefore updating or changing your version.

  1. Download a Windows binary from the Github Releases page.

  2. Put it in a folder of your choosing and rename it to fioctl.exe

  3. Press Win + R and type SystemPropertiesAdvanced

  4. Press enter or click OK.

  5. Click “Environment Variables…” in the resultant menu..

  6. Click the Path system variable, then click Edit...

  7. Click New in the “Edit environment variable” menu.

  8. Enter the path to the folder in which you have placed Fioctl.

    An example path string if installing to a folder on the desktop would look like this.

    C:\Users\Gavin\Desktop\fio\bin

You should now be able to open cmd.exe or powershell.exe and type fioctl.

Install From Source

Note

This requires that you have Golang installed. See https://golang.org/doc/install for instructions.

If you intend to use Fioctl on a non X86_64 platform (like a Raspberry Pi/Pinebook/Smartphone) such as ARM, RISC-V, PPC, etc. Fioctl can be compiled and installed from the latest sources and installed via Golang’s own package manager; go get:

go get github.com/foundriesio/fioctl

Authenticate fioctl

Now that Fioctl is installed, you must authenticate with our backend before you’re able to use it. This requires you to generate OAuth2 application credentials for interacting with Factory APIs:

fioctl login
 Please visit:

 https://app.foundries.io/settings/tokens/

 and create a new "Application Credential" to provide inputs below.

 Client ID:

Fioctl will now ask for your Client ID and Secret. Follow the next steps to generate it.

Application Credentials

Go to Tokens and create a new Application Credentials by clicking on + New Credentials.

../../_images/application_credentials.png

Fig. 7 Application Credentials

Complete with a Description and the Expiration date and select next.

For fioctl, check the Use for tools like fioctl box and select your Factory. Remember that you can revoke this access and set up a new credential later once you are familiar with the API Access.

../../_images/fioctl_token.png

Fig. 8 API Token

Tip

We recommend creating a new API token for each device you plan to use our tools with. For example, if you intend to develop on multiple systems such as a laptop and a desktop, you should create a new token for each, just as you would with SSH keys. This way you can revoke tokens for individual systems, should they be compromised.

Use the Client ID and Secret to finish the fioctl login.

../../_images/token1.png

Fig. 9 Client ID and Secret

fioctl login
 Please visit:

 https://app.foundries.io/settings/tokens/

 and create a new "Application Credential" to provide inputs below.

 Client ID:
 Client secret:
 You are now logged in to Foundries.io services.

Configuration

When working with multiple factories, specifying a factory name is mandatory. It can be set using 3 different methods:

  • Argument:

    fioctl targets list --factory <factory>
    
  • Environment Variable:

export FIOCTL_FACTORY=<factory>
fioctl targets list
  • Configuration File:
echo "factory: <factory>" >> $HOME/.config/fioctl.yaml
fioctl targets list

Note

Refer to the Fioctl section of the documentation to learn more about configuration.