influxctl

The influxctl command line interface (CLI) writes to, queries, and performs administrative tasks in an InfluxDB cluster.

Usage
Commands
Global flags
Download and install influxctl
Configure connection profiles
Authentication

Usage

influxctl [global-flags] [command]

Commands

Command	Description
auth	Log in to or log out of InfluxDB v3
cluster	List InfluxDB v3 cluster information
database	Manage InfluxDB v3 databases
help	Output `influxctl` help information
management	Manage InfluxDB v3 management tokens
query	Query data from InfluxDB v3
token	Manage InfluxDB v3 database tokens
user	Manage InfluxDB v3 cluster users
version	Output the current `influxctl` version
write	Write line protocol to InfluxDB v3

Global flags

Flag		Description
	`--debug`	Enable debug logging
	`--account`	Override account ID value in configuration file
	`--cluster`	Override cluster ID value in configuration file
	`--config`	Path to configuration file to use
	`--profile`	Specify a connection profile to use (default is `default`)
	`--timeout`	Specify a timeout duration for API calls (default is `1m0s`)
	`--trace`	Enable more verbose debug logging
`-h`	`--help`	Show help

Download and install influxctl

macOS Linux Windows

Use one of the following options to download and install influxctl on macOS:

Use Homebrew to install influxctl
Manually download and install the influxctl binary

Use Homebrew to install influxctl

Use brew tap to add the influxdata/tap repository to the list of formulae that Homebrew tracks, updates, and installs from:
```
brew tap influxdata/tap
```
Install the influxctl package:
```
brew install influxctl
```

Manually download and install the influxctl binary

Download the influxctl CLI package appropriate for your CPU type. Download the package from your browser or command line.

Browser

influxctl CLI v2.9.8 (x86_64) influxctl CLI v2.9.8 (arm64)

Command line

# x86_64
curl -Oo ~/Downloads/ https://dl.influxdata.com/influxctl/releases/influxctl-v2.9.8-darwin-x86_64.zip

# arm64
curl -Oo ~/Downloads/ https://dl.influxdata.com/influxctl/releases/influxctl-v2.9.8-darwin-arm64.zip

Unpackage the downloaded package.
Do one of the following:
- In Finder, double-click the downloaded package file.
- From the command line, run the following command appropriate for your CPU type:
```
# x86_64
unzip ~/Downloads/influxctl-v2.9.8-darwin-x86_64.zip

# arm64
unzip ~/Downloads/influxctl-v2.9.8-darwin-arm64.zip
```

(Optional) Place the binary in your $PATH.

# x86_64
sudo cp ~/Downloads/influxctl-v2.9.8-darwin-x86_64/influxctl /usr/local/bin/

# arm64
sudo cp ~/Downloads/influxctl-v2.9.8-darwin-arm64/influxctl /usr/local/bin/

Create a connection profile that stores connection credentials for your cluster.

To download the Linux influxctl package, do one of the following:

Use a package manager
Manually download the package

Use a package manager

Ubuntu & Debian (.deb) Red Hat & CentOS (.rpm)

# influxdata-archive_compat.key GPG fingerprint:
#     9D53 9D90 D332 8DC7 D6C8 D3B9 D8FF 8E1F 7DF8 B07E
wget -q https://repos.influxdata.com/influxdata-archive_compat.key
echo '393e8779c89ac8d958f81f942f9ad7fb82a25e133faddaf92e15b16e6ac9ce4c influxdata-archive_compat.key' | sha256sum -c && cat influxdata-archive_compat.key | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/influxdata-archive_compat.gpg > /dev/null
echo 'deb [signed-by=/etc/apt/trusted.gpg.d/influxdata-archive_compat.gpg] https://repos.influxdata.com/debian stable main' | sudo tee /etc/apt/sources.list.d/influxdata.list

sudo apt-get update && sudo apt-get install influxctl

# influxdata-archive_compat.key GPG fingerprint:
#     9D53 9D90 D332 8DC7 D6C8 D3B9 D8FF 8E1F 7DF8 B07E
cat <<EOF | sudo tee /etc/yum.repos.d/influxdata.repo
[influxdata]
name = InfluxData Repository - Stable
baseurl = https://repos.influxdata.com/stable/\$basearch/main
enabled = 1
gpgcheck = 1
gpgkey = https://repos.influxdata.com/influxdata-archive_compat.key
EOF

sudo yum install influxctl

Manually download the package

Download the influxctl CLI package appropriate for your CPU type. Download the package from your browser or command line.

Browser

influxctl CLI v2.9.8 (x86_64) influxctl CLI v2.9.8 (arm64)

Command line

# amd64
curl -O https://dl.influxdata.com/influxctl/releases/influxctl-v2.9.8-linux-x86_64.tar.gz

# arm64
curl -O https://dl.influxdata.com/influxctl/releases/influxctl-v2.9.8-linux-arm64.tar.gz

Unpackage the downloaded package.

# amd64
tar zxvf influxctl-v2.9.8-linux-x86_64.tar.gz

# arm64
tar zxvf influxctl-v2.9.8-linux-arm64.tar.gz

(Optional) Place the binary in your $PATH.

# amd64
sudo cp influxctl-v2.9.8-darwin-x86_64/influxctl /usr/local/bin/

# arm64
sudo cp influxctl-v2.9.8-darwin-arm64/influxctl /usr/local/bin/

Create a connection profile that stores connection credentials for your cluster.

Download the influxctl CLI package.
influxctl CLI v2.9.8 (x86_64)

Expand the downloaded archive.

Expand the downloaded archive into C:\Program Files\InfluxData\ and rename it if desired.

