The influx command-line interface (CLI) of TSDB for InfluxDB® is a shell that allows you to interact with the HTTP API. You can use the influx CLI to manually write data, write data from files, interactively query data, and view query results that use various formats.

Download the CLI

Download the CLI by using this link: Download, and select v1.7.6.

Download a binary package that is specific to your operating system. The following figure shows the binary packages for different operating systems.

Then, decompress your binary package, and go to the folder that is extracted from the binary package. In the usr/bin/ directory, you can find the influx CLI. If you download a Windows binary package, you can find the influx.exe binary file in the folder extracted from the package. If you use the Mac OS X operating system, run the following commands to download the binary package and go to the directory where influx resides:

$ wget https://dl.influxdata.com/influxdb/releases/influxdb-1.7.6_darwin_amd64.tar.gz
$ tar zxvf influxdb-1.7.6_darwin_amd64.tar.gz
$ cd influxdb-1.7.6-1/usr/bin
$

Start influx

To use the CLI, start influx in your terminal first. After your TSDB for InfluxDB® instance is connected, you can view the following output:

$ ./influx -ssl -username <Username> -password <Password> -host <Domain name> -port 3242
Connected to https://<Domain name>:3242 version 1.7.x
InfluxDB shell version: 1.7.x

TSDB for InfluxDB® uses the Secure Sockets Layer (SSL) protocol to ensure security during data transmission. Therefore, each time you connect to a TSDB for InfluxDB® instance, you must set the following five parameters: -ssl, -username, -password, -host, and -port.

Parameter description

• -ssl: indicates that HTTPS is used to connect to TSDB for InfluxDB® servers.

• -username: specifies the username that is used to connect to the servers.

• -password: specifies the password for the username.

• -host: specifies the domain name. You can find the domain name on the Instance Details page in the TSDB console. The following figure shows the Instance Details page.

• -port: specifies a network port. The default port is port 3242.

Then, you can enter InfluxQL query statements and CLI-specific commands in your terminal. If you want to enter Flux query statements, you must set the -type parameter to flux. You can use the help command to obtain available commands. You can use the Ctrl+C keyboard shortcut to terminate long-running InfluxQL queries.

Use environment variables

You can use the following environment variables to configure the settings for the influx client. You can specify the environment variables by using uppercase or lowercase characters, but the uppercase version has a higher priority.

HTTP_PROXY

This environment variable defines the proxy server that is used for HTTP.

