Connect to HCD with the CQL shell (cqlsh)

The CQL shell (cqlsh) is a Python-based command-line shell you can use to issue Cassandra Query Language (CQL) statements to your Hyper-Converged Database (HCD) databases. The CQL shell also provides unique cqlsh commands, like DESCRIBE KEYSPACE, that aren’t available through the Cassandra drivers or other CQL-only tools.

These steps are for running the CQL shell on the command line with direct cluster connections or Mission Control gateway connections. If you are using the embedded CQL shell in Mission Control, see Use the CQL console to interact with the databases in your datacenter.

Prerequisites

Start the CQL shell

To start the CQL shell, run cqlsh directly on the command line if it is in your system’s PATH. Otherwise, run bin/cqlsh from the directory where you installed HCD or a standalone cqlsh binary (without HCD).

With the exception of --version and --help, most cqlsh operations require connection details, credentials, and other options. CQL and cqlsh statements that interact with your database are passed with --file option, --execute option, or at the interactive cqlsh prompt. The following sections provide more information about options and ways of interacting with cqlsh.

CQL shell in PATH
cqlsh [ OPTIONS ] [ HOST[:PORT] ]
CQL shell not in PATH
INSTALL_DIRECTORY/bin/cqlsh [ OPTIONS ] [ HOST[:PORT] ]

Connect to a node

Credentials passed on the command line can be stored in your shell history and the cqlsh_history file. To avoid this, do one of the following:

  • Store sensitive values in cqlsh environment variables, such as CQLSH_PASSWORD.

  • Use a .cqlshrc file.

  • Pass -u without -p to be prompted for the password without storing it in your shell history.

cqlsh connects to a running database instance using the Apache Cassandra Python driver and the Cassandra native protocol.

Starting cqlsh with no arguments attempts to connect to the local host at 127.0.0.1:9042 without authentication if no credentials or connection details are provided in a .cqlshrc file. To connect to a remote node, provide the host name or IP address and port (optional) of the target node. If authentication is enabled, provide the required credentials.

The following example uses internal username and password authentication. The --password option is omitted so that the user is prompted for the password instead of storing it in the shell history.

cqlsh IP_ADDRESS:PORT -u DATABASE_ROLE_NAME

If you use a Mission Control CQL gateway, the gateway Secure Connect Bundle (SCB) sets the host and port automatically. Specify the SCB zip file with the -b option, and don’t set a host name or port on the command line.

bin/cqlsh -b PATH/TO/SCB_ZIP_FILE -u DATABASE_ROLE_NAME

For more connection options, see CQL shell options.

Run commands with the CQL shell

You can execute CQL and CQL shell commands in the interactive cqlsh shell environment, or non-interactively with the --execute and --file options.

For --execute and --file usage, see General session options.

If you don’t use --execute or --file, cqlsh starts in interactive mode. A successful connection shows the connection details and the cqlsh> prompt. Issue CQL or cqlsh commands directly at the cqlsh> prompt. The results output to the terminal.

Connected to hcd-cluster at 192.0.2.200:9042
[cqlsh 6.1.0 | Cassandra 4.1.x | CQL spec 3.4.6 | Native protocol v5]
Use HELP for help.
cqlsh>

If you start cqlsh with the --keyspace option, the shell prompt includes the keyspace name, such as cqlsh:cycling>. If you run the USE command to select a keyspace after starting cqlsh, the shell prompt changes accordingly. For example:

cqlsh> USE cycling;
cqlsh:cycling> SELECT * FROM calendar WHERE race_id = 201;

After you start a cqlsh session, try these basic commands:

  1. Create a keyspace named store that uses NetworkTopologyStrategy with a replication factor of 1.

    Replace datacenter1 with a valid datacenter name for your cluster.

    CREATE KEYSPACE IF NOT EXISTS store WITH REPLICATION = {
  'class' : 'NetworkTopologyStrategy',
  'datacenter1' : '1'
};

  2. In the store keyspace, create a table named shopping_cart with three columns: userid, item_count, and last_update.

    CREATE TABLE IF NOT EXISTS store.shopping_cart (
  userid text PRIMARY KEY,
  item_count int,
  last_update timestamp
);

  3. Insert rows into the shopping_cart table.

    The value of the last_update column is generated using CQL native functions. The now() function gets the current date and time, and the toTimeStamp() function converts the date and time to a timestamp.

    INSERT INTO store.shopping_cart (userid, item_count, last_update)
  VALUES ('4729', 2, toTimeStamp(now()));
