Skip to content
Maintained by AxonOps — production-grade documentation from engineers who operate distributed databases at scale

CQLAI Quickstart

Get started with CQLAI in under 5 minutes.

Installation

macOS

# Using Homebrew
brew install axonops/tap/cqlai

# Or download directly
curl -L https://github.com/axonops/cqlai/releases/latest/download/cqlai-darwin-arm64 -o cqlai
chmod +x cqlai
sudo mv cqlai /usr/local/bin/

Linux

curl -L https://github.com/axonops/cqlai/releases/latest/download/cqlai-linux-amd64 -o cqlai
chmod +x cqlai
sudo mv cqlai /usr/local/bin/

Verify Installation

cqlai --version

Connect to Cassandra

Local Cassandra

cqlai

Remote Cassandra

cqlai --host cassandra.example.com

With Authentication

cqlai --host cassandra.example.com --username myuser --password mypassword

With SSL

cqlai --host cassandra.example.com --ssl

Basic Usage

Execute CQL Queries

cqlai> USE my_keyspace;
cqlai:my_keyspace> SELECT * FROM users LIMIT 10;

View Schema

-- List keyspaces
cqlai> DESCRIBE KEYSPACES;

-- Describe a table
cqlai> DESCRIBE TABLE my_keyspace.users;

-- Quick schema view
cqlai> .schema

Useful Commands

Command Description
.help Show available commands
.schema Show current schema
.tables List tables in current keyspace
.clear Clear the screen
.exit Exit CQLAI

AI Query Generation (Optional)

Generate CQL queries from natural language descriptions.

Set up (Choose One Provider)

# OpenAI
export OPENAI_API_KEY=sk-...

# Anthropic Claude
export ANTHROPIC_API_KEY=sk-ant-...

# Local Ollama (no API key needed)
ollama serve

Generate Queries

cqlai> .ai show all users who signed up this week

Generated CQL:
  SELECT * FROM users
  WHERE created_at >= '2024-01-08'
  ALLOW FILTERING;

Execute? [Y/n]: y

Export Data

To CSV

cqlai> .export users users.csv
cqlai> .export users users.csv --format csv

To Parquet

cqlai> .export users users.parquet --format parquet

To JSON

cqlai> .export users users.json --format json

Export query results: 

cqlai> .export "SELECT * FROM orders WHERE status = 'pending'" pending.csv

Configuration File

Create a configuration file for persistent settings. CQLAI supports JSON format:

// ~/.config/cqlai/config.json (or ~/.cqlai.json or ./cqlai.json)
{
  "host": "cassandra.example.com",
  "port": 9042,
  "username": "myuser",
  "ssl": {
    "enabled": true
  },
  "ai": {
    "provider": "openai",
    "model": "gpt-4"
  }
}

See Configuration for all available options.

Next Steps