InfluxDB CLI

InfluxDB CLI cheatsheet — query data with Flux, write metrics, manage buckets and tokens. influx query, influx write, influx bucket create. Full InfluxDB CLI reference.

7 min read

What it is

The InfluxDB CLI is a command-line interface for interacting with InfluxDB, allowing you to manage your database, query data, and perform administrative tasks.

Installation

Linux

# Download the latest release (replace with the actual latest version)
wget https://dl.influxdata.com/influxdb/releases/influxdb-client-v2.12.1_linux_amd64.tar.gz

# Extract the archive
tar -zxvf influxdb-client-v2.12.1_linux_amd64.tar.gz

# Move the binary to your PATH
sudo mv influxdb-client-v2.12.1-linux_amd64/influx /usr/local/bin/

# Clean up
rm -rf influxdb-client-v2.12.1_linux_amd64.tar.gz influxdb-client-v2.12.1-linux_amd64

macOS

# Download the latest release (replace with the actual latest version)
curl -O https://dl.influxdata.com/influxdb/releases/influxdb-client-v2.12.1_darwin_amd64.tar.gz

# Extract the archive
tar -zxvf influxdb-client-v2.12.1_darwin_amd64.tar.gz

# Move the binary to your PATH
sudo mv influxdb-client-v2.12.1-darwin_amd64/influx /usr/local/bin/

# Clean up
rm -rf influxdb-client-v2.12.1_darwin_amd64.tar.gz influxdb-client-v2.12.1-darwin_amd64

Windows

Download the appropriate .tar.gz file from the InfluxDB releases page and extract the influx.exe binary. You may want to add its directory to your system’s PATH environment variable.

Core Concepts

Organizations: A top-level container for users, buckets, dashboards, and tasks.
Buckets: Where time-series data is stored. A bucket belongs to an organization.
Tokens: Used for authentication when interacting with InfluxDB.
Flux: The query language used by InfluxDB 2.x and later.

Commands / Usage

Connecting and Authentication

Connect to InfluxDB:
```
influx --host localhost --port 8086 --token YOUR_API_TOKEN --org YOUR_ORG_ID
```
Connect to a specific InfluxDB instance using host, port, API token, and organization ID.
Set default connection details (environment variables):
```
export INFLUX_HOST="http://localhost:8086"
export INFLUX_TOKEN="YOUR_API_TOKEN"
export INFLUX_ORG="YOUR_ORG_ID"
```
Set environment variables for host, token, and organization to avoid specifying them on every command.

Managing Organizations

List all organizations:
```
influx org list
```
Display a list of all organizations.
Create a new organization:
```
influx org create --name "new-org-name"
```
Create a new organization with the specified name.
Update an organization:
```
influx org update --id "your-org-id" --name "updated-org-name"
```
Update the name of an existing organization.
Delete an organization:
```
influx org delete --id "your-org-id"
```
Delete an organization by its ID. This is irreversible.

Managing Buckets

List all buckets:
```
influx bucket list
```
Display a list of all buckets in the current organization.
List buckets in a specific organization:
```
influx bucket list --org "your-org-id"
```
Display a list of buckets in a specified organization.
Create a new bucket:
```
influx bucket create --name "my-new-bucket" --retention "1h" --description "Bucket for my metrics"
```
Create a new bucket with a name, retention period (e.g., 1h, 7d, 30d), and an optional description.

Update a bucket:

influx bucket update --id "your-bucket-id" --retention "24h" --description "Updated retention"

Update the retention period or description of an existing bucket.

Delete a bucket:
```
influx bucket delete --id "your-bucket-id"
```
Delete a bucket by its ID. This is irreversible.

Managing Tokens

List all tokens:
```
influx token list
```
Display a list of all API tokens in the current organization.
List tokens for a specific user:
```
influx token list --user "user-id-or-name"
```
Display tokens associated with a particular user.
Create a new token:
```
influx token create --description "my-app-token" --read-bucket "your-bucket-id" --write-bucket "your-bucket-id" --org "your-org-id"
```
Create a new token with a description, read/write permissions for specific buckets, and associated with an organization.
Get token details:
```
influx token get --id "your-token-id"
```
Retrieve details about a specific token.
Delete a token:
```
influx token delete --id "your-token-id"
```
Delete an API token by its ID. This is irreversible.

Querying Data (Flux)

Run a Flux query:

influx query 'from(bucket: "my-bucket") |> range(start: -5m) |> filter(fn: (r) => r._measurement == "cpu" and r.host == "server-01") |> limit(n: 10)'

Execute a Flux query and display the results.

