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

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)

You can follow the same repo setup steps for the agent found here.

Next, update and install the fctl debian package:

sudo apt update
sudo apt install fctl

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.

👋

If you notice an issue with this page or need help, please reach out to us! Use the 'Did this page help you?' buttons below, or get in contact with our Customer Success team via the Intercom messenger in the bottom-right corner of this page, or at support@formant.io.