---
updatedAt: 2026-06-09T05:00:40.000Z
agentTools:
  projectIndex: https://docs.formant.io/llms.txt
---

# fctl overview and installation

`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:

| OS     | Versions                                                                    |
| ------ | --------------------------------------------------------------------------- |
| Ubuntu | 16.04 (xenial), 18.04 (bionic), 20.04 (focal), 22.04 (jammy), 24.04 (noble) |
| Debian | 10 (buster), 11 (bullseye), 12 (bookworm)                                   |
| macOS  | Intel, and Apple silicon via Rosetta                                        |

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:

```Text Terminal
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:

```Text Terminal
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:

```Text Terminal
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](https://support.apple.com/en-us/HT211861).

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

```Text Terminal
softwareupdate --install-rosetta
```

# Step 1: Install `fctl`

## Convenience script (recommended)

Run the following command in your terminal:

```shell 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:

```Terminal
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:

```bash Terminal
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):

```bash Terminal
 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:

```bash Terminal
fctl -h
```

You should see:

```Text Terminal
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:

```bash Terminal
fctl init
```

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

<Callout icon="👋" theme="default">
  ### 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](mailto:support@formant.io).
</Callout>