{"id":30707063,"url":"https://github.com/axonops/cqlai","last_synced_at":"2026-04-07T11:01:25.306Z","repository":{"id":312549915,"uuid":"1042798112","full_name":"axonops/cqlai","owner":"axonops","description":"Modern AI-powered CQL shell for Apache Cassandra® with rich terminal UI, cqlsh compatibility, and natural language query generation","archived":false,"fork":false,"pushed_at":"2026-04-04T21:06:58.000Z","size":52355,"stargazers_count":14,"open_issues_count":9,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-04T23:25:39.920Z","etag":null,"topics":["ai","apache-cassandra-tools","apachecassandra","cassandra-cql","cassandra-database","cassandra-db","cql","cqlsh","database-client","database-tools","dba","developer-tools","go","golang","llm","natural-language","terminal","tui"],"latest_commit_sha":null,"homepage":"https://axonops.com","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/axonops.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-22T15:37:31.000Z","updated_at":"2026-04-04T21:07:00.000Z","dependencies_parsed_at":"2025-08-31T14:19:46.623Z","dependency_job_id":"355971e1-368e-4d89-8e6e-8de66afd066f","html_url":"https://github.com/axonops/cqlai","commit_stats":null,"previous_names":["axonops/cqlai"],"tags_count":75,"template":false,"template_full_name":null,"purl":"pkg:github/axonops/cqlai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axonops%2Fcqlai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axonops%2Fcqlai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axonops%2Fcqlai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axonops%2Fcqlai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/axonops","download_url":"https://codeload.github.com/axonops/cqlai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axonops%2Fcqlai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31509941,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T03:10:19.677Z","status":"ssl_error","status_checked_at":"2026-04-07T03:10:13.982Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","apache-cassandra-tools","apachecassandra","cassandra-cql","cassandra-database","cassandra-db","cql","cqlsh","database-client","database-tools","dba","developer-tools","go","golang","llm","natural-language","terminal","tui"],"created_at":"2025-09-02T20:14:10.294Z","updated_at":"2026-04-07T11:01:25.298Z","avatar_url":"https://github.com/axonops.png","language":"Go","readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"./assets/cqlai-logo.svg\" alt=\"CQLAI Logo\" width=\"400\"\u003e\n\n  # CQLAI - Modern Cassandra® CQL Shell\n\n  [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n  [![Go Version](https://img.shields.io/github/go-mod/go-version/axonops/cqlai)](https://golang.org/)\n  [![GitHub Issues](https://img.shields.io/github/issues/axonops/cqlai)](https://github.com/axonops/cqlai/issues)\n  [![GitHub Discussions](https://img.shields.io/github/discussions/axonops/cqlai)](https://github.com/axonops/cqlai/discussions)\n  [![GitHub Stars](https://img.shields.io/github/stars/axonops/cqlai)](https://github.com/axonops/cqlai/stargazers)\n\u003c/div\u003e\n\n**CQLAI** is a fast, portable interactive terminal for Cassandra (CQL), built in Go. It provides a modern, user-friendly alternative to `cqlsh` with an advanced terminal UI, client-side command parsing, and enhanced productivity features.\n\n**AI features are completely optional** - CQLAI works perfectly as a standalone CQL shell without any AI configuration or API keys.\n\n\u003cdiv align=\"center\"\u003e\n  \u003cvideo src=\"https://github.com/user-attachments/assets/334bd302-3152-4f48-9d2d-ed617e8d86d3\" controls width=\"100%\" style=\"max-width: 800px;\"\u003e\n    Your browser does not support the video tag.\n  \u003c/video\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n### 🎁 100% Free \u0026 Open Source\n**No hidden costs • No premium tiers • No license keys**\n\nCommunity-driven development with full transparency\n\n\u003c/div\u003e\n\nThe original cqlsh command in the [Apache Cassandra](https://cassandra.apache.org/) project is written in Python which requires Python to be installed on the system. cqlai is compiled to a single executable binary, requiring no external dependencies. This project provides binaries for the following platforms:\n\n- Linux x86-64\n- macOS x86-64\n- Windows x86-64\n- Linux aarch64\n- macOS arm64\n\n\nIt is built with [Bubble Tea](https://github.com/charmbracelet/bubbletea), [Bubbles](https://github.com/charmbracelet/bubbles), and [Lip Gloss](https://github.com/charmbracelet/lipgloss) for the beautiful terminal UI. A big shout out to the cassandra gocql driver team for implementing the latest Cassandra functionalities [gocql](https://github.com/apache/cassandra-gocql-driver)\n\n---\n\n## 📑 Table of Contents\n\n- [📊 Project Status](#-project-status)\n- [✨ Features](#-features)\n- [🔧 Installation](#-installation)\n- [📚 Usage](#-usage)\n  - [Interactive Mode](#interactive-mode)\n  - [Command-Line Options](#command-line-options)\n  - [Batch Mode Examples](#batch-mode-examples)\n  - [Basic Commands](#basic-commands)\n  - [Keyboard Shortcuts](#keyboard-shortcuts)\n  - [Tab Completion](#tab-completion)\n- [⚙️ Available Commands](#️-available-commands)\n  - [CQL Commands](#cql-commands)\n  - [Meta-Commands](#meta-commands)\n  - [AI Commands](#ai-commands)\n- [🛠️ Configuration](#️-configuration)\n  - [Configuration Precedence](#configuration-precedence)\n  - [CQLSHRC Compatibility](#cqlshrc-compatibility)\n  - [CQLAI JSON Configuration](#cqlai-json-configuration)\n  - [AI Provider Configuration](#ai-provider-configuration)\n    - [OpenAI](#openai-gpt-4--gpt-35)\n    - [Anthropic](#anthropic-claude-3)\n    - [Google Gemini](#google-gemini)\n    - [Synthetic](#synthetic-multiple-open-source-models)\n    - [Ollama](#ollama-local-models)\n    - [OpenRouter](#openrouter-multiple-models)\n    - [Mock Provider](#mock-provider-for-testing)\n- [🤖 AI-Powered Query Generation](#-ai-powered-query-generation)\n- [📦 Apache Parquet Support](#-apache-parquet-support)\n- [⚠️ Known Limitations](#️-known-limitations)\n- [🔨 Development](#-development)\n- [🏗️ Technology Stack](#️-technology-stack)\n- [🙏 Acknowledgements](#-acknowledgements)\n- [💬 Community \u0026 Support](#-community--support)\n- [📝 License](#-license)\n- [⚖️ Legal Notices](#️-legal-notices)\n\n---\n\n## 📊 Project Status\n\n**CQLAI is production-ready** and actively used in development, testing, and production environments with Cassandra clusters. The tool provides a complete, stable alternative to `cqlsh` with enhanced features and performance.\n\n### What Works\n- All core CQL operations and queries\n- Complete meta-command support (`DESCRIBE`, `SHOW`, `CONSISTENCY`, etc.)\n- Client-side command parsing (lightweight, no ANTLR dependency)\n- Data import/export with `COPY TO/FROM` (CSV and Parquet formats)\n- SSL/TLS connections and authentication\n- User-Defined Types (UDTs) and complex data types\n- Batch mode for scripting and automation\n- Apache Parquet format support for efficient data interchange\n- Tab completion for CQL keywords, tables, columns, and keyspaces\n- **Optional**: AI-powered query generation ([OpenAI](https://openai.com/), [Anthropic](https://www.anthropic.com/), [Google Gemini](https://ai.google.dev/), [Synthetic](https://synthetic.new/))\n\n### Coming Soon\n- Enhanced AI context awareness\n- Cassandra MCP service\n- Additional performance optimizations\n\nWe encourage you to **try CQLAI today** and help shape its development! Your feedback and contributions are invaluable in making this the best CQL shell for the Cassandra community. Please [report issues](https://github.com/axonops/cqlai/issues) or [contribute](https://github.com/axonops/cqlai/pulls).\n\n---\n\n## ✨ Features\n\n- **Interactive CQL Shell:** Execute any CQL query that your Cassandra cluster supports.\n- **Rich Terminal UI:**\n    - A multi-layer, full-screen terminal application with alternate screen buffer (preserves terminal history).\n    - Virtualized, scrollable table for results with automatic data loading, preventing memory overload from large queries.\n    - Advanced navigation modes with vim-style keyboard shortcuts.\n    - Full mouse support including wheel scrolling and text selection.\n    - Sticky footer/status bar showing connection details, query latency, and session status (consistency, tracing).\n    - Modal overlays for history, help, and command completion.\n- **Apache Parquet Support:**\n    - High-performance columnar data format for analytics and machine learning workflows.\n    - Export Cassandra tables to Parquet files with `COPY TO` command.\n    - Import Parquet files into Cassandra with automatic schema inference.\n    - Partitioned datasets with Hive-style directory structures.\n    - TimeUUID / timestamp virtual columns for intelligent time-based partitioning.\n    - Support for all Cassandra data types including UDTs, collections, and vectors.\n- **Optional AI-Powered Query Generation:**\n    - Natural language to CQL conversion using AI providers ([OpenAI](https://openai.com/), [Anthropic](https://www.anthropic.com/), [Google Gemini](https://ai.google.dev/), [Synthetic](https://synthetic.new/)).\n    - Schema-aware query generation with automatic context.\n    - Safe preview and confirmation before execution.\n    - Support for complex operations including DDL and DML.\n    - **Requires API key configuration** - not needed for core functionality.\n- **Configuration:**\n    - Simple configuration via `cqlai.json` in current directory or `~/.cqlai.json`.\n    - Support for SSL/TLS connections with certificate authentication.\n- **Single Binary:** Distributed as a single, static binary with no external dependencies. Fast startup and small footprint.\n\n## 🔧 Installation\n\nYou can install `cqlai` in several ways. For detailed instructions including package managers (APT, YUM) and Docker, see the [Installation Guide](docs/INSTALLATION.md).\n\n### Pre-compiled Binaries\n\nDownload the appropriate binary for your OS and architecture from the [**Releases**](https://github.com/axonops/cqlai/releases) page.\n\n\n### Using Go\n\n```bash\ngo install github.com/axonops/cqlai/cmd/cqlai@latest\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/axonops/cqlai.git\ncd cqlai\ngo build -o cqlai cmd/cqlai/main.go\n```\n\n### Using Docker\n\n```bash\n# Build the image\ndocker build -t cqlai .\n\n# Run the container\ndocker run -it --rm --name cqlai-session cqlai --host your-cassandra-host\n```\n\n## 📚 Usage\n\n### Interactive Mode\n\nConnect to a Cassandra host:\n```bash\n# With password on command line (not recommended - visible in ps)\ncqlai --host 127.0.0.1 --port 9042 --username cassandra --password cassandra\n\n# With password prompt (secure - password hidden)\ncqlai --host 127.0.0.1 --port 9042 -u cassandra\n# Password: [hidden input]\n\n# Using environment variable (secure for scripts/containers)\nexport CQLAI_PASSWORD=cassandra\ncqlai --host 127.0.0.1 -u cassandra\n```\n\nOr use a configuration file:\n```bash\n# Create configuration from example\ncp cqlai.json.example cqlai.json\n# Edit cqlai.json with your settings, then run:\ncqlai\n```\n\n### Command-Line Options\n\n```bash\ncqlai [options] [host [port]]\n```\n\n**Note:** Positional arguments are supported for `cqlsh` compatibility. `cqlai 192.168.1.100 9042` is equivalent to `cqlai --host 192.168.1.100 --port 9042`.\n\n#### Connection Options\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--host \u003chost\u003e` | | Cassandra host (overrides config) |\n| `--port \u003cport\u003e` | | Cassandra port (overrides config) |\n| `--keyspace \u003ckeyspace\u003e` | `-k` | Default keyspace (overrides config) |\n| `--username \u003cusername\u003e` | `-u` | Username for authentication |\n| `--password \u003cpassword\u003e` | `-p` | Password for authentication* |\n| `--ssl` | | Enable SSL/TLS connection |\n| `--consistency \u003clevel\u003e` | | Default consistency level (e.g., ONE, QUORUM, LOCAL_QUORUM) |\n| `--no-confirm` | | Disable confirmation prompts for destructive commands (DROP, DELETE, TRUNCATE) |\n| `--connect-timeout \u003cseconds\u003e` | | Connection timeout (default: 10) |\n| `--request-timeout \u003cseconds\u003e` | | Request timeout (default: 10) |\n| `--debug` | | Enable debug logging |\n\n*\\*Note: Password can be provided in three ways:*\n1. *Command line with `-p` (not recommended - visible in process list)*\n2. *Interactive prompt when `-u` is used without `-p` (recommended)*\n3. *Environment variable `CQLAI_PASSWORD` (good for automation)*\n\n#### Batch Mode Options\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--execute \u003cstatement\u003e` | `-e` | Execute CQL statement and exit |\n| `--file \u003cfile\u003e` | `-f` | Execute CQL from file and exit |\n| `--format \u003cformat\u003e` | | Output format: ascii, json, csv, table |\n| `--no-header` | | Don't output column headers (CSV) |\n| `--field-separator \u003csep\u003e` | | Field separator for CSV (default: ,) |\n| `--page-size \u003cn\u003e` | | Rows per batch (default: 100) |\n\n#### General Options\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--config-file \u003cpath\u003e` | | Path to config file (overrides default locations) |\n| `--help` | `-h` | Show help message |\n| `--version` | `-v` | Print version and exit |\n\n### Batch Mode Examples\n\nExecute CQL statements non-interactively (compatible with cqlsh):\n\n```bash\n# Execute a single statement\ncqlai -e \"SELECT * FROM system_schema.keyspaces;\"\n\n# Execute from a file\ncqlai -f script.cql\n\n# Pipe input\necho \"SELECT * FROM users;\" | cqlai\n\n# Control output format\ncqlai -e \"SELECT * FROM users;\" --format json\ncqlai -e \"SELECT * FROM users;\" --format csv --no-header\n\n# Control pagination size\ncqlai -e \"SELECT * FROM large_table;\" --page-size 50\n```\n\n### Basic Commands\n\n- **Execute CQL:** Type any CQL statement and press Enter.\n- **Meta-Commands:**\n  ```sql\n  DESCRIBE KEYSPACES;\n  USE my_keyspace;\n  DESCRIBE TABLES;\n  CONSISTENCY QUORUM;\n  TRACING ON;\n  PAGING 50;\n  EXPAND ON;  -- Vertical output mode\n  SOURCE 'script.cql';  -- Execute CQL script\n  ```\n- **AI-Powered Query Generation:**\n  ```sql\n  .ai What keyspaces are there?\n  .ai What columns does the users table have?\n  .ai create a table for storing product inventory\n  .ai delete orders older than 1 year from the orders table\n  ```\n\n### Keyboard Shortcuts\n\n#### Navigation \u0026 Control\n| Shortcut | Action | macOS Alternative |\n|----------|--------|-------------------|\n| `↑`/`↓` | Navigate command history | Same |\n| `Ctrl+P`/`Ctrl+N` | Previous/Next in command history | Same |\n| `Alt+N` | Move to next line in history | `Option+N` |\n| `Tab` | Autocomplete commands and table/keyspace names | Same |\n| `Ctrl+C` | Clear input / Cancel pagination / Cancel operation (twice to exit) | `⌘+C` or `Ctrl+C` |\n| `Ctrl+D` | Exit application | `⌘+D` or `Ctrl+D` |\n| `Ctrl+R` | Search command history | `⌘+R` or `Ctrl+R` |\n| `Esc` | Toggle navigation mode / Cancel pagination / Close modals | Same |\n| `Enter` | Execute command / Load next page (during pagination) | Same |\n\n#### Text Editing\n| Shortcut | Action | macOS Alternative |\n|----------|--------|-------------------|\n| `Ctrl+A` | Jump to beginning of line | Same |\n| `Ctrl+E` | Jump to end of line | Same |\n| `Ctrl+Left`/`Ctrl+Right` | Jump by word (or 20 chars) | Same |\n| `PgUp`/`PgDn` (in input) | Page left/right in long queries | `Fn+↑`/`Fn+↓` |\n| `Ctrl+K` | Cut from cursor to end of line | Same |\n| `Ctrl+U` | Cut from beginning to cursor | Same |\n| `Ctrl+W` | Cut word backward | Same |\n| `Alt+D` | Delete word forward | `Option+D` |\n| `Ctrl+Y` | Paste previously cut text | Same |\n\n#### View Switching\n| Shortcut | Action |\n|----------|--------|\n| `F2` | Switch to query/history view |\n| `F3` | Switch to table view |\n| `F4` | Switch to trace view (when tracing enabled) |\n| `F5` | Switch to AI conversation view |\n| `F6` | Toggle column data types in table headers |\n\n#### Scrolling \u0026 Table Navigation\n| Shortcut | Action | macOS Alternative |\n|----------|--------|-------------------|\n| `PgUp`/`PgDn` | Scroll viewport by page / Load more data when available | `Fn+↑`/`Fn+↓` |\n| `Space` | Load next page when more data available | Same |\n| `Enter` (empty input) | Load next page when more data available | Same |\n| `Alt+↑`/`Alt+↓` | Scroll viewport by single row (respects row boundaries) | `Option+↑`/`Option+↓` |\n| `Alt+←`/`Alt+→` | Scroll table horizontally (wide tables) | `Option+←`/`Option+→` |\n| `↑`/`↓` | Navigate table rows (when in navigation mode) | Same |\n\n#### Navigation Mode (Table/Trace Views)\nPress `Esc` to toggle navigation mode when viewing tables or traces.\n\n| Shortcut | Action in Navigation Mode |\n|----------|---------------------------|\n| `j` / `k` | Scroll down/up by single line |\n| `d` / `u` | Scroll down/up by half page |\n| `g` / `G` | Jump to top/bottom of results |\n| `\u003c` / `\u003e` | Scroll left/right by 10 columns |\n| `{` / `}` | Scroll left/right by 50 columns |\n| `0` / `$` | Jump to first/last column |\n| `Esc` | Exit navigation mode / Cancel pagination if active |\n\n#### Mouse Support\n| Action | Function |\n|--------|----------|\n| Mouse Wheel | Scroll vertically with automatic data loading |\n| Alt+Mouse Wheel | Scroll horizontally in tables |\n| Shift+Mouse Wheel | Scroll horizontally (alternative) |\n| Ctrl+Mouse Wheel | Scroll horizontally (alternative) |\n| Shift+Click+Drag | Select text for copying |\n| Ctrl+Shift+C | Copy selected text to clipboard |\n| Middle Click | Paste from selection buffer (Linux/Unix) |\n\n**Note for macOS Users:**\n- Most `Ctrl` shortcuts work as-is on macOS, but you can also use `⌘` (Command) key as an alternative\n- `Alt` key is labeled as `Option` on Mac keyboards\n- Function keys (F1-F6) may require holding `Fn` key depending on your Mac settings\n\n### Tab Completion\n\nCQLAI provides intelligent, context-aware tab completion to speed up your workflow. Press `Tab` at any point to see available completions.\n\n#### What Can Be Completed\n\n**CQL Keywords \u0026 Commands:**\n- All CQL keywords: `SELECT`, `INSERT`, `CREATE`, `ALTER`, `DROP`, etc.\n- Meta-commands: `DESCRIBE`, `CONSISTENCY`, `COPY`, `SHOW`, etc.\n- Data types: `TEXT`, `INT`, `UUID`, `TIMESTAMP`, etc.\n- Consistency levels: `ONE`, `QUORUM`, `ALL`, `LOCAL_QUORUM`, etc.\n\n**Schema Objects:**\n- Keyspace names\n- Table names (within current keyspace)\n- Column names (when context allows)\n- User-defined type names\n- Function and aggregate names\n- Index names\n\n**Context-Aware Completions:**\n```sql\n-- After SELECT, suggests column names and keywords\nSELECT \u003cTab\u003e           -- Shows: *, column names, DISTINCT, JSON, etc.\n\n-- After FROM, suggests table names\nSELECT * FROM \u003cTab\u003e    -- Shows: available tables in current keyspace\n\n-- After USE, suggests keyspace names\nUSE \u003cTab\u003e              -- Shows: available keyspaces\n\n-- After DESCRIBE, suggests object types\nDESCRIBE \u003cTab\u003e         -- Shows: KEYSPACE, TABLE, TYPE, etc.\n\n-- After consistency command\nCONSISTENCY \u003cTab\u003e      -- Shows: ONE, QUORUM, ALL, etc.\n```\n\n**File Path Completion:**\n```sql\n-- For commands that accept file paths\nSOURCE '\u003cTab\u003e          -- Shows: files in current directory\nSOURCE '/path/\u003cTab\u003e    -- Shows: files in /path/\n```\n\n#### Completion Behavior\n\n- **Case Insensitive:** Type `sel\u003cTab\u003e` to get `SELECT`\n- **Partial Matching:** Type part of a word and press Tab\n- **Multiple Matches:** When multiple completions are available:\n  - First Tab: Shows inline completion if unique\n  - Second Tab: Shows all available options in a modal\n- **Smart Filtering:** Completions are filtered based on current context\n- **Escape to Cancel:** Press `Esc` to close the completion modal\n\n#### Examples\n\n```sql\n-- Complete table name\nSELECT * FROM us\u003cTab\u003e\n-- Completes to: SELECT * FROM users\n\n-- Complete consistency level\nCONSISTENCY LOC\u003cTab\u003e\n-- Shows: LOCAL_ONE, LOCAL_QUORUM, LOCAL_SERIAL\n\n-- Complete column names after SELECT\nSELECT id, na\u003cTab\u003e FROM users\n-- Completes to: SELECT id, name FROM users\n\n-- Complete file paths for SOURCE command\nSOURCE 'sche\u003cTab\u003e\n-- Completes to: SOURCE 'schema.cql'\n\n-- Complete COPY command options\nCOPY users TO 'file.csv' WITH \u003cTab\u003e\n-- Shows: HEADER, DELIMITER, NULLVAL, PAGESIZE, etc.\n\n-- Show all tables when multiple exist\nSELECT * FROM \u003cTab\u003e\n-- Shows modal with: users, orders, products, etc.\n```\n\n#### Tips for Effective Use\n\n1. **Use Tab liberally:** The completion system is smart and context-aware\n2. **Type minimum characters:** Often 2-3 characters are enough to get unique completion\n3. **Use for discovery:** Press Tab on empty input to see what's available\n4. **File paths:** Remember to include quotes for file path completion\n5. **Navigate completions:** Use arrow keys to select from multiple options\n\n## ⚙️ Available Commands\n\nCQLAI supports all standard CQL commands plus additional meta-commands for enhanced functionality.\n\n### CQL Commands\nExecute any valid CQL statement supported by your Cassandra cluster:\n- DDL: `CREATE`, `ALTER`, `DROP` (KEYSPACE, TABLE, INDEX, etc.)\n- DML: `SELECT`, `INSERT`, `UPDATE`, `DELETE`\n- DCL: `GRANT`, `REVOKE`\n- Other: `USE`, `TRUNCATE`, `BEGIN BATCH`, etc.\n\n### Meta-Commands\n\nMeta-commands provide additional functionality beyond standard CQL:\n\n#### Session Management\n- **CONSISTENCY** `\u003clevel\u003e` - Set consistency level (ONE, QUORUM, ALL, etc.)\n  ```sql\n  CONSISTENCY QUORUM\n  CONSISTENCY LOCAL_ONE\n  ```\n\n- **PAGING** `\u003csize\u003e` | OFF - Set result paging size\n  ```sql\n  PAGING 1000\n  PAGING OFF\n  ```\n\n- **TRACING** ON | OFF - Enable/disable query tracing\n  ```sql\n  TRACING ON\n  SELECT * FROM users;\n  TRACING OFF\n  ```\n\n- **OUTPUT** [FORMAT] - Set output format\n  ```sql\n  OUTPUT          -- Show current format\n  OUTPUT TABLE    -- Table format (default)\n  OUTPUT JSON     -- JSON format\n  OUTPUT EXPAND   -- Expanded vertical format\n  OUTPUT ASCII    -- ASCII table format\n  ```\n\n#### Schema Description\n- **DESCRIBE** - Show schema information\n  ```sql\n  DESCRIBE KEYSPACES                    -- List all keyspaces\n  DESCRIBE KEYSPACE \u003cname\u003e              -- Show keyspace definition\n  DESCRIBE TABLES                       -- List tables in current keyspace\n  DESCRIBE TABLE \u003cname\u003e                 -- Show table structure\n  DESCRIBE TYPES                        -- List user-defined types\n  DESCRIBE TYPE \u003cname\u003e                  -- Show UDT definition\n  DESCRIBE FUNCTIONS                    -- List user functions\n  DESCRIBE FUNCTION \u003cname\u003e              -- Show function definition\n  DESCRIBE AGGREGATES                   -- List user aggregates\n  DESCRIBE AGGREGATE \u003cname\u003e             -- Show aggregate definition\n  DESCRIBE MATERIALIZED VIEWS           -- List materialized views\n  DESCRIBE MATERIALIZED VIEW \u003cname\u003e     -- Show view definition\n  DESCRIBE INDEX \u003cname\u003e                 -- Show index definition\n  DESCRIBE CLUSTER                      -- Show cluster information\n  DESC \u003ckeyspace\u003e.\u003ctable\u003e               -- Shorthand for table description\n  ```\n\n#### Data Export/Import\n- **COPY TO** - Export table data to CSV or Parquet file\n  ```sql\n  -- Basic export to CSV\n  COPY users TO 'users.csv'\n\n  -- Export to Parquet format (auto-detected by extension)\n  COPY users TO 'users.parquet'\n\n  -- Export to Parquet with explicit format and compression\n  COPY users TO 'data.parquet' WITH FORMAT='PARQUET' AND COMPRESSION='SNAPPY'\n\n  -- Export specific columns\n  COPY users (id, name, email) TO 'users_partial.csv'\n\n  -- Export with options\n  COPY users TO 'users.csv' WITH HEADER = TRUE AND DELIMITER = '|'\n\n  -- Export to stdout\n  COPY users TO STDOUT WITH HEADER = TRUE\n\n  -- Available options:\n  -- FORMAT = 'CSV'/'PARQUET' -- Output format (default: CSV, auto-detected)\n  -- HEADER = TRUE/FALSE      -- Include column headers (CSV only)\n  -- DELIMITER = ','          -- Field delimiter (CSV only)\n  -- NULLVAL = 'NULL'        -- String to use for NULL values\n  -- PAGESIZE = 1000         -- Rows per page for large exports\n  -- COMPRESSION = 'SNAPPY'  -- For Parquet: SNAPPY, GZIP, ZSTD, LZ4, NONE\n  -- CHUNKSIZE = 10000       -- Rows per chunk for Parquet\n  ```\n\n- **COPY FROM** - Import CSV or Parquet data into table\n  ```sql\n  -- Basic import from CSV file\n  COPY users FROM 'users.csv'\n\n  -- Import from Parquet file (auto-detected)\n  COPY users FROM 'users.parquet'\n\n  -- Import from Parquet with explicit format\n  COPY users FROM 'data.parquet' WITH FORMAT='PARQUET'\n\n  -- Import with header row (CSV)\n  COPY users FROM 'users.csv' WITH HEADER = TRUE\n\n  -- Import specific columns\n  COPY users (id, name, email) FROM 'users_partial.csv'\n\n  -- Import from stdin\n  COPY users FROM STDIN\n\n  -- Import with custom options\n  COPY users FROM 'users.csv' WITH HEADER = TRUE AND DELIMITER = '|' AND NULLVAL = 'N/A'\n\n  -- Available options:\n  -- HEADER = TRUE/FALSE      -- First row contains column names\n  -- DELIMITER = ','          -- Field delimiter\n  -- NULLVAL = 'NULL'        -- String representing NULL values\n  -- MAXROWS = -1            -- Maximum rows to import (-1 = unlimited)\n  -- SKIPROWS = 0            -- Number of initial rows to skip\n  -- MAXPARSEERRORS = -1     -- Max parsing errors allowed (-1 = unlimited)\n  -- MAXINSERTERRORS = 1000  -- Max insert errors allowed\n  -- MAXBATCHSIZE = 20       -- Max rows per batch insert\n  -- MAXREQUESTS = 6         -- Concurrent batch workers (parallelism)\n  -- MINBATCHSIZE = 2        -- Min rows per batch insert\n  -- CHUNKSIZE = 5000        -- Rows between progress updates\n  -- ENCODING = 'UTF8'       -- File encoding\n  -- QUOTE = '\"'             -- Quote character for strings\n  ```\n\n- **CAPTURE** - Capture query output to file (continuous recording)\n  ```sql\n  CAPTURE 'output.txt'          -- Start capturing to text file\n  CAPTURE JSON 'output.json'    -- Capture as JSON\n  CAPTURE CSV 'output.csv'      -- Capture as CSV\n  SELECT * FROM users;\n  CAPTURE OFF                   -- Stop capturing\n  ```\n\n- **SAVE** - Save displayed query results to file (without re-executing)\n  ```sql\n  -- First run a query\n  SELECT * FROM users WHERE status = 'active';\n\n  -- Then save the displayed results in various formats:\n  SAVE                           -- Interactive dialog (choose format \u0026 filename)\n  SAVE 'users.csv'               -- Save to CSV (format auto-detected)\n  SAVE 'users.json'              -- Save to JSON (format auto-detected)\n  SAVE 'users.txt' ASCII         -- Save as ASCII table\n  SAVE 'data.csv' CSV            -- Explicitly specify format\n\n  -- Key differences from CAPTURE:\n  -- - SAVE exports the currently displayed results\n  -- - No need to re-run the query\n  -- - Preserves exact data shown in terminal\n  -- - Works with paginated results (saves only loaded pages)\n  ```\n\n#### Information Display\n- **SHOW** - Display session information\n  ```sql\n  SHOW VERSION          -- Show Cassandra version\n  SHOW HOST            -- Show current connection details\n  SHOW SESSION         -- Show all session settings\n  ```\n\n- **EXPAND** ON | OFF - Toggle expanded output mode\n  ```sql\n  EXPAND ON            -- Vertical output (one field per line)\n  SELECT * FROM users WHERE id = 1;\n  EXPAND OFF           -- Normal table output\n  ```\n\n#### Script Execution\n- **SOURCE** - Execute CQL scripts from file\n  ```sql\n  SOURCE 'schema.cql'           -- Execute script\n  SOURCE '/path/to/script.cql'  -- Absolute path\n  ```\n\n#### Help\n- **HELP** - Display command help\n  ```sql\n  HELP                 -- Show all commands\n  HELP DESCRIBE        -- Help for specific command\n  HELP CONSISTENCY     -- Help for consistency levels\n  ```\n\n### AI Commands\n- **.ai** `\u003cnatural language query\u003e` - Generate CQL from natural language\n  ```sql\n  .ai show all users with active status\n  .ai create a table for storing user sessions\n  .ai find orders placed in the last 30 days\n  ```\n\n## 🛠️ Configuration\n\nCQLAI supports multiple configuration methods for maximum flexibility and compatibility with existing Cassandra setups.\n\n### Configuration Precedence\n\nConfiguration sources are loaded in the following order (later sources override earlier ones):\n\n1. **CQLSHRC files** (for compatibility with existing cqlsh setups)\n   - `~/.cassandra/cqlshrc` (standard location)\n   - `~/.cqlshrc` (alternative location)\n   - `$CQLSH_RC` (if environment variable is set)\n\n2. **CQLAI JSON configuration files**\n   - `./cqlai.json` (current directory)\n   - `~/.cqlai.json` (user home directory)\n   - `~/.config/cqlai/config.json` (XDG config directory)\n\n3. **Environment variables**\n   - `CQLAI_HOST`, `CQLAI_PORT`, `CQLAI_KEYSPACE`, etc.\n   - `CASSANDRA_HOST`, `CASSANDRA_PORT` (for compatibility)\n\n4. **Command-line flags** (highest priority)\n   - `--host`, `--port`, `--keyspace`, `--username`, `--password`, etc.\n\n### CQLSHRC Compatibility\n\nCQLAI can read standard CQLSHRC files used by the traditional `cqlsh` tool, making migration seamless.\n\n**Supported CQLSHRC sections:**\n- `[connection]` - hostname, port, ssl settings\n- `[authentication]` - keyspace, credentials file path\n- `[auth_provider]` - authentication module and username\n- `[ssl]` - SSL/TLS certificate configuration\n\n**Example CQLSHRC file:**\n```ini\n; ~/.cassandra/cqlshrc\n[connection]\nhostname = cassandra.example.com\nport = 9042\nssl = true\n\n[authentication]\nkeyspace = my_keyspace\ncredentials = ~/.cassandra/credentials\n\n[ssl]\ncertfile = ~/certs/ca.pem\nuserkey = ~/certs/client-key.pem\nusercert = ~/certs/client-cert.pem\nvalidate = true\n```\n\nSee [CQLSHRC_SUPPORT.md](docs/CQLSHRC_SUPPORT.md) for complete CQLSHRC compatibility details.\n\n### CQLAI JSON Configuration\n\nFor advanced features and AI configuration, CQLAI uses its own JSON format:\n\n**Example `cqlai.json`:**\n```json\n{\n  \"host\": \"127.0.0.1\",\n  \"port\": 9042,\n  \"keyspace\": \"\",\n  \"username\": \"cassandra\",\n  \"password\": \"cassandra\",\n  \"requireConfirmation\": true,\n  \"consistency\": \"LOCAL_ONE\",\n  \"pageSize\": 100,\n  \"maxMemoryMB\": 10,\n  \"connectTimeout\": 10,\n  \"requestTimeout\": 10,\n  \"debug\": false,\n  \"historyFile\": \"~/.cqlai/history\",\n  \"aiHistoryFile\": \"~/.cqlai/ai_history\",\n  \"ssl\": {\n    \"enabled\": false,\n    \"certPath\": \"/path/to/client-cert.pem\",\n    \"keyPath\": \"/path/to/client-key.pem\",\n    \"caPath\": \"/path/to/ca-cert.pem\",\n    \"hostVerification\": true,\n    \"insecureSkipVerify\": false\n  },\n  \"ai\": {\n    \"provider\": \"openai\",\n    \"apiKey\": \"sk-...\",\n    \"model\": \"gpt-4-turbo-preview\"\n  }\n}\n```\n\n**Note:** You can also use the `url` field to override the API endpoint for OpenAI-compatible APIs:\n```json\n{\n  \"ai\": {\n    \"provider\": \"openai\",\n    \"apiKey\": \"your-api-key\",\n    \"url\": \"https://api.synthetic.new/openai/v1\",\n    \"model\": \"hf:Qwen/Qwen3-235B-A22B-Instruct-2507\"\n  }\n}\n```\n\n### AI Provider Configuration\n\n**Note:** AI features are completely optional. CQLAI works as a full-featured CQL shell without any AI configuration.\n\nTo enable AI-powered query generation, configure your preferred provider in the `ai` section of your `cqlai.json` file.\n\n#### OpenAI (GPT-4 \u0026 GPT-3.5)\n\nUse OpenAI for high-quality, general-purpose query generation. Requires an OpenAI API key.\n\n- **Get API Key:** [platform.openai.com/api-keys](https://platform.openai.com/api-keys)\n- **Recommended Models:**\n  - `gpt-4-turbo-preview` (default, recommended for best results)\n  - `gpt-3.5-turbo` (faster, more cost-effective)\n\n**Configuration:**\n```json\n{\n  \"ai\": {\n    \"provider\": \"openai\",\n    \"apiKey\": \"sk-...\",\n    \"model\": \"gpt-4-turbo-preview\"\n  }\n}\n```\n\n#### Anthropic (Claude 3)\n\nUse Anthropic for powerful, context-aware models. Ideal for complex queries and reasoning. Requires an Anthropic API key.\n\n- **Get API Key:** [console.anthropic.com/settings/keys](https://console.anthropic.com/settings/keys)\n- **Recommended Models:**\n  - `claude-3-opus-20240229` (most powerful)\n  - `claude-3-sonnet-20240229` (default, balanced performance)\n  - `claude-3-haiku-20240307` (fastest)\n\n**Configuration:**\n```json\n{\n  \"ai\": {\n    \"provider\": \"anthropic\",\n    \"apiKey\": \"sk-ant-...\",\n    \"model\": \"claude-3-sonnet-20240229\"\n  }\n}\n```\n\n#### Google Gemini\n\nUse Google Gemini for a fast and capable model from Google. Requires a Google AI Studio API key.\n\n- **Get API Key:** [aistudio.google.com/app/apikey](https://aistudio.google.com/app/apikey)\n- **Recommended Model:**\n  - `gemini-pro` (default)\n\n**Configuration:**\n```json\n{\n  \"ai\": {\n    \"provider\": \"gemini\",\n    \"apiKey\": \"...\",\n    \"model\": \"gemini-pro\"\n  }\n}\n```\n\n#### Synthetic (Multiple Open-Source Models)\n\nUse Synthetic to access a vast selection of open-source AI models at very reasonable prices. Synthetic provides an OpenAI-compatible API that makes it easy to work with various open-source models.\n\n- **Get Started:** [synthetic.new](https://synthetic.new/)\n- **API Documentation:** [dev.synthetic.new/docs](https://dev.synthetic.new/docs)\n- **Recommended Model:**\n  - `hf:Qwen/Qwen3-235B-A22B-Instruct-2507` (recommended, though we haven't extensively tested all models)\n- **Available Models:** See [Always-On Models](https://dev.synthetic.new/docs/api/models#always-on-models)\n\n**Configuration:**\n```json\n{\n  \"ai\": {\n    \"provider\": \"openai\",\n    \"apiKey\": \"your-synthetic-api-key\",\n    \"url\": \"https://api.synthetic.new/openai/v1\",\n    \"model\": \"hf:Qwen/Qwen3-235B-A22B-Instruct-2507\"\n  }\n}\n```\n\n**Key Benefits:**\n- Access to a wide variety of open-source models\n- Cost-effective pricing\n- OpenAI-compatible API for easy integration\n- No vendor lock-in\n\n**Notes:**\n- Synthetic presents an OpenAI-compatible interface, so you use the `openai` provider in your configuration\n- The `url` field overrides the default OpenAI endpoint to point to Synthetic\n- API key is required - obtain one from [synthetic.new](https://synthetic.new/)\n\n#### Ollama (Local Models)\n\nUse Ollama for running AI models locally or connecting to OpenAI-compatible APIs. Ollama allows you to run powerful language models on your own hardware without sending data to external services.\n\n- **Get Started:** [ollama.ai](https://ollama.ai)\n- **Recommended Models:**\n  - `llama3.2` (Meta's Llama 3.2)\n  - `codellama` (Code-specialized Llama)\n  - `mistral` (Mistral AI's model)\n  - `qwen2.5-coder` (Alibaba's code model)\n\n**Configuration:**\n```json\n{\n  \"ai\": {\n    \"provider\": \"ollama\",\n    \"model\": \"llama3.2\",\n    \"url\": \"http://localhost:11434/v1\"\n  }\n}\n```\n\n**Environment Variables:**\n- `OLLAMA_URL` - Custom Ollama server URL (default: `http://localhost:11434/v1`)\n- `OLLAMA_MODEL` - Model to use\n\n**Notes:**\n- No API key required for local Ollama installations\n- Supports custom URLs for remote Ollama servers or OpenAI-compatible endpoints\n- The `url` field can be set at the top level (`ai.url`) or provider-specific (`ai.ollama.url`)\n\n#### OpenRouter (Multiple Models)\n\nUse OpenRouter to access multiple AI models through a single API. OpenRouter provides access to various models from different providers.\n\n- **Get API Key:** [openrouter.ai/keys](https://openrouter.ai/keys)\n- **Available Models:** See [openrouter.ai/models](https://openrouter.ai/models)\n\n**Configuration:**\n```json\n{\n  \"ai\": {\n    \"provider\": \"openrouter\",\n    \"apiKey\": \"sk-or-...\",\n    \"model\": \"anthropic/claude-3-sonnet\",\n    \"url\": \"https://openrouter.ai/api/v1\"\n  }\n}\n```\n\n**Environment Variables:**\n- `OPENROUTER_API_KEY` - OpenRouter API key\n- `OPENROUTER_MODEL` - Model to use\n- `OPENROUTER_URL` - Custom OpenRouter URL (default: `https://openrouter.ai/api/v1`)\n\n#### Mock Provider (for Testing)\n\nThe `mock` provider is the default and requires no API key. It's useful for testing the AI workflow or for users who don't need real AI capabilities. It generates simple, predictable queries based on keywords.\n\n**Configuration:**\n```json\n{\n  \"ai\": {\n    \"provider\": \"mock\"\n  }\n}\n```\n\n#### Using Environment Variables for API Keys and URLs\n\nFor better security, you can provide API keys and custom URLs via environment variables instead of writing them in the configuration file.\n\n**API Keys:**\n- **OpenAI:** `OPENAI_API_KEY`\n- **Anthropic:** `ANTHROPIC_API_KEY`\n- **Google Gemini:** `GEMINI_API_KEY`\n- **OpenRouter:** `OPENROUTER_API_KEY`\n\n**Custom URLs:**\n- **Ollama:** `OLLAMA_URL` (default: `http://localhost:11434/v1`)\n- **OpenRouter:** `OPENROUTER_URL` (default: `https://openrouter.ai/api/v1`)\n\nIf an environment variable is set, it will be used even if a value is present in `cqlai.json`.\n\n**Configuration Options:**\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `host` | string | `127.0.0.1` | Cassandra host address |\n| `port` | number | `9042` | Cassandra port |\n| `keyspace` | string | `\"\"` | Default keyspace to use |\n| `username` | string | `\"\"` | Authentication username |\n| `password` | string | `\"\"` | Authentication password |\n| `requireConfirmation` | boolean | `true` | Require confirmation for destructive commands (DROP, DELETE, TRUNCATE) |\n| `consistency` | string | `LOCAL_ONE` | Default consistency level (ANY, ONE, TWO, THREE, QUORUM, ALL, LOCAL_QUORUM, EACH_QUORUM, LOCAL_ONE) |\n| `pageSize` | number | `100` | Number of rows per page |\n| `maxMemoryMB` | number | `10` | Maximum memory for query results in MB |\n| `connectTimeout` | number | `10` | Connection timeout in seconds |\n| `requestTimeout` | number | `10` | Request timeout in seconds |\n| `historyFile` | string | `~/.cqlai/history` | Path to CQL command history file (supports `~` expansion) |\n| `aiHistoryFile` | string | `~/.cqlai/ai_history` | Path to AI command history file (supports `~` expansion) |\n| `debug` | boolean | `false` | Enable debug logging |\n\n### Configuration File Locations\n\nCQLAI searches for configuration files in the following locations:\n\n**CQLSHRC files:**\n1. `$CQLSH_RC` (if environment variable is set)\n2. `~/.cassandra/cqlshrc` (standard cqlsh location)\n3. `~/.cqlshrc` (alternative location)\n\n**CQLAI JSON files:**\n1. `./cqlai.json` (current working directory)\n2. `~/.cqlai.json` (user home directory)\n3. `~/.config/cqlai/config.json` (XDG config directory on Linux/macOS)\n\n### Environment Variables\n\nAll environment variables supported by CQLAI. `CQLAI_*` variables take precedence over `CASSANDRA_*` equivalents.\n\n#### Connection\n- `CQLAI_HOST` or `CASSANDRA_HOST` - Cassandra host\n- `CQLAI_PORT` or `CASSANDRA_PORT` - Cassandra port\n- `CQLAI_KEYSPACE` or `CASSANDRA_KEYSPACE` - Default keyspace\n- `CQLAI_USERNAME` or `CASSANDRA_USERNAME` - Authentication username\n- `CQLAI_PASSWORD` or `CASSANDRA_PASSWORD` - Authentication password\n- `CQLAI_CONNECT_TIMEOUT` - Connection timeout in seconds (default: 10)\n- `CQLAI_REQUEST_TIMEOUT` - Request timeout in seconds (default: 10)\n- `CQLAI_NO_CONFIRM` - Set to `true` or `1` to disable confirmation prompts for destructive commands\n- `CQLAI_DEBUG` - Set to `true` or `1` to enable debug logging\n\n#### Configuration\n- `CQLAI_CONFIG_FILE` - Path to JSON config file (overrides default locations)\n- `CQLSH_RC` - Path to custom CQLSHRC file\n\n#### Batch Mode\n- `CQLAI_EXECUTE` - CQL statement to execute (equivalent to `-e`)\n- `CQLAI_FILE` - CQL file to execute (equivalent to `-f`)\n- `CQLAI_FORMAT` - Output format: ascii, json, csv, table (default: ascii)\n- `CQLAI_NO_HEADER` - Set to `true` or `1` to omit column headers (CSV)\n- `CQLAI_FIELD_SEPARATOR` - Field separator for CSV output (default: `,`)\n- `CQLAI_PAGE_SIZE` - Pagination size (default: 100)\n- `CQLAI_MAX_MEMORY_MB` - Maximum memory for query results in MB (default: 10)\n\n#### AI Configuration\n- `CQLAI_AI_PROVIDER` or `AI_PROVIDER` - AI provider name (mock, openai, anthropic, gemini, ollama, openrouter)\n- `CQLAI_AI_API_KEY` or `AI_API_KEY` - General AI API key\n- `CQLAI_AI_MODEL` or `AI_MODEL` - General AI model name\n- `OPENAI_API_KEY` - OpenAI API key\n- `OPENAI_MODEL` - OpenAI model name\n- `ANTHROPIC_API_KEY` - Anthropic API key\n- `ANTHROPIC_MODEL` - Anthropic model name\n- `GEMINI_API_KEY` - Google Gemini API key\n- `OLLAMA_URL` - Ollama server URL (default: `http://localhost:11434/v1`)\n- `OLLAMA_MODEL` - Ollama model name\n- `OPENROUTER_API_KEY` - OpenRouter API key\n- `OPENROUTER_MODEL` - OpenRouter model name\n- `OPENROUTER_URL` - OpenRouter API URL (default: `https://openrouter.ai/api/v1`)\n\n### Migration from cqlsh\n\nIf you're migrating from `cqlsh`, CQLAI will automatically read your existing `~/.cassandra/cqlshrc` file. No changes are needed to start using CQLAI with your existing Cassandra configuration.\n\n## 🤖 AI-Powered Query Generation\n\nCQLAI includes built-in AI capabilities to convert natural language into CQL queries. Simply prefix your request with `.ai`:\n\n### Examples\n\n```sql\n-- Simple queries\n.ai show all users\n.ai find products with price less than 100\n.ai count orders from last month\n\n-- Complex operations\n.ai create a table for storing customer feedback with id, customer_id, rating, and comment\n.ai update user status to inactive where last_login is older than 90 days\n.ai delete all expired sessions\n\n-- Schema exploration\n.ai what tables are in this keyspace\n.ai describe the structure of the users table\n```\n\n### How It Works\n\n1. **Natural Language Input**: Type `.ai` followed by your request in plain English\n2. **Schema Context**: CQLAI automatically extracts your current schema to provide context\n3. **Query Generation**: The AI generates a structured query plan\n4. **Preview \u0026 Confirm**: Review the generated CQL before execution\n5. **Execute or Edit**: Choose to execute, edit, or cancel the query\n\n### Supported AI Providers\n\nConfigure your preferred AI provider in `cqlai.json`:\n\n- **[OpenAI](https://openai.com/)** (GPT-4, GPT-3.5)\n- **[Anthropic](https://www.anthropic.com/)** (Claude 3)\n- **[Google Gemini](https://ai.google.dev/)**\n- **[Synthetic](https://synthetic.new/)** (Multiple open-source models)\n- **[Ollama](https://ollama.ai/)** (Local models or OpenAI-compatible APIs)\n- **[OpenRouter](https://openrouter.ai/)** (Access to multiple models)\n- **Mock** (default, for testing without API keys)\n\n### Safety Features\n\n- **Read-only by default**: AI prefers SELECT queries unless explicitly asked to modify\n- **Dangerous operation warnings**: DROP, DELETE, TRUNCATE operations show warnings\n- **Confirmation required**: Destructive operations require additional confirmation\n- **Schema validation**: Queries are validated against your current schema\n\n### Disabling Confirmation Prompts\n\nFor automation and scripting, you can disable the confirmation prompts for destructive commands (DROP, DELETE, TRUNCATE) using any of these methods:\n\n1. **Command-line flag**:\n   ```bash\n   cqlai --no-confirm -e \"TRUNCATE my_table;\"\n   ```\n\n2. **Environment variable**:\n   ```bash\n   export CQLAI_NO_CONFIRM=true\n   cqlai -e \"DROP TABLE old_data;\"\n   ```\n\n3. **Configuration file** (`cqlai.json`):\n   ```json\n   {\n     \"requireConfirmation\": false\n   }\n   ```\n\n**Note**: Use with caution in production environments. These settings disable safety prompts that help prevent accidental data loss.\n\n## 📦 Apache Parquet Support\n\nCQLAI provides comprehensive support for Apache Parquet format, making it ideal for data analytics workflows and integration with modern data ecosystems.\n\n### Key Benefits\n\n- **Efficient Storage**: Columnar format with excellent compression (50-80% smaller than CSV)\n- **Fast Analytics**: Optimized for analytical queries in Spark, Presto, and other engines\n- **Type Preservation**: Maintains Cassandra data types including collections and UDTs\n- **Machine Learning Ready**: Direct compatibility with pandas, PyArrow, and ML frameworks\n- **Streaming Support**: Memory-efficient streaming for large datasets\n\n### Quick Examples\n\n```sql\n-- Export to Parquet (auto-detected by extension)\nCOPY users TO 'users.parquet';\n\n-- Export with compression\nCOPY events TO 'events.parquet' WITH FORMAT='PARQUET' AND COMPRESSION='ZSTD';\n\n-- Import from Parquet\nCOPY users FROM 'users.parquet';\n\n-- Capture query results in Parquet format\nCAPTURE 'results.parquet' FORMAT='PARQUET';\nSELECT * FROM large_table WHERE condition = true;\nCAPTURE OFF;\n```\n\n### Supported Features\n\n- All Cassandra primitive types (int, text, timestamp, uuid, etc.)\n- Collection types (list, set, map)\n- User-Defined Types (UDTs)\n- Frozen collections\n- Vector types for ML workloads (Cassandra 5.0+)\n- Multiple compression algorithms (Snappy, GZIP, ZSTD, LZ4)\n\nFor detailed documentation, see [Parquet Support Guide](docs/PARQUET.md).\n\n## ⚠️ Known Limitations\n\n### JSON Output (CAPTURE JSON and --format json)\n\nWhen outputting data as JSON, there are some limitations due to how the underlying gocql driver handles dynamic typing:\n\n#### NULL Values\n- **Issue**: NULL values in primitive columns (int, boolean, text, etc.) appear as zero values (`0`, `false`, `\"\"`) instead of `null`\n- **Cause**: The gocql driver returns zero values for NULLs when scanning into dynamic types (`interface{}`)\n- **Workaround**: Use `SELECT JSON` queries which return proper JSON from Cassandra server-side\n\n#### User-Defined Types (UDTs)\n- **Issue**: UDT columns appear as empty objects `{}` in JSON output\n- **Cause**: The gocql driver cannot properly unmarshal UDTs without compile-time knowledge of their structure\n- **Workaround**: Use `SELECT JSON` queries for proper UDT serialization\n\n#### Example\n```sql\n-- Regular SELECT (has limitations)\nSELECT * FROM users;  \n-- Returns: {\"id\": 1, \"age\": 0, \"active\": false}  -- age and active might be NULL\n\n-- Using SELECT JSON (preserves types correctly)\nSELECT JSON * FROM users;\n-- Returns: {\"id\": 1, \"age\": null, \"active\": null}  -- NULLs properly represented\n```\n\n**Note**: Complex types (lists, sets, maps, vectors) are properly preserved in JSON output.\n\n## 🔨 Development\n\nTo work on `cqlai`, you'll need Go (≥ 1.24).\n\n#### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/axonops/cqlai.git\ncd cqlai\n\n# Install dependencies\ngo mod download\n```\n\n#### Building\n\n```bash\n# Build a standard binary\nmake build\n\n# Build a development binary with race detection\nmake build-dev\n```\n\n#### Running Tests \u0026 Linter\n\n```bash\n# Run all tests\nmake test\n\n# Run tests with coverage report\nmake test-coverage\n\n# Run the linter\nmake lint\n\n# Run all checks (format, lint, test)\nmake check\n```\n\n\n## 🏗️ Technology Stack\n\n- **Language:** Go\n- **TUI Framework:** [Bubble Tea](https://github.com/charmbracelet/bubbletea)\n- **TUI Components:** [Bubbles](https://github.com/charmbracelet/bubbles)\n- **Styling:** [Lip Gloss](https://github.com/charmbracelet/lipgloss)\n- **Cassandra Driver:** [gocql](https://github.com/gocql/gocql)\n\n## 🙏 Acknowledgements\n\nCQLAI builds upon the foundation laid by several open-source projects, particularly Apache Cassandra. We extend our sincere gratitude to the Apache Cassandra community for their outstanding work and contributions to the field of distributed databases.\n\nApache Cassandra is a free and open-source, distributed, wide-column store, NoSQL database management system designed to handle large amounts of data across many commodity servers, providing high availability with no single point of failure.\n\n### Apache Cassandra Resources\n\n- **Official Website**: [cassandra.apache.org](https://cassandra.apache.org/)\n- **Source Code**: Available on [GitHub](https://github.com/apache/cassandra) or the Apache Git repository at `gitbox.apache.org/repos/asf/cassandra.git`\n- **Documentation**: Comprehensive guides and references available at the [Apache Cassandra website](https://cassandra.apache.org/)\n\nCQLAI incorporates and extends functionality from various Cassandra tools and utilities, enhancing them to provide a modern, efficient terminal experience for Cassandra developers and DBAs.\n\nWe encourage users to explore and contribute to the main Apache Cassandra project, as well as to provide feedback and suggestions for CQLAI through our [GitHub discussions](https://github.com/axonops/cqlai/discussions) and [issues](https://github.com/axonops/cqlai/issues) pages.\n\n## 💬 Community \u0026 Support\n\n### Get Involved\n- 💡 **Share Ideas**: Visit our [GitHub Discussions](https://github.com/axonops/cqlai/discussions) to propose new features\n- 🐛 **Report Issues**: Found a bug? [Open an issue](https://github.com/axonops/cqlai/issues/new/choose)\n- 🤝 **Contribute**: We welcome pull requests! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines\n- ⭐ **Star Us**: If you find CQLAI useful, please star our repository!\n\n### Stay Connected\n- 🌐 **Website**: [axonops.com](https://axonops.com)\n- 📧 **Contact**: Visit our website for support options\n\n## 📝 License\n\nThis project is licensed under the Apache 2.0 license. See the [LICENSE](LICENSE) file for details.\n\nThird-party dependency licenses are available in the [THIRD-PARTY-LICENSES](THIRD-PARTY-LICENSES/) directory. To regenerate license attributions, run `make licenses`.\n\n## ⚖️ Legal Notices\n\n*This project may contain trademarks or logos for projects, products, or services. Any use of third-party trademarks or logos are subject to those third-party's policies.*\n\n- **AxonOps** is a registered trademark of AxonOps Limited.\n- **Apache**, **Apache Cassandra**, **Cassandra**, **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.\n- **DataStax** is a registered trademark of DataStax, Inc. and its subsidiaries in the United States and/or other countries.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n  \u003cp\u003eMade with ❤️ by the \u003ca href=\"https://axonops.com\"\u003eAxonOps\u003c/a\u003e Team\u003c/p\u003e\n\u003c/div\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faxonops%2Fcqlai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faxonops%2Fcqlai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faxonops%2Fcqlai/lists"}