307 lines
11 KiB
Markdown
307 lines
11 KiB
Markdown
|
|
Use the `influx` CLI to interact with and manage your
|
|
InfluxDB {{% show-in "cloud,cloud-serverless" %}}Cloud{{% /show-in %}} instance.
|
|
Write and query data, generate InfluxDB templates, export data, and more.
|
|
|
|
{{% show-in "v2" %}}
|
|
|
|
{{% note %}}
|
|
The [`influx` CLI](/influxdb/version/reference/cli/influx) is packaged and versioned
|
|
separately from the InfluxDB server (`influxd`).
|
|
{{% /note %}}
|
|
|
|
{{% /show-in %}}
|
|
|
|
- [Install the influx CLI](#install-the-influx-cli)
|
|
- [Set up the influx CLI](#set-up-the-influx-cli)
|
|
- [Use influx CLI commands](#use-influx-cli-commands)
|
|
|
|
## Install the influx CLI
|
|
|
|
{{< tabs-wrapper >}}
|
|
{{% tabs %}}
|
|
[macOS](#)
|
|
[Linux](#)
|
|
[Windows](#)
|
|
{{% /tabs %}}
|
|
|
|
<!-------------------------------- BEGIN macOS -------------------------------->
|
|
{{% tab-content %}}
|
|
|
|
Do one of the following:
|
|
|
|
- [Use Homebrew](#use-homebrew)
|
|
- [Manually download and install](#manually-download-and-install)
|
|
|
|
### Use Homebrew
|
|
|
|
<!--pytest.mark.skip-->
|
|
|
|
```sh
|
|
brew install influxdb-cli
|
|
```
|
|
|
|
{{% show-in "v2" %}}
|
|
|
|
{{% note %}}
|
|
If you used Homebrew to install **InfluxDB {{< current-version >}}**, the `influxdb-cli`
|
|
formula was downloaded as a dependency and should already be installed.
|
|
If installed, `influxdb-cli` will appear in the output of the following command:
|
|
|
|
<!--pytest.mark.skip-->
|
|
|
|
```sh
|
|
brew list | grep influxdb-cli
|
|
```
|
|
{{% /note %}}
|
|
|
|
{{% /show-in %}}
|
|
|
|
### Manually download and install
|
|
|
|
1. Download the `influx` CLI package [from your browser](#download-from-your-browser)
|
|
or [from the command line](#download-from-the-command-line).
|
|
|
|
#### Download from your browser
|
|
|
|
<a class="btn download" href="https://dl.influxdata.com/influxdb/releases/influxdb2-client-{{< latest-patch cli=true >}}-darwin-amd64.tar.gz" download>influx CLI v{{< latest-patch cli=true >}} (macOS)</a>
|
|
|
|
#### Download from the command line
|
|
|
|
```sh
|
|
curl -LO https://dl.influxdata.com/influxdb/releases/influxdb2-client-{{< latest-patch cli=true >}}-darwin-amd64.tar.gz \
|
|
--output-dir ~/Downloads
|
|
```
|
|
|
|
2. Unpackage the downloaded binary.
|
|
|
|
Do one of the following:
|
|
|
|
- In **Finder**, double-click the downloaded package file.
|
|
- In your terminal (for example, **Terminal** or **[iTerm2](https://www.iterm2.com/)**) use `tar` to extract the package--for example, enter the following command to extract it into `~/Downloads`:
|
|
|
|
```sh
|
|
tar zxvf ~/Downloads/influxdb2-client-{{< latest-patch cli=true >}}-darwin-amd64.tar.gz \
|
|
--directory ~/Downloads
|
|
```
|
|
|
|
3. Optional: Place the `influx` binary in your `$PATH`--for example, copy the binary to `/usr/local/bin`:
|
|
|
|
```sh
|
|
sudo cp ~/Downloads/influx /usr/local/bin/
|
|
```
|
|
|
|
With the `influx` binary in your `$PATH` (`/usr/local/bin`), you can enter `influx` in your terminal to run the CLI.
|
|
|
|
If you do not move the `influx` binary into your `$PATH`, enter the path to the binary to run the CLI--for example:
|
|
|
|
<!--pytest.mark.xfail-->
|
|
|
|
```sh
|
|
~/Downloads/influx
|
|
```
|
|
|
|
4. (macOS Catalina and newer) Authorize the `influx` binary.
|
|
|
|
macOS requires downloaded binaries to be signed by registered Apple developers.
|
|
When you first attempt to run `influx`, macOS prevents it from running.
|
|
To authorize the `influx` binary:
|
|
|
|
**Allow the binary on macOS Ventura**
|
|
|
|
1. Follow the preceding instructions to attempt to start `influx`.
|
|
2. Open **System Settings** and click **Privacy & Security**.
|
|
3. Under the **Security** heading, there is a message about "influxd" being blocked, click **Allow Anyway**.
|
|
5. When prompted, enter your password to allow the setting.
|
|
6. Close **System Settings**.
|
|
7. Attempt to start `influx`.
|
|
8. A prompt appears with the message _"macOS cannot verify the developer of "influx"...""_.
|
|
Click **Open**.
|
|
|
|
**Allow the binary on macOS Catalina**
|
|
|
|
1. Attempt to run an `influx` command.
|
|
2. Open **System Preferences** and click **Security & Privacy**.
|
|
3. Under the **General** tab, there is a message about `influx` being blocked.
|
|
Click **Open Anyway**.
|
|
|
|
{{% /tab-content %}}
|
|
<!--------------------------------- END macOS --------------------------------->
|
|
|
|
<!-------------------------------- BEGIN Linux -------------------------------->
|
|
{{% tab-content %}}
|
|
|
|
1. Download the `influx` CLI package [from your browser](#download-from-your-browser)
|
|
or [from the command line](#download-from-the-command-line).
|
|
|
|
#### Download from your browser
|
|
|
|
<a class="btn download" href="https://dl.influxdata.com/influxdb/releases/influxdb2-client-{{< latest-patch cli=true >}}-linux-amd64.tar.gz" download >influx CLI v{{< latest-patch cli=true >}} (amd64)</a>
|
|
<a class="btn download" href="https://dl.influxdata.com/influxdb/releases/influxdb2-client-{{< latest-patch cli=true >}}-linux-arm64.tar.gz" download >influx CLI v{{< latest-patch cli=true >}} (arm)</a>
|
|
|
|
#### Download from the command line
|
|
|
|
```sh
|
|
# amd64
|
|
wget https://dl.influxdata.com/influxdb/releases/influxdb2-client-{{< latest-patch cli=true >}}-linux-amd64.tar.gz
|
|
```
|
|
|
|
```sh
|
|
# arm
|
|
wget https://dl.influxdata.com/influxdb/releases/influxdb2-client-{{< latest-patch cli=true >}}-linux-arm64.tar.gz
|
|
```
|
|
|
|
2. Unpackage the downloaded binary.
|
|
|
|
_**Note:** The following commands are examples. Adjust the filenames, paths, and utilities if necessary._
|
|
|
|
```sh
|
|
# amd64
|
|
tar xvzf ./influxdb2-client-{{< latest-patch cli=true >}}-linux-amd64.tar.gz
|
|
```
|
|
|
|
```sh
|
|
# arm
|
|
tar xvzf ./influxdb2-client-{{< latest-patch cli=true >}}-linux-arm64.tar.gz
|
|
```
|
|
|
|
3. Optional: Place the unpackaged `influx` executable in your system `$PATH`.
|
|
|
|
```sh
|
|
# amd64
|
|
sudo cp ./influx /usr/local/bin/
|
|
```
|
|
|
|
```sh
|
|
# arm
|
|
sudo cp ./influx /usr/local/bin/
|
|
```
|
|
|
|
If you do not move the `influxd` binary into your `$PATH`, enter the path to the binary to start the server--for example:
|
|
|
|
<!--pytest.mark.xfail-->
|
|
|
|
```sh
|
|
./influx
|
|
```
|
|
|
|
{{% /tab-content %}}
|
|
<!--------------------------------- END Linux --------------------------------->
|
|
|
|
<!-------------------------------- BEGIN Windows -------------------------------->
|
|
{{% tab-content %}}
|
|
|
|
{{% note %}}
|
|
We recommend running `influx` CLI commands in Powershell.
|
|
Command Prompt is not fully compatible.
|
|
{{% /note %}}
|
|
|
|
1. Download the `influx` CLI package.
|
|
|
|
<a class="btn download" href="https://dl.influxdata.com/influxdb/releases/influxdb2-client-{{< latest-patch cli=true >}}-windows-amd64.zip" download>influx CLI v{{< latest-patch cli=true >}} (Windows)</a>
|
|
|
|
2. Expand the downloaded archive.
|
|
|
|
Expand the downloaded archive into `C:\Program Files\InfluxData\` and rename it if desired.
|
|
|
|
<!--pytest.mark.skip-->
|
|
|
|
```powershell
|
|
> Expand-Archive .\influxdb2-client-{{< latest-patch cli=true >}}-windows-amd64.zip -DestinationPath 'C:\Program Files\InfluxData\'
|
|
> mv 'C:\Program Files\InfluxData\influxdb2-client-{{< latest-patch cli=true >}}-windows-amd64' 'C:\Program Files\InfluxData\influx'
|
|
```
|
|
|
|
3. Grant network access to the `influx` CLI.
|
|
|
|
When using the `influx` CLI for the first time, **Windows Defender** displays
|
|
the following message:
|
|
|
|
> Windows Defender Firewall has blocked some features of this app.
|
|
|
|
To grant the `influx` CLI the required access, do the following:
|
|
|
|
1. Select **Private networks, such as my home or work network**.
|
|
2. Click **Allow access**.
|
|
|
|
{{% /tab-content %}}
|
|
<!--------------------------------- END Windows --------------------------------->
|
|
{{< /tabs-wrapper >}}
|
|
|
|
## Set up the influx CLI
|
|
|
|
- [Provide required authentication credentials](#provide-required-authentication-credentials)
|
|
- [Enable shell completion (Optional)](#enable-shell-completion-optional)
|
|
|
|
### Provide required authentication credentials
|
|
To avoid having to pass your InfluxDB **host**, **API token**, and **organization**
|
|
with each command, store them in an `influx` CLI configuration (config).
|
|
`influx` commands that require these credentials automatically retrieve these
|
|
credentials from the active config.
|
|
|
|
Use the [`influx config create` command](/influxdb/version/reference/cli/influx/config/create/)
|
|
to create an `influx` CLI config and set it as active:
|
|
|
|
|
|
{{% code-placeholders "API_TOKEN|ORG|http://localhost:8086|CONFIG_NAME" %}}
|
|
```sh
|
|
influx config create --config-name CONFIG_NAME \
|
|
--host-url http://localhost:8086 \
|
|
--org ORG \
|
|
--token API_TOKEN \
|
|
--active
|
|
```
|
|
{{% /code-placeholders %}}
|
|
|
|
Replace the following:
|
|
|
|
- {{% code-placeholder-key %}}`CONFIG_NAME`{{% /code-placeholder-key %}}: Connection configuration name.
|
|
- {{% code-placeholder-key %}}`ORG_NAME`{{% /code-placeholder-key %}}: your InfluxDB [organization](/influxdb/version/admin/organizations/).
|
|
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: your [API token](/influxdb/version/admin/tokens/).
|
|
|
|
For more information about managing CLI configurations, see the
|
|
[`influx config` documentation](/influxdb/version/reference/cli/influx/config/).
|
|
|
|
For instructions on how to create API tokens, see [Create a token](/influxdb/version/admin/tokens/create-token/).
|
|
|
|
{{% show-in "v2" %}}
|
|
|
|
#### Authenticate with a username and password
|
|
|
|
The **`influx` CLI 2.4.0+** lets you create connection configurations
|
|
that authenticate with **InfluxDB OSS 2.4+** using the username and
|
|
password combination that you would use to log into the InfluxDB user interface (UI).
|
|
The CLI retrieves a session cookie and stores it, unencrypted, in your
|
|
[configs path](/influxdb/version/reference/internals/file-system-layout/#configs-path).
|
|
|
|
Use the `--username-password`, `-p` option to provide your username and password
|
|
using the `<username>:<password>` syntax.
|
|
If no password is provided, the CLI prompts for a password after each
|
|
command that requires authentication.
|
|
|
|
{{% code-placeholders "API_TOKEN|ORG|http://localhost:8086|CONFIG_NAME|USERNAME|PASSWORD" %}}
|
|
```sh
|
|
influx config create \
|
|
-n CONFIG_NAME \
|
|
-u http://localhost:8086 \
|
|
-p USERNAME:PASSWORD \
|
|
-o ORG
|
|
```
|
|
{{% /code-placeholders %}}
|
|
|
|
Replace the following:
|
|
|
|
- {{% code-placeholder-key %}}`CONFIG_NAME`{{% /code-placeholder-key %}}: Connection configuration name.
|
|
- {{% code-placeholder-key %}}`ORG`{{% /code-placeholder-key %}}: [your organization name](/influxdb/version/admin/organizations/).
|
|
- {{% code-placeholder-key %}}`USERNAME:PASSWORD`{{% /code-placeholder-key %}}: your UI username and password combination.
|
|
|
|
{{% /show-in %}}
|
|
|
|
### Enable shell completion (Optional)
|
|
|
|
To install `influx` shell completion scripts, see
|
|
[`influx completion`](/influxdb/version/reference/cli/influx/completion/#install-completion-scripts).
|
|
|
|
## Use influx CLI commands
|
|
_For information about `influx` CLI commands, see the
|
|
[`influx` CLI reference documentation](/influxdb/version/reference/cli/influx/)._
|