Skip to content

‣ Cqlsh

📖 Reference Documentations and resources
  1. 📖 Astra Docs - Reference documentation
  2. 📖 Cql Tool Docs - Reference Documentation

A - Overview

CqlSH is a command-line interface for interacting with Cassandra using CQL (the Cassandra Query Language). It is shipped with every Cassandra package, and can be found in the bin/ directory alongside the cassandra executable. cqlsh is implemented with the Python native protocol driver, and connects to the single specified node.

You can setup the software by providing options in the command line and/OR provide the settings in a file called cqlshrc located in ~/.cassandra

> cqlsh --help
Usage: cqlsh [options] [host [port]]

CQL Shell

  --version             show program's version number and exit
  -h, --help            show this help message and exit
  -C, --color           Always use color output
  --no-color            Never use color output
  --browser=BROWSER     The browser to use to display CQL help, where BROWSER
                        can be:
                        - one of the supported browsers in
                        - browser path followed by %s, example: /usr/bin
                        /google-chrome-stable %s
  --ssl                 Use SSL
  -u USERNAME, --username=USERNAME
                        Authenticate as user.
  -p PASSWORD, --password=PASSWORD
                        Authenticate using password.
  -k KEYSPACE, --keyspace=KEYSPACE
                        Authenticate to the given keyspace.
                        Connect using secure connect bundle. If this option is
                        specified host, port settings are ignored
  -f FILE, --file=FILE  Execute commands from FILE, then exit
  --debug               Show additional debugging information
  --coverage            Collect coverage data
  --encoding=ENCODING   Specify a non-default encoding for output. (Default:
  --cqlshrc=CQLSHRC     Specify an alternative cqlshrc file location.
                        Specify a particular CQL version, by default the
                        highest version supported by the server will be used.
                        Examples: "3.0.3", "3.1.0"
                        Specify a specific protocol version; otherwise the
                        client will default and downgrade as necessary.
                        Mutually exclusive with --dse-protocol-version.
  -e EXECUTE, --execute=EXECUTE
                        Execute the statement and quit.
                        Specify the connection timeout in seconds (default: 5
                        Specify the default request timeout in seconds
                        (default: 10 seconds).
                        Specify the initial consistency level.
                        Specify the initial serial consistency level.
  -t, --tty             Force tty mode (command prompt).
  --no-file-io          Disable cqlsh commands that perform file I/O.
  --disable-history     Disable saving of history

Connects to by default. These defaults can be changed by
setting $CQLSH_HOST and/or $CQLSH_PORT. When a host (and optional port number)
are given on the command line, they take precedence over any defaults.

B - Prerequisites

C - Installation

✅ Step 1: Download and extract the archive

  • To download the archive you can go on the download page, check the box and download the file:

  • You can also use the command line:
wget \
          && tar xvzf cqlsh-astra.tar.gz \
          && rm -f cqlsh-astra.tar.gz
  • The archive should look like:

✅ Step 2: Start cqlsh providing parameters in the command line:

  • From the directory where you extracted the CQLSH tarball, run the cqlsh script from the command line:
$ cd /cqlsh-astra/bin

$ ./cqlsh -u ${CLIENT_ID} -p ${CLIENT_SECRET} -b ${}
  • -u (username) - Client ID as provided in the token generation page
  • -p (password) - Client secret as provided in the token generation page
  • -b (bundle) - location of the secure connect bundle that you downloaded for your database.

✅ Step 3: Start Cqlsh providing parameters in cqlshrc

Configure the cqlshrc file If you do not want to pass the secure connect bundle on the command line every time, set up the location in your cqlshrc file in ~/.cassandra

username = ${CLIENT_ID}
password = ${CLIENT_SECRET}

secure_connect_bundle = ${}

D - Tips and tricks

  • If is a good idea to add cqlsh in your path to be able to use from everywhere

  • If you want to work with multiple DB use some alias with the parameters

alias cqlsh_db1='cqlsh -u user -p password -b'
alias cqlsh_db2='cqlsh --cqlshrc_db2'

Last update: 2022-09-02