cqlsh (startup options)

Execute the cqlsh Python script to start the CQL shell. The CQL shell is a Python-based command line interface for running CQL commands interactively. The CQL shell supports tab completion. The cqlsh command runs in either Python 2 or 3.


cqlsh [ <options> ] [ <host_name>[:<port_number>] ]
Syntax legend
Syntax conventions Description


Literal keyword.


Not literal.

< >

Variable value. Replace with a user-defined value.


Optional. Square brackets ([]) surround optional command arguments. Do not type the square brackets.

( )

Group. Parentheses ( ( ) ) identify a group to choose from. Do not type the parentheses.


Or. A vertical bar (|) separates alternative elements. Type any one of the elements. Do not type the vertical bar.


Repeatable. An ellipsis ( ... ) indicates that you can repeat the syntax element as often as required.

'<Literal string>'

Single quotation (') marks must surround literal strings in CQL statements. Use single quotation marks to preserve upper case.

{ <key> : <value> }

Map collection. Braces ({ }) enclose map collections or key value pairs. A colon separates the key and the value.


Set, list, map, or tuple. Angle brackets ( < > ) enclose data types in a set, list, map, or tuple. Separate the data types with a comma.


End CQL statement. A semicolon (;) terminates all CQL statements.


Separate the command line options from the command arguments with two hyphens ( -- ). This syntax is useful when arguments might be mistaken for command line options.

' <<schema\> ... </schema\>> '

Search CQL only: Single quotation marks (') surround an entire XML schema declaration.


Search CQL only: Identify the entity and literal value to overwrite the XML element in the schema and solrConfig files.

Required parameters


To connect the CQL session to a specified node, specify a hostname or IP address and optional port after the cqlsh command, along with any additional CQL shell options.

By default, the CQL shell launches a session with the local host on address You can connect the CQL shell to remote hosts that have a higher or equal CQL shell version than the local CQL shell version. When no port is specified, the connection uses the default port of 9042.


Several options are available for starting the CQL shell.



-b <scb_file>

Load secure connect bundle from the specified file.

--browser="<launch_browser_cmd> %s"

Browser to display the CQL command help. See Web Browser Control for a list of supported browsers. Replace the URL in the command with %s.

-C, --color

Always use color output.


Connection timeout in seconds.

Default: 5


Folder that contains the cqlshrc file. Use tilde (~) for paths relative to the user’s home directory.


CQL version to use. The CQL version displays after starting cqlsh.


Show additional debugging information.


Disables saving history to disk for current execution.


Specify a specific DSE protocol version; otherwise the client will default and downgrade as necessary. Mutually exclusive with --protocol-version.


Output encoding.

Default encoding: utf8


Execute the CQL statement, then exit. To direct the command output to a file, see saving CQL output.

-f <file_name>, --file=<file_name>

Execute commands from a CQL file, then exit.

After starting cqlsh, use the SOURCE command and the path to the file using the cqlsh command line.

-h, --help

Show help.

-k <keyspace_name>, --keyspace=<keyspace_name>

Automatically use the specified keyspace after starting the CQL shell.


Do not display color output.

-p <password>, --password="<password>"

Connect with the specified user’s password.


Specify a specific protocol version. If omitted, the client will use a default, and possibly lower version protocol, as needed.Mutually exclusive with --dse-protocol-version.


CQL request timeout in seconds.

Default: 10

--consistency-level <consistency_level>

Specify the initial consistency level.

Default: ONE

--serial-consistency-level <serial_consistency_level>

Specify the initial serial consistency level.

Default: SERIAL


Use SSL.

-t, --tty

Force TTY command prompt mode.

-u <user_name>, --username="<user_name>"

Connect with the specified user account.


Show the cqlsh version number.

Environment variables

You can use environment variables to overwrite default values for cqlsh commands. For example, increase the timeout values of a user running cqlsh on a particular computer.


Starting the CQL shell

On start up, cqlsh shows the name of the cluster, IP address, and connection port. The cqlsh prompt initially is cqlsh>. If you specify a keyspace, it is added after the prompt.

  1. Start the CQL shell:


    The cluster and host information appears. For example:

    Connected to Test Cluster at
    [cqlsh 5.0.1 | Cassandra 3.3.0 | CQL spec 3.4.0 | Native protocol v4]
    Use HELP for help.
  2. Use the cycling keyspace:

    USE cycling;

    The prompt now includes the keyspace name:


Querying using CQL commands

At the cqlsh prompt, you can enter CQL commands. Use a semicolon to terminate a command. A new line does not terminate a command, and commands can be spread over several lines. For example:

FROM calendar
WHERE race_id = 201;

The returned results are shown in the standard output:

 race_id | race_start_date                 | race_end_date                   | race_name
     201 | 2015-02-18 08:00:00.000000+0000 | 2015-02-22 08:00:00.000000+0000 | Women's Tour of New Zealand
  • How upper- and lower-case literals are treated in commands.

  • When to use quotation marks in strings.

  • How to enter exponential notation.

Saving CQL output in a file

To save output from a CQL statement to a file, use the cqlsh -e option, followed by the CQL statement placed inside quotation marks, and redirect the output to a file.

For example, to save the output of a SELECT statement to myoutput.txt:

cqlsh -e "SELECT * FROM mytable" > myoutput.txt

Connect to a remote node

Specify a remote node IP address:

Connected to West CS Cluster at
[cqlsh 5.0.1 | Cassandra 3.3.0 | CQL spec 3.4.0 | Native protocol v4]
Use HELP for help.

Was this helpful?

Give Feedback

How can we improve the documentation?

© 2024 DataStax | Privacy policy | Terms of use

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Kubernetes is the registered trademark of the Linux Foundation.

General Inquiries: +1 (650) 389-6000, info@datastax.com