Value format: [protocol://][:port]

HTTP_PROXY=http://localhost:1234

HTTPS_PROXY

This environment variable defines the proxy server that is used for HTTPS. If you set the HTTP_PROXY and HTTPS_PROXY variables, the HTTPS_PROXY value has a higher priority than the HTTP_PROXY value for HTTPS.

Value format: [protocol://][:port]

HTTPS_PROXY=https://localhost:1443

NO_PROXY

This environment variable specifies a list of host names that do not use proxies. If you set this variable to an asterisk (*) only, the variable matches all hosts.

Value format: a comma-separated list of hosts

NO_PROXY=123.45.67.89,123.45.67.90

Arguments for influx

You can pass available arguments into influx when you start influx. To obtain the list of available arguments, run the $influx --help command. This section provides a brief description about each available argument, and offers the details about the -execute, -format, and -import arguments.

-compressed

Specifies whether to compress data. The -compressed argument is used in conjunction with the -import argument. If an imported file is compressed, set this argument to true.

-consistency 'any|one|quorum|all'

Specifies a consistency level for data writes.

-database 'database name'

Specifies the database to which the influx CLI connects.

-execute '<command>'

Executes an InfluxQL statement and exits.

-format 'json|csv|column'

Specifies the format of server responses.

-host '<hostname>'

Specifies the host to which the influx CLI connects.

-import

Imports new data from a file, or imports previously exported database data from a file.

-password '<password>'

Specifies the password that the influx CLI uses to connect to the server. If you do not specify this argument (-password ''), the influx CLI prompts you to enter your password. You can also use the INFLUX_PASSWORD environment variable to specify a password for the CLI.

-path

Specifies the path where the file to be imported resides. The -path argument must be used in conjunction with the -import argument.

-port 'port #'

Specifies the port to which the influx CLI connects. By default, TSDB for InfluxDB® runs on port 3242.

-pps

Specifies the number of points that can be imported per second. By default, the -pps argument is set to 0 and the influx CLI does not limit the speed of importing data. The -pps argument must be used in conjunction with the -import argument.

-precision 'rfc3339|h|m|s|ms|u|ns'

Specifies the format and the granularity of timestamps for data queries and writes: rfc3339 (YYYY-MM-DDTHH:MM:SS.nnnnnnnnnZ), h (hours), m (minutes), s (seconds), ms (milliseconds), u (microseconds), and ns (nanoseconds). The default granularity is nanoseconds.

Note: If the granularity is set to rfc3339 (-precision rfc3339), this argument can be used in conjunction with the -execute argument but cannot be used in conjunction with the -import argument. If the granularity is set to the other formats, this argument can be used in conjunction with -execute and -import arguments. The other granularity formats include h, m, s, ms, u, and ns.

-pretty

Beautifies JSON-formatted data to deliver improved reading experience.

-ssl

Enables HTTPS for requests.

-type

Specifies the interactive shell that is used. The default value is influxql. If you want to use the Flux REPL shell, set -type to flux.

-username 'username'

Specifies the username that the influx CLI uses to connect to the server. You can also use the INFLUX_USERNAME environment variable to specify a username for the CLI.

-version

Shows the TSDB for InfluxDB® version and exits.

Execute an InfluxQL statement and exit by using -execute

If you want to query data from all available databases, run the following query:

$ influx -ssl -username <Username> -password <Password> -host <Domain name> -port 3242 -execute 'SHOW DATABASES'
name: databases
---------------
name
NOAA_water_database
_internal
telegraf
pirates

If you want to query data from a specific database and change the timestamp granularity, run the following query:

$ influx -ssl -username <Username> -password <Password> -host <Domain name> -port 3242 -execute 'SELECT * FROM "h2o_feet" LIMIT 3' -database="NOAA_water_database" -precision=rfc3339
name: h2o_feet
--------------
time                     level description     location      water_level
2015-08-18T00:00:00Z     below 3 feet          santa_monica  2.064
2015-08-18T00:00:00Z     between 6 and 9 feet  coyote_creek  8.12
2015-08-18T00:06:00Z     between 6 and 9 feet  coyote_creek  8.005

Specify the format of server responses by using -format

The default value for the -format argument is column.

$ influx -ssl -username <Username> -password <Password> -host <Domain name> -port 3242 -format=column
[...]
> SHOW DATABASES
name: databases
---------------
name
NOAA_water_database
_internal
telegraf
pirates

Change the format to csv.

$ influx -ssl -username <Username> -password <Password> -host <Domain name> -port 3242 -format=csv
[...]
> SHOW DATABASES
name,name
databases,NOAA_water_database
databases,_internal
databases,telegraf
databases,pirates

Change the format to json.

$ influx -ssl -username <Username> -password <Password> -host <Domain name> -port 3242 -format=json
[...]
> SHOW DATABASES
{"results":[{"series":[{"name":"databases","columns":["name"],"values":[["NOAA_water_database"],["_internal"],["telegraf"],["pirates"]]}]}]}

Change the format to json and beautify the output data.

$ influx -ssl -username <Username> -password <Password> -host <Domain name> -port 3242 -format=json -pretty
[...]
> SHOW DATABASES
{
    "results": [
        {
            "series": [
                {
                    "name": "databases",
                    "columns": [
                        "name"
                    ],
                    "values": [
                        [
                            "NOAA_water_database"
                        ],
                        [
                            "_internal"
                        ],
                        [
                            "telegraf"
                        ],
                        [
                            "pirates"
                        ]
                    ]
                }
            ]
        }
    ]
}

Import data from a file by using -import

An imported file consists of two parts:

• Data Definition Language (DDL): includes InfluxQL statements that are used to create the relevant database and manage the retention policy. If your database and retention policy have been created, you can skip this part in the file.
• Data Manipulation Language (DML): lists the relevant database and the retention policy if you require the retention policy, and contains the data that uses the line protocol.

Example
Assume that the pirates database and the oneday retention policy have been created.

File datarrr.txt:

# DML
# CONTEXT-DATABASE: pirates
# CONTEXT-RETENTION-POLICY: oneday
treasures,captain_id=dread_pirate_roberts value=801 1439856000
treasures,captain_id=flint value=29 1439856000
treasures,captain_id=sparrow value=38 1439856000
treasures,captain_id=tetra value=47 1439856000
treasures,captain_id=crunch value=109 1439858880

Command:

$influx -ssl -username <Username> -password <Password> -host <Domain name> -port 3242 -import -path=datarrr.txt -precision=s

Result:

2015/12/22 12:25:06 Processed 0 commands
2015/12/22 12:25:06 Processed 5 inserts
2015/12/22 12:25:06 Failed 0 inserts

Note: For large datasets, the influx CLI provides a status message every 100,000 points. An example of the status message is provided as follows:
2015/08/21 14:48:01 Processed 3100000 lines. Time elapsed: 56.740578415s. Points per second (PPS): 54634

To use -import, you must pay attention to the following considerations:

• You can use the -pps argument to specify the number of points that can be imported per second. This setting is applied when you write points to the database. By default, the -pps argument is set to 0 and the influx CLI does not limit the speed of importing data.
• You can import data from .gz files by including -compressed in the command.
• You must provide timestamps for the points that are stored in files. Otherwise, TSDB for InfluxDB® assigns the same timestamp to points that do not have timestamps. This may cause unexpected data overwriting.
• If your data file has more than 5,000 points, you may need to split the data file into multiple smaller files. This allows you to write data to TSDB for InfluxDB® in batches. We recommend that you include 5,000 or 10,000 points in each batch. If you include a smaller number of points in each batch, a larger number of HTTP requests must be sent. This compromises the performance. By default, the time-out period for each HTTP request is five seconds. TSDB for InfluxDB® attempts to write points after a request time-out, but the points may fail to be written.

Commands of the influx CLI

You can enter help in the CLI to obtain available commands.

Commands

This section provides a brief description of each available command, and provides the details about the insert command.

auth

Prompts you to enter your username and password. The influx CLI requires the authentication information when you send requests to databases. You can also use the INFLUX_USERNAME and INFLUX_PASSWORD environment variables to specify the username and the password for the CLI, respectively.

chunked

Returns chunked responses sent from a server when you run queries. By default, chunked responses are returned.

chunk size <size>

Specifies the size for each chunk of the responses. The default chunk size is 10,000. You can reset the chunk size to its default value by setting the size parameter to 0.

clear [ database | db | retention policy | rp ]

Clears the context for the current database or the retention policy.

connect <host:port>

Connects to another server without the need to exit from the shell. By default, the influx CLI connects to localhost:8086. If you do not specify the host or the port, the influx CLI uses the default settings for the parameters that you do not specify.

consistency <level>

Specifies a consistency level for data writes. The valid values are any, one, quorum, and all.

Ctrl+C

Terminates a running query. This command is especially useful if you want to terminate long-running interactive queries where the system attempts to return large amounts of data.

exit quit Ctrl+D

Exits the influx shell.

format <format>

Specifies the format of server responses. The valid values are json, csv, and column.

history

Shows your command history. To run the history command in the shell, use the up arrow. The influx CLI stores your latest 1,000 commands in the .influx_history file that is located in your home directory.

insert

Writes data by using the line protocol.

precision <format>

Specifies the format and the granularity of timestamps for data queries and writes: rfc3339 (YYYY-MM-DDTHH:MM:SS.nnnnnnnnnZ), h (hours), m (minutes), s (seconds), ms (milliseconds), u (microseconds), or ns (nanoseconds). The default granularity is nanoseconds.

pretty

Beautifies JSON-formatted data to deliver improved reading experience.

settings

Returns the current settings of the shell. The current settings include the settings of the Host, Username, Database, Retention Policy, Pretty, Chunked, Chunk Size, Format, and Write Consistency elements.

use [ "<database_name>" | "<database_name>"."<retention policy_name>" ]

Specifies the current database and retention policy. If the current database and the retention policy are specified in the influx CLI, you do not need to specify the database or the retention policy in queries. If you do not specify a retention policy, the influx CLI queries data from the default (DEFAULT) retention policy of the database by default.

Write data to TSDB for InfluxDB® by using insert

To write the data to TSDB for InfluxDB®, enter insert, and then enter the data that uses the line protocol. To write data to a specific retention policy, use insert into <retention policy> <line protocol>.

The following example writes data into a single field in the treasures measurement that includes the captain_id = pirate_king tag. By default, the influx CLI writes the point to the default (DEFAULT) retention policy of the database.

> INSERT treasures,captain_id=pirate_king value=2
>

The following example writes the same point in the preceding example to the existing oneday retention policy.

> INSERT INTO oneday treasures,captain_id=pirate_king value=2
Using retention policy oneday
>

Queries

Run all InfluxQL queries in the influx CLI.

For more information about InfluxQL, see Data exploration, Schema exploration, and Database management.

InfluxDB® is a trademark registered by InfluxData, which is not affiliated with, and does not endorse, TSDB for InfluxDB®.