--- title: influxctl description: The influxctl command line interface (CLI) writes to, queries, and performs administrative tasks in an InfluxDB cluster. url: https://docs.influxdata.com/influxdb3/clustered/reference/cli/influxctl/ estimated_tokens: 7357 product: InfluxDB Clustered version: clustered --- # influxctl The `influxctl` command line interface (CLI) writes to, queries, and performs administrative tasks in an InfluxDB cluster. - [Usage](#usage) - [Commands](#commands) - [Global flags](#global-flags) - [Download and install influxctl](#download-and-install-influxctl) - [Configure connection profiles](#configure-connection-profiles) - [Authentication](#authentication) ## Usage ```sh influxctl [global-flags] [command] ``` ## Commands | Command | Description | | --- | --- | | auth | Log in to or log out of InfluxDB 3 | | cluster | List InfluxDB 3 cluster information | | database | Manage InfluxDB 3 databases | | help | Output influxctl help information | | management | Manage InfluxDB 3 management tokens | | query | Query data from InfluxDB 3 | | token | Manage InfluxDB 3 database tokens | | user | Manage InfluxDB 3 cluster users | | version | Output the current influxctl version | | write | Write line protocol to InfluxDB 3 | ## 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:** Use one of the following options to download and install `influxctl` on macOS: - [Use Homebrew to install influxctl](#use-homebrew-to-install-influxctl) - [Manually download and install the influxctl binary](#manually-download-and-install-the-influxctl-binary) ### Use Homebrew to install influxctl 1. Use `brew tap` to add the `influxdata/tap` repository to the list of formulae that Homebrew tracks, updates, and installs from: ```sh brew tap influxdata/tap ``` 2. Install the `influxctl` package: ```sh brew install influxctl ``` ### Manually download and install the influxctl binary 1. **Download the `influxctl` CLI package** appropriate for your CPU type. Download the package from your browser or command line. ##### Browser [influxctl CLI v2.12.0 (x86\_64)](https://dl.influxdata.com/influxctl/releases/influxctl-v2.12.0-darwin-x86_64.zip) [influxctl CLI v2.12.0 (arm64)](https://dl.influxdata.com/influxctl/releases/influxctl-v2.12.0-darwin-arm64.zip) ##### Command line ```sh # x86_64 curl -Oo ~/Downloads/ https://dl.influxdata.com/influxctl/releases/influxctl-v2.12.0-darwin-x86_64.zip # arm64 curl -Oo ~/Downloads/ https://dl.influxdata.com/influxctl/releases/influxctl-v2.12.0-darwin-arm64.zip ``` 2. **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: ```sh # x86_64 unzip ~/Downloads/influxctl-v2.12.0-darwin-x86_64.zip # arm64 unzip ~/Downloads/influxctl-v2.12.0-darwin-arm64.zip ``` 3. ***(Optional)* Place the binary in your `$PATH`**. ```sh # x86_64 sudo cp ~/Downloads/influxctl-v2.12.0-darwin-x86_64/influxctl /usr/local/bin/ # arm64 sudo cp ~/Downloads/influxctl-v2.12.0-darwin-arm64/influxctl /usr/local/bin/ ``` 4. [Create a connection profile](#configure-connection-profiles) that stores connection credentials for your cluster. **Linux:** To download the Linux `influxctl` package, do one of the following: - [Use a package manager](#use-a-package-manager) - [Manually download the package](#manually-download-the-package) ### Use a package manager **Ubuntu & Debian (.deb):** ```sh # influxdata-archive.key GPG fingerprint: # Primary key fingerprint: 24C9 75CB A61A 024E E1B6 3178 7C3D 5715 9FC2 F927 # Subkey fingerprint: 9D53 9D90 D332 8DC7 D6C8 D3B9 D8FF 8E1F 7DF8 B07E wget -q https://repos.influxdata.com/influxdata-archive.key gpg --show-keys --with-fingerprint --with-colons ./influxdata-archive.key 2>&1 | grep -q '^fpr:\+24C975CBA61A024EE1B631787C3D57159FC2F927:$' && cat influxdata-archive.key | gpg --dearmor | sudo tee /etc/apt/keyrings/influxdata-archive.gpg > /dev/null echo 'deb [signed-by=/etc/apt/keyrings/influxdata-archive.gpg] https://repos.influxdata.com/debian stable main' | sudo tee /etc/apt/sources.list.d/influxdata.list ``` **Red Hat & CentOS (.rpm):** ```sh # influxdata-archive.key GPG fingerprint: # Primary key fingerprint: 24C9 75CB A61A 024E E1B6 3178 7C3D 5715 9FC2 F927 # Subkey fingerprint: 9D53 9D90 D332 8DC7 D6C8 D3B9 D8FF 8E1F 7DF8 B07E cat < ### Manually download the package 1. **Download the `influxctl` CLI package** appropriate for your CPU type. Download the package from your browser or command line. ##### Browser [influxctl CLI v2.12.0 (x86\_64)](https://dl.influxdata.com/influxctl/releases/influxctl-v2.12.0-linux-x86_64.tar.gz) [influxctl CLI v2.12.0 (arm64)](https://dl.influxdata.com/influxctl/releases/influxctl-v2.12.0-linux-arm64.tar.gz) ##### Command line ```sh # amd64 curl -O https://dl.influxdata.com/influxctl/releases/influxctl-v2.12.0-linux-x86_64.tar.gz # arm64 curl -O https://dl.influxdata.com/influxctl/releases/influxctl-v2.12.0-linux-arm64.tar.gz ``` 2. **Unpackage the downloaded package**. ```sh # amd64 tar zxvf influxctl-v2.12.0-linux-x86_64.tar.gz # arm64 tar zxvf influxctl-v2.12.0-linux-arm64.tar.gz ``` 3. ***(Optional)* Place the binary in your `$PATH`**. ```sh # amd64 sudo cp influxctl-v2.12.0-darwin-x86_64/influxctl /usr/local/bin/ # arm64 sudo cp influxctl-v2.12.0-darwin-arm64/influxctl /usr/local/bin/ ``` 4. [Create a connection profile](#configure-connection-profiles) that stores connection credentials for your cluster. **Windows:** 1. **Download the `influxctl` CLI package**. [influxctl CLI v2.12.0 (x86\_64)](https://dl.influxdata.com/influxctl/releases/influxctl-v2.12.0-windows-x86_64.zip) 2. **Expand the downloaded archive**. Expand the downloaded archive into C:\\Program Files\\InfluxData\\ and rename it if desired. ```powershell Expand-Archive .\influxctl-v2.12.0-windows-x86_64.zip ` -DestinationPath 'C:\Program Files\InfluxData\' mv 'C:\Program Files\InfluxData\influxctl-v2.12.0-windows-x86_64' ` 'C:\Program Files\InfluxData\influxctl' ``` 3. **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**. 4. [Create a connection profile](#configure-connection-profiles) 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](#default-connection-profile-store-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-configtoml) View sample `config.toml` ```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 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](https://auth0.com/) 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): ```sh 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: ```sh GTK_MODULES= influxctl ... ``` [cli](/influxdb3/clustered/tags/cli/)