Command Line Interface (CLI)

The ConfigCat Command Line Interface (CLI) allows you to interact with the Public Management API via the command line. It supports most functionality found on the ConfigCat Dashboard. You can manage ConfigCat resources like Feature Flags, Targeting / Percentage rules, Products, Configs, Environments, and more.

The ConfigCat Command Line Interface (CLI) has the ability to scan your source code for feature flag and setting usages and upload the found code references to ConfigCat.

configcat
  This is the Command Line Tool of ConfigCat.
  ConfigCat is a hosted feature flag service: https://configcat.com
  For more information, see the documentation here: https://configcat.com/docs/advanced/cli

Usage:
  configcat [command] [options]

Options:
  -v, --verbose           Print detailed execution information
  -ni, --non-interactive  Turn off progress rendering and interactive features
  --version               Show version information
  -?, -h, --help          Show help and usage information

Commands:
  setup                        Setup the CLI with Public Management API host and credentials
  ls                           List all Product, Config, and Environment IDs
  p, product                   Manage Products
  c, config                    Manage Configs
  webhook, wh                  Manage Webhooks
  e, environment               Manage Environments
  f, flag, s, setting          Manage Feature Flags & Settings
  f2, flag-v2, s2, setting-v2  Manage V2 Feature Flags & Settings
  seg, segment                 Manage Segments
  permission-group, pg         Manage Permission Groups
  m, member                    Manage Members
  t, tag                       Manage Tags
  k, sdk-key                   List SDK Keys
  scan <directory>             Scan files for Feature Flag & Setting usages
  config-json                  Config JSON-related utilities
  w, workspace                 Manage the CLI workspace. When set, the CLI's interactive mode
                               filters Product and Config selectors by the values set in the
                               workspace

Use "configcat [command] -?" for more information about a command.

Reference

See the command reference documentation for more information about each available command.

Getting Started

The following instructions will guide you through the first steps to start using this tool.

Installation

You can install the CLI on multiple operating systems using the following sources.

Homebrew (macOS / Linux)

Install the CLI with Homebrew from ConfigCat's tap by executing the following command:

brew tap configcat/tap
brew install configcat

Snap (Linux)

Install the CLI with Snapcraft by executing the following command:

sudo snap install configcat

Scoop (Windows)

Install the CLI with Scoop from ConfigCat's bucket by executing the following command:

scoop bucket add configcat https://github.com/configcat/scoop-configcat
scoop install configcat

Chocolatey (Windows)

Install the CLI with Chocolatey by executing the following command:

choco install configcat

.NET tool / NuGet.org

The CLI can be installed as a .NET tool via the .NET SDK.

dotnet tool install -g configcat-cli

After installing, you can execute the CLI using the configcat command:

configcat scan "/repository" --print --config-id <CONFIG-ID>

Docker

The CLI can be executed from a Docker image.

docker pull configcat/cli

An example of how to scan a repository for feature flag & setting references with the docker image.

docker run --rm \
    --env CONFIGCAT_API_HOST=<API-HOST> \
    --env CONFIGCAT_API_USER=<API-USER> \
    --env CONFIGCAT_API_PASS=<API-PASSWORD> \
    -v /path/to/repository:/repository \
  configcat/cli scan "/repository" --print --config-id <CONFIG-ID>

Install Script

On Unix platforms, you can install the CLI by executing an install script.

curl -fsSL "https://raw.githubusercontent.com/configcat/cli/main/scripts/install.sh" | bash

By default, the script downloads the OS specific artifact from the latest GitHub Release with curl and moves it into the /usr/local/bin directory.

It might happen that you don't have permissions to write into /usr/local/bin, then you should execute the install script with sudo.

curl -fsSL "https://raw.githubusercontent.com/configcat/cli/main/scripts/install.sh" | sudo bash

The script accepts the following input parameters:

Parameter	Description	Default value
-d, --dir	The directory where the CLI should be installed.	/usr/local/bin
-v, --version	The desired version to install.	latest
-a, --arch	The desired architecture to install.	x64

Available architecture values for Linux: x64, musl-x64, arm, arm64.

Available architecture values for macOS: x64, arm64.

Script usage examples:

Custom installation directory:

curl -fsSL "https://raw.githubusercontent.com/configcat/cli/main/scripts/install.sh" | bash -s -- -d=/path/to/install

Install a different version:

curl -fsSL "https://raw.githubusercontent.com/configcat/cli/main/scripts/install.sh" | bash -s -- -v=1.4.2

Install with custom architecture:

curl -fsSL "https://raw.githubusercontent.com/configcat/cli/main/scripts/install.sh" | bash -s -- -a=arm

Standalone executables

You can download the executables directly from GitHub Releases for your desired platform.

Setup

After a successful installation, the CLI must be set up with your ConfigCat Management API credentials.

You can do this by using the configcat setup command.

Environment Variables

Besides the setup command above, the CLI can read your credentials from the following environment variables.

Name	Description
CONFIGCAT_API_HOST	The Management API host. (default: api.configcat.com)
CONFIGCAT_API_USER	The Management API basic authentication username.
CONFIGCAT_API_PASS	The Management API basic authentication password.

caution

When any of these environment variables are set, the CLI will use them over the local values set by the configcat setup command.

Modes

The CLI supports both interactive and argument driven execution. When no arguments provided for a command and user input is enabled (stdout is not redirected), the CLI automatically activates interactive mode.

Interactive

With Arguments

The same operation with command arguments would look like this:

configcat flag create \
  --config-id <config-id> \
  --name "My awesome feature" \
  --hint "This is my awesome feature" \
  --key my_awesome_feature
  --type boolean \
  --tag-ids <tag-id-1> <tag-id-2> \

info

Each create command writes the newly created resource's ID to the standard output so you can save that for further operations.

Example:

#!/bin/bash

ORGANIZATION_ID="<your-organization-id>"
PRODUCT_ID=$(configcat product create -o $ORGANIZATION_ID -n "<product-name>")
CONFIG_ID=$(configcat config create -p $PRODUCT_ID -n "<config-name>")

info

You can change the output format of several command's result to JSON with the --json option, like: configcat flag ls --json. See more about these commands in the command reference documentation.

Scan & Upload Code References

The CLI has the ability to scan your source code for feature flag and setting usages and upload the found code references to ConfigCat. You can read more about this feature here.

Examples

Here are a few examples showing the true power of the CLI.

Create a Feature Flag

The following example shows how you can create a Feature Flag in a specific Config.

Value update

The following example shows how you can update the value of a Feature Flag in a specific Environment.

Add Targeting Rules

The following example shows how you can add Targeting Rules to a Feature Flag.

Add percentage rules

The following example shows how you can set percentage rules on a Feature Flag.