All Products
Search

This Product

    Command-line interface

    Document Center

    Command-line interface

    Last Updated: Sep 04, 2020

    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:

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

    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:

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

    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.

    image

    • -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] 

     
      
  
    1. HTTP_PROXY=http://localhost:1234
      2.

    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] 

     
      
  
    1. HTTPS_PROXY=https://localhost:1443
      2.

    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

     
      
  
    1. NO_PROXY=123.45.67.89,123.45.67.90
      2.

    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:

     
      
  
    1. $ influx -ssl -username <Username> -password <Password> -host <Domain name> -port 3242 -execute 'SHOW DATABASES'
      2. 
  
    2. name: databases
      3. 
  
    3. ---------------
      4. 
  
    4. name
      5. 
  
    5. NOAA_water_database
      6. 
  
    6. _internal
      7. 
  
    7. telegraf
      8. 
  
    8. pirates
      9.

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

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

    Specify the format of server responses by using -format

    The default value for the -format argument is column.

     
      
  
    1. $ influx -ssl -username <Username> -password <Password> -host <Domain name> -port 3242 -format=column
      2. 
  
    2. [...]
      3. 
  
    3. > SHOW DATABASES
      4. 
  
    4. name: databases
      5. 
  
    5. ---------------
      6. 
  
    6. name
      7. 
  
    7. NOAA_water_database
      8. 
  
    8. _internal
      9. 
  
    9. telegraf
      10. 
  
    10. pirates
      11.

    Change the format to csv.

     
      
  
    1. $ influx -ssl -username <Username> -password <Password> -host <Domain name> -port 3242 -format=csv
      2. 
  
    2. [...]
      3. 
  
    3. > SHOW DATABASES
      4. 
  
    4. name,name
      5. 
  
    5. databases,NOAA_water_database
      6. 
  
    6. databases,_internal
      7. 
  
    7. databases,telegraf
      8. 
  
    8. databases,pirates
      9.

    Change the format to json.

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

    Change the format to json and beautify the output data.

     
      
  
    1. $ influx -ssl -username <Username> -password <Password> -host <Domain name> -port 3242 -format=json -pretty
      2. 
  
    2. [...]
      3. 
  
    3. > SHOW DATABASES
      4. 
  
    4. {
      5. 
  
    5.     "results": [
      6. 
  
    6.         {
      7. 
  
    7.             "series": [
      8. 
  
    8.                 {
      9. 
  
    9.                     "name": "databases",
      10. 
  
    10.                     "columns": [
      11. 
  
    11.                         "name"
      12. 
  
    12.                     ],
      13. 
  
    13.                     "values": [
      14. 
  
    14.                         [
      15. 
  
    15.                             "NOAA_water_database"
      16. 
  
    16.                         ],
      17. 
  
    17.                         [
      18. 
  
    18.                             "_internal"
      19. 
  
    19.                         ],
      20. 
  
    20.                         [
      21. 
  
    21.                             "telegraf"
      22. 
  
    22.                         ],
      23. 
  
    23.                         [
      24. 
  
    24.                             "pirates"
      25. 
  
    25.                         ]
      26. 
  
    26.                     ]
      27. 
  
    27.                 }
      28. 
  
    28.             ]
      29. 
  
    29.         }
      30. 
  
    30.     ]
      31. 
  
    31. }
      32.

    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:

     
      
  
    1. # DML
      2. 
  
    2. # CONTEXT-DATABASE: pirates
      3. 
  
    3. # CONTEXT-RETENTION-POLICY: oneday
      4. 
  
      5. 
  
    5. treasures,captain_id=dread_pirate_roberts value=801 1439856000
      6. 
  
    6. treasures,captain_id=flint value=29 1439856000
      7. 
  
    7. treasures,captain_id=sparrow value=38 1439856000
      8. 
  
    8. treasures,captain_id=tetra value=47 1439856000
      9. 
  
    9. treasures,captain_id=crunch value=109 1439858880
      10.

    Command:

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

    Result:

     
      
  
    1. 2015/12/22 12:25:06 Processed 0 commands
      2. 
  
    2. 2015/12/22 12:25:06 Processed 5 inserts
      3. 
  
    3. 2015/12/22 12:25:06 Failed 0 inserts
      4.

    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.

     
      
  
    1. > INSERT treasures,captain_id=pirate_king value=2
      2. 
  
    2. >
      3.

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

     
      
  
    1. > INSERT INTO oneday treasures,captain_id=pirate_king value=2
      2. 
  
    2. Using retention policy oneday
      3. 
  
    3. >
      4.

    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®.

    Free Trial Free Trial