Install the CQL shell

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.

There are several ways to access the CQL shell, depending on your environment:

Environment CQL shell Notes

HCD tarball installation

Use the bundled CQL shell

A supported Python version is required

HCD package installation

Use the bundled CQL shell

A supported Python version is required

HCD not installed

Download and install the standalone CQL shell

A supported Python version is required

HCD Docker container

Use the bundled CQL shell

A supported Python version is required

Mission Control

Use the embedded CQL console

No additional software is required, but you must have access to the Mission Control UI. For programmatic access, use the other methods.

Install Python

CQL shell requires Python.

HCD 2.0 supports Python 3.8 to 3.13.

If you have multiple Python versions installed, run cqlsh in a virtual environment that uses a supported Python version.

To verify your Python version, run python -V.

Use the bundled CQL shell

Your HCD installation automatically includes cqlsh:

  • Package installations: cqlsh is installed automatically with HCD. You can run cqlsh from your system’s command line if it is in your system’s PATH. Otherwise, run it from the bin directory of your HCD installation.

  • Tarball installations: cqlsh is installed automatically with HCD. You can run cqlsh from the bin directory of your HCD installation directory.

  • HCD container: cqlsh is included with the container image. You can run cqlsh from the HCD bin directory inside the container, or start CQL shell with docker exec. For an example, see Connect to an HCD container.

Install the standalone CQL shell

To install cqlsh without HCD, you need a cqlsh binary tarball. This tarball is included with HCD tarball installation files on IBM Passport Advantage. The cqlsh binary cannot be extracted from HCD DEB/RPM packages.

Separate cqlsh binary tarballs are no longer provided; you must download the HCD tarball installation files, and then extract the standalone cqlsh binary tarball.

If you installed HCD from a tarball, you can use the cqlsh binary from your original tarball installation files.

  1. Get access to IBM Passport Advantage:

    • IBMid: An IBMid account with MFA enabled is required. If you don’t have one, create an IBMid account. If your organization uses Enterprise Federation (EF) for authentication with corporate credentials, see the IBMid EF documentation.

    • Site number: You must be authorized by your Site Primary or Secondary Contact.

    • Entitlement: You must have an active watsonx.data Premium Software Subscription and an HCD entitlement.

    • Temporary passcode (primary contact, initial setup only): If you are a primary contact, you need a temporary passcode from your welcome letter to initially connect your IBMid to your site number.

  2. Download the HCD tarball installation files from IBM Passport Advantage:

    1. Go to the Passport Advantage Online for Customers website and click Sign in to your PAO site.

    2. Log in with your IBMid.

    3. Select Software download from the top menu or the quick links list.

    4. Search for the product by name or part number, or use the Find downloads & media tool to view your entitled products.

      For the best search results, try one of the following:

      • Search by product name: Include the word Version in your search. For example, Hyper-Converged Database Version.

      • Search by part number: Find part numbers for each release in the release notes.

      If results show only eAssemblies, switch to the Images tab to find HCD under Analytics - Platform.

    5. Select the version you need.

    6. Select the files you need, agree to the terms and conditions, and then click Download now.

      The download file is named HCD_VERSION_NUMBER_EN.zip.

  3. Unzip the downloaded file to access the included cqlsh binary tarball (cqlsh-VERSION-bin.tar.gz).

  4. Extract the cqlsh distribution into the directory where you want to install cqlsh:

    tar -xzvf cqlsh-VERSION-bin.tar.gz -C /PATH/TO/INSTALL/DIRECTORY

  5. Optional: Validate the signatures (cqlsh-VERSION-bin.tar.gz.asc and cqlsh-VERSION-bin.tar.gz.cosign.sig), as explained in Validate tarball signatures.

Next steps

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