INSERT INTO store.shopping_cart (userid, item_count, last_update)
  VALUES ('1836', 5, toTimeStamp(now()));

  4. Query the shopping_cart table.

    This example uses an unbounded SELECT * query to retrieve all rows from the table. This isn’t recommended in production due to performance impacts. It is acceptable in this example because the amount of data is very small.

    SELECT * FROM store.shopping_cart;
     userid | item_count | last_update
--------+------------+---------------------------------
   4729 |          2 | 2024-10-12 04:23:03.636000+0000
   1836 |          5 | 2024-10-12 04:23:04.327000+0000

(2 rows)

CQL shell options

You can set cqlsh options on the command line, as environment variables, or in a .cqlshrc file.

cqlsh uses the following hierarchy to determine the value of the options:

  1. Command line options override environment variables and .cqlshrc.

  2. Environment variables override values set in .cqlshrc.

  3. .cqlshrc overrides the default values.

  4. If not set elsewhere, cqlsh uses the default values.

Connection details

Command line Environment variable .cqlshrc section and option Description

-b <path/to/scb_zip_file>

File path to a Mission Control CQL gateway Secure Connect Bundle (SCB). Use ~ for the user’s home directory.

--cqlshrc="<path/to/directory>"

CQLSHRC

Cannot be set in .cqlshrc

Path to a directory containing a .cqlshrc file if not using the default location ~/.cassandra/. Use ~ for the user’s home directory.

cqlsh looks for a file named .cqlshrc in the specified directory. There must be only one .cqlshrc file in the specified directory.

--connect-timeout="<timeout>"

CQLSH_CONNECT_TIMEOUT

[connection], timeout

Connection timeout in seconds. The default is 5.

<host_name_or_ip>:<port>

CQLSH_HOSTNAME, CQLSH_PORT

[connection], hostname, port

Host name or IP address of the database node to connect to. Port is optional if using the default native protocol port. The default is 127.0.0.1:9042.

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

CQLSH_PASSWORD

[authentication], password

Password for --username.

--ssl

CQLSH_SSL

[connection], ssl

Whether to use SSL for the connection. The default is false.

To enable client-to-node SSL encryption, additional configuration is required. See Use a cqlshrc file.

When using a Mission Control CQL gateway, SSL is configured automatically with the SCB. --ssl is ignored if -b is set.

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

CQLSH_USERNAME

[authentication], username

CQL role to use for authentication.

General session options

Command line Environment variable .cqlshrc section and option Description

--browser="<launch_browser_cmd> %s"

CQLSH_BROWSER

[ui], browser

Open CQL help in the specified browser if you don’t want to use the system’s default browser. Replace the URL in the browser launch command with %s. For example, /usr/bin/google-chrome-stable %s.

--color (-C), --no-color

CQLSH_COLOR

[ui], color (on, off)

Whether to use color output. The default is --color.

--consistency-level="<CL>", --serial-consistency-level="<CL>"

CQLSH_CONSISTENCY_LEVEL, CQLSH_SERIAL_CONSISTENCY_LEVEL

Specify the initial consistency level for the session, depending on the transaction type.

Lightweight transactions (LWTs) use --serial-consistency-level (default: SERIAL). All other transactions use --consistency-level (default: ONE). For more information, see Consistency levels.

After starting the session, the consistency level can be changed with the CONSISTENCY command.

--cqlversion="X.Y.Z"

CQLSH_CQLVERSION

[cql], version

Set a specific CQL version to use for the session. Not useful unless connecting to an earlier version of Cassandra or DSE that doesn’t support the default CQL version.

The CQL version is printed with the connection details after starting cqlsh.

--debug

Not set as an environment variable.

Not set in .cqlshrc.

Show additional debugging information.

--disable-history=<bool>

CQLSH_DISABLE_HISTORY

[history], disabled

Whether to disable command history.

By default (--disable-history=false), when you exit a cqlsh session, the command history is appended to ~/.cassandra/cqlsh_history. Existing history isn’t overwritten. A cqlsh_history file is created if not found at the expected location.

If --disable-history=true, command history is not generated.