Run a Flux query from a file:
```
influx query --file ./my_query.flux
```
Execute a Flux query defined in a file.

Specify organization and bucket in query:

influx query --org "your-org-id" --bucket "my-bucket" 'range(start: -1h) |> filter(fn: (r) => r["_measurement"] == "mem") |> limit(n: 5)'

Specify the organization and bucket directly in the query command, overriding defaults.

Writing Data

Write data using the line protocol (from stdin):
```
echo 'cpu,host=server-01 usage_user=10.5,usage_system=5.2 1678886400' | influx write --bucket "my-bucket" --org "your-org-id"
```
Send single or multiple data points in InfluxDB line protocol format via standard input.
Write data from a file:
```
influx write --bucket "my-bucket" --org "your-org-id" --file ./data.lp
```
Write data points from a file containing InfluxDB line protocol.

Managing Users (InfluxDB OSS < 2.0)

List users:
```
influx user list
```
List all users in the InfluxDB instance.
Create a user:
```
influx user create --username "newuser" --password "securepassword" --admin
```
Create a new user with a username, password, and optionally grant admin privileges.
Update a user:
```
influx user update --id "user-id" --password "newpassword"
```
Update a user’s password or other properties.
Delete a user:
```
influx user delete --id "user-id"
```
Delete a user by their ID.

Managing Dashboards and Variables (InfluxDB OSS < 2.0)

List dashboards:
```
influx dashboard list
```
List all dashboards.
Get dashboard by ID:
```
influx dashboard get --id "dashboard-id"
```
Retrieve the configuration of a specific dashboard.
List variables:
```
influx variable list
```
List all variables.
Get variable by ID:
```
influx variable get --id "variable-id"
```
Retrieve the configuration of a specific variable.

Other Useful Commands

Version:
```
influx version
```
Display the InfluxDB CLI version.
Health check:
```
influx health
```
Check the health status of the InfluxDB instance.

Common Patterns

Quickly query the last 5 minutes of data from a specific measurement:

influx query 'from(bucket: "telegraf") |> range(start: -5m) |> filter(fn: (r) => r._measurement == "cpu") |> limit(n: 10)'

Write data from a CSV file (requires transformation to line protocol first or using a tool like telegraf): If you have a CSV file that needs to be converted to line protocol, you’d typically use telegraf or a script. Once converted to a .lp file:
```
influx write --bucket "my-metrics" --org "my-org" --file "converted_data.lp"
```
Export all data from a bucket (requires careful Flux scripting): This is more complex and usually involves scripting. A basic example to export a subset:
```
influx query --org "my-org" --bucket "my-bucket" 'from(bucket: "my-bucket") |> range(start: 0) |> yield(name: "export")' > export.flux
# Then potentially process export.flux or use it in a write command.
```
For full exports, consider specialized tools or scripts that handle pagination and large datasets.

Set up InfluxDB CLI for a specific project: Create a .env file in your project root:

INFLUX_HOST="http://localhost:8086"
INFLUX_TOKEN="your-project-token"
INFLUX_ORG="your-project-org-id"

And load it in your shell:

set -a; source .env; set +a
# Now 'influx' commands will use these settings

Gotchas

InfluxDB 1.x vs 2.x CLI: The influx command has significant differences between InfluxDB 1.x (CLI v1) and InfluxDB 2.x (CLI v2). Ensure you are using the correct version of the CLI for your InfluxDB instance. This cheatsheet focuses on InfluxDB 2.x.
Token Permissions: Tokens have granular permissions. If a token can’t read from or write to a specific bucket, operations will fail. Always check token permissions.
Organization ID vs Name: Some commands require the Organization ID (--org flag can sometimes accept name, but ID is more reliable), while others might use the name. Always refer to the command’s help (influx <command> --help) if unsure.
Flux Syntax: Flux is a powerful but distinct language. Errors in Flux queries are common. Pay close attention to parentheses, commas, function names, and quotes.
Line Protocol Formatting: When writing data manually, ensure the InfluxDB line protocol format is strictly adhered to (measurement, tags, fields, timestamp). Incorrect formatting will lead to write errors.
Data Types in Line Protocol: Fields can be integers (e.g., 10i), floats (e.g., 10.5), strings (e.g., "hello"), or booleans (e.g., true). Ensure correct type suffixes are used.
Default vs Explicit Settings: Relying on environment variables is convenient but can lead to unexpected behavior if they are not set or are set incorrectly. Explicitly specifying --org and --token in commands can prevent confusion.
Deletion is Permanent: Deleting organizations, buckets, tokens, users, etc., is irreversible. Double-check before executing delete commands.