fctl is a command line tool which allows you to configure SSH, port forwarding, and secure copy protocol (SCP) to your Formant device.

Supported platforms

fctl is available for the following systems:

The convenience script below auto-detects your OS and installs the correct package.

Prerequisites

Generate SSH keys

On Mac OS, you'll have to generate SSH keys before you can install fctl.

You can verify that the keys exist by opening a terminal and entering the following command:

cd ~/.ssh

If you see the following message: No such file or directory, you'll have to generate SSH keys. To do that, open a terminal and run the following command:

ssh-keygen

Follow the instructions in the terminal to generate SSH keys. Once you're done, you can verify that the directory exists by entering the following command again:

cd ~/.ssh

Apple silicon compatibility

If you're using a Mac with Apple silicon, you'll have to install Rosetta. For more information on Rosetta, see Apple: If you need to install Rosetta on your Mac.

To install Rosetta, open a terminal and run the following command:

softwareupdate --install-rosetta

Step 1: Install fctl

Convenience script (recommended)

Run the following command in your terminal:

bash <(curl -s https://app.formant.io/install-fctl.sh)

This will install fctl on your system and prompt you for admin credentials. This will also configure your ~/.ssh/config for SSH over Formant's peer-to-peer connection.

❗️

Installing via Apt and Homebrew is deprecated

The convenience script above will install on both Linux and Mac for you, as well as set up some environment settings to initialize and make SSH much easier. The following is included for completeness.

Linux via Apt (not recommended)

📘

The convenience script above already does all of this for you. These manual steps are provided only for completeness, or if you need to script the repo setup yourself.

Register Formant's signing key and apt repository, then install the package. These commands use the modern signed-by keyring method and work on every supported release, including Ubuntu 24.04 and Debian 12:

sudo apt-get update
sudo apt-get install -y gnupg ca-certificates curl apt-transport-https
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://keys.formant.io/formant.pub.gpg | sudo gpg --dearmor --yes -o /etc/apt/keyrings/formant.gpg
sudo chmod a+r /etc/apt/keyrings/formant.gpg
echo "deb [signed-by=/etc/apt/keyrings/formant.gpg] https://repo.formant.io/formant/debian $(. /etc/os-release; echo "$VERSION_CODENAME") main" | sudo tee /etc/apt/sources.list.d/formant.list
sudo apt-get update
sudo apt-get install -y fctl

❗️

Older instructions that use apt-key adv --fetch-keys ... and append the repo to /etc/apt/sources.list no longer work on Ubuntu 24.04 or Debian 12, where apt-key has been removed. Use the keyring steps above instead.

Mac via Homebrew (not recommended)

Set up the Formant tap and install via homebrew:

brew tap formantio/formant
brew install formantio/formant/fctl

Docker

First you'll need to initialize the fctl container with a volume mount on your local machine to store tokens (make sure to include a ' ' before the command so it doesn't save to your history):

 docker run -it -v <permanent_storage>:/root/.formant -e FORMANT_EMAIL=<admin_email> -e FORMANT_PASSWORD=<admin_password> formant/fctl init

Replace <permanent_storage> with a mount path on your local host system, and fill in your admin credentials.

Step 2: Verify installation (Mac/Linux)

Check that fctl is available by running the following command:

fctl -h

You should see:

fctl can be authenticated by either entering your Formant username and password, or by using a service account.

Learn more about service accounts here: https://docs.formant.io/docs/users

Usage:
  fctl [command]

Available Commands:
  completion   Generate completion scripts
  create       Create a resource
  describe     Describe a resource
  help         Help about any command
  init         Reinitialize fctl credentials
  list         List a resource
  port-forward Port forward to your device, used for SSH, SCP, and network tunneling.
  provision    Provision a resource
  query        Query ingested datapoints
  upload       upload media data for a device
  version      Get fctl version

Flags:
      --config-directory string   directory for fctl authentication tokens and configuration
  -h, --help                      display detailed help for fctl

Use "fctl [command] --help" for more information about a command

Step 3: Credential fctl (Mac/Linux)

fctl requires admin level privileges on your Formant account. We never store your email/password on disk so you initialize by running the following command:

fctl init

You will be prompted to log into Formant using the email address and password associated with your account.