Command history is stored in plaintext as entered on the command line, including arguments that might contain sensitive values. For better security when history is enabled, set permissions on the cqlsh_history file with chmod or similar commands.

To change the default history file location, set the CQL_HISTORY environment variable to the desired directory path. There is no command line option for the history file path.

When CQL_HISTORY is set, cqlsh creates parent directories and the cqlsh_history file if they don’t exist. Previous history isn’t migrated to the new location. You can copy your existing cqlsh_history file to the new location before starting cqlsh, or insert the contents before the first line of the new cqlsh_history file.

CQL_HISTORY is ignored and has no purpose when --disable-history=true

--dse-protocol-version="<VERSION>"

CQLSH_DSE_PROTOCOL_VERSION

[protocol], dse_version

Enforce a DSE protocol version for the connection to the server. If not specified, the client requests the highest version it supports, negotiating and downgrading as necessary.

Typically used when the default version is undesirable or lower versions are incompatible, such as with ZDM Proxy.

Mutually exclusive with --protocol-version.

--encoding="<output_encoding>"

CQLSH_ENCODING

[ui], encoding

Encoding to use for output. The default is utf8.

-e "<statement>",--execute="<CQL_statement>"

Not set as an environment variable.

Not set in .cqlshrc.

Runs the specified CQL or cqlsh statement, and then exits the cqlsh session.

The entire value of -e must be wrapped in double quotes. Each CQL statement must be terminated with a semicolon (;).

To execute multiple statements:

  • Pass multiple -e options: cqlsh -e "USE cycling;" -e "DESCRIBE KEYSPACE;"

  • Combine all statements into a single -e string: cqlsh -e "USE cycling; DESCRIBE KEYSPACE;"

  • Use the --file option.

By default, results output to the terminal. Use the redirection operator > to write the output to a file.

To run statements without exiting, start cqlsh without --execute, and then issue statements interactively at the prompt.

-f <path/to/file.cql>, --file="<path/to/file.cql>"

Not set as an environment variable.

Not set in .cqlshrc.

Runs one or more CQL or cqlsh statements from a .cql file, and then exits the cqlsh session. Each statement in the file must be terminated with a semicolon (;) and placed on a separate line. Use ~ for the user’s home directory.

By default, results are displayed in the terminal. You can use the redirection operator > to write the output to a file instead.

To run statements from a file without exiting, start cqlsh without -f, and then run the SOURCE command interactively at the prompt.

-k <name>, --keyspace="<name>"

CQLSH_KEYSPACE

[authentication], keyspace

Sets the initial keyspace for the cqlsh session.

The authenticating role must have permission to access the keyspace.

When using the interactive cqlsh prompt, you can change the active keyspace with the USE command.

--protocol-version="<version>"

CQLSH_PROTOCOL_VERSION

[protocol], version

Enforce a Cassandra Native Protocol version for the connection to the server. If not specified, the client requests the highest version it supports, negotiating and downgrading as necessary.

Typically used when the default version is undesirable or lower versions are incompatible, such as with ZDM Proxy.

Mutually exclusive with --dse-protocol-version.

--request-timeout="<seconds>"

CQLSH_REQUEST_TIMEOUT

[connection], request_timeout

CQL request timeout in seconds.

The default is 10 seconds.

-t, --tty

CQLSH_TTY

Not set in .cqlshrc.

Force TTY command prompt mode.

--version

Not set as an environment variable.

Not set in .cqlshrc.

Prints the version of CQL shell that is installed on the local host, and exits. Credentials aren’t required because this command doesn’t start a session or connect to the cluster.

For more .cqlshrc options, see Use a cqlshrc file.

Troubleshoot the CQL shell

If cqlsh cannot connect, and it mentions a different port than 9042, make sure your ~/.cassandra/cqlshrc file and CQLSH_* environment variables aren’t modifying the default port.

For command help, run cqlsh --help or cqlsh -h with no other arguments to show general help, or run --help with a command or subcommand for context-specific help. HTML help documentation opens in the system’s default web browser unless --browser is set. This command exits immediately without starting a session or connecting to the cluster.

For detailed logs, start cqlsh or run any cqlsh command with the --debug option.

See also

Was this helpful?

Give Feedback

How can we improve the documentation?

© Copyright IBM Corporation 2026 | Privacy policy | Terms of use |  Manage Privacy Choices

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: Contact IBM