Expand-Archive .\influxctl-v2.9.8-windows-x86_64.zip `
-DestinationPath 'C:\Program Files\InfluxData\'
mv 'C:\Program Files\InfluxData\influxctl-v2.9.8-windows-x86_64' `
'C:\Program Files\InfluxData\influxctl'

Grant network access to the influxctl CLI.
When using the influxctl CLI for the first time, Windows Defender displays the following message:
Windows Defender Firewall has blocked some features of this app.
To grant the influxctl CLI the required access, do the following:
Select Private networks, such as my home or work network. Click Allow access.
Create a connection profile that stores connection credentials for your cluster.

Configure connection profiles

To connect with your InfluxDB cluster, influxctl needs the following credentials:

InfluxDB cluster host
InfluxDB cluster port
OAuth provider credentials (what credentials are needed depend on your OAuth provider)

Create a configuration file

Create a config.toml that includes the necessary credentials. If stored at the default location for your operating system, influxctl automatically detects and uses the connection profile configurations. If stored at a non-default location, include the --config flag with each influxctl command and provide the path to your profile configuration file.

View sample config.toml

## influxctl - example configuration

[[profile]]
    ## Profile name
    ## Users can define multiple profile sections and reference them via the
    ## `--profile {name}` global option. By default, the profile named
    ## "default" is loaded and used.
    name = "PROFILE_NAME
"

    ## Product type
    ## Choose from "clustered" or "dedicated"
    product = "clustered"

    ## Host and port
    ## InfluxDB hostname/IP address and port.
    ## Required for InfluxDB Clustered.
    host = "cluster-host.com"
    port = "INFLUXDB_PORT
"

    ## Database and token
    ## Used for the query and write subcommands
    # database = ""
    # token = ""

    ### Dedicated Specific Options ###
    ## Account ID and cluster ID
    # account_id = ""
    # cluster_id = ""

    ## Custom client-side TLS certs
    ## By default, the system certificates are used. If a custom certificate
    ## for connecting to InfluxDB is required, define it below.
    # [profile.tls]
        ## When true, `insecure` influxctl configures HTTPS clients to not
        ## verify server certificates. Use this if you are connecting to a
        ## TLS endpoint with invalid (expired, self-signed, etc) server
        ## certificates.
        # insecure = false
        ## When true, `disable` causes influxctl to use HTTP rather than HTTPS
        ## client. Use this if you don't have an ingress controller configured
        ## to terminate TLS connections. InfluxDB 3.0 components themselves do
        ## not terminate TLS.
        # disable = false
        # cert = ""
        # key = ""
        # ca = ""

    ## OAuth2 client authorization settings
    [profile.auth.oauth2]
        client_id = "OAUTH_CLIENT_ID
"
        scopes = [""]
        parameters = { audience = "" }
        token_url = "OAUTH_TOKEN_URL
"
        device_url = "OAUTH_DEVICE_URL
"

Replace the following values in the sample:

PROFILE_NAME: Use default for your default connection profile or a custom name for a non-default profile.
INFLUXDB_PORT: InfluxDB cluster port
OAUTH_CLIENT_ID: OAuth client ID
OAUTH_CLIENT_ID: OAuth provider token URL (for example: https://indentityprovider/oauth2/v2/token)
OAUTH_CLIENT_ID: OAuth provider device URL (for example: https://indentityprovider/oauth2/v2/auth/device)

Default connection profile store location

The influxctl CLI checks for connection profiles in a config.toml file at a default location based on your operating system:

Operating system	Default profile configuration file path
Linux	`~/.config/influxctl/config.toml`
macOS	`~/Library/Application Support/influxctl/config.toml`
Windows	`%APPDATA%\influxctl\config.toml`

Authentication

The influxctl CLI uses Auth0 to authenticate access to your InfluxDB cluster. When you issue an influxctl command, the CLI checks for an active Auth0 token. If none exists, you are directed to login to Auth0 via a browser using credentials you should have created when setting up your InfluxDB Cloud Dedicated cluster. Auth0 issues a short-lived (1 hour) token that authenticates access to your InfluxDB cluster.

Troubleshoot

Not loading module “atk-bridge”: When authenticating, some Linux systems might report the following warning in the terminal (on stderr):
```
Not loading module "atk-bridge": The functionality is provided by GTK natively. Please try to not load it.
```
To silence the warning when running influxctl commands, unset the GTK_MODULES environment variable (or remove gail:atk-bridge from its value)–for example:
```
GTK_MODULES= influxctl ...
```

cli

Was this page helpful?

Thank you for your feedback!

Support and feedback

Thank you for being part of our community! We welcome and encourage your feedback and bug reports for InfluxDB and this documentation. To find support, use the following resources:

Customers with an annual or support contract can contact InfluxData Support.

Edit this page Submit docs issue Submit InfluxDB issue

influxctl

Usage

Commands

Global flags

Download and install influxctl

Use Homebrew to install influxctl

Manually download and install the influxctl binary

Browser

Command line

Use a package manager

Manually download the package

Browser

Command line

Configure connection profiles

Create a configuration file

Default connection profile store location

Authentication

Troubleshoot

Support and feedback

The future of Flux

InfluxDB v3 enhancements and InfluxDB Clustered is now generally available

InfluxDB v3 performance and features

InfluxDB Clustered general availability

influxctl

Usage

Commands

Global flags

Download and install influxctl

Use Homebrew to install influxctl

Manually download and install the influxctl binary

Browser

Command line

Use a package manager

Manually download the package

Browser

Command line

Configure connection profiles

Create a configuration file

Default connection profile store location

Authentication

Troubleshoot

Support and feedback

What is your InfluxDB cluster URL?

Enter cluster URL

Thank you for your feedback!

The future of Flux

InfluxDB v3 enhancements and InfluxDB Clustered is now generally available

InfluxDB v3 performance and features

InfluxDB Clustered general availability