Official CLI Reference

QueryCraft CLI & MCP Documentation

Authenticate, introspect schemas, run natural language queries with Llama 3.1 70B, and hook directly into Claude Desktop, Cursor IDE, Antigravity, and ChatGPT.

Chapter 1

Overview & Architecture

The QueryCraft CLI (`querycraft`) bridges your local development environment directly to your live database clusters and AI coding agents via the Model Context Protocol (MCP).

🧠 Zero-Hallucination

Grounds prompts strictly in live introspected database schemas and types.

🛡️ Pre-Flight Cost Guard

Dry-runs PostgreSQL EXPLAIN to detect expensive scans before execution.

🔒 Tenant-Isolated

OAuth tokens stored locally in `~/.querycraft/auth.json` with 600 permissions.

Installation Options

Universal Shell Installer (bash)

# Downloads, builds, and symlinks /usr/local/bin/querycraft
curl -fsSL https://raw.githubusercontent.com/Nitindeep65/TTSC/main/setup-mcp.sh | bash

3-Step Quickstart

Run querycraft auth login to link your QueryCraft account in 1 tap.

Connect your Database (or use sandbox)

Run querycraft connect postgresql://user:pass@host/db to link your live database.

Ask Questions in Plain English

Run querycraft ask "show active users" to get instant SQL + table data.

Chapter 2

1-Click Universal AI Setup (`querycraft setup`)

Automatically detects installed AI tools on your system (Claude Desktop, Cursor IDE, Antigravity, Windsurf) and configures their Model Context Protocol (MCP) configuration in 1 millisecond.

Run 1-Click AI Configuration (zsh)

$querycraft setup
  🔍 Detecting installed AI assistants & IDEs...
  ✓ Claude Desktop: Configured (~/Library/Application Support/Claude/claude_desktop_config.json)
  ✓ Cursor IDE: Configured (~/.cursor/mcp.json)
  ✓ Antigravity: Configured (~/.gemini/config/mcp_config.json)
  🎉 3 AI tools configured successfully!
  Restart your editor or Claude to start querying databases naturally.

Manual MCP Configuration Reference

If you prefer manual configuration, add this to your MCP configuration file:

claude_desktop_config.json / mcp.json (json)

{
  "mcpServers": {
    "querycraft": {
      "command": "querycraft",
      "args": ["ai", "mcp-stdio"],
      "env": {
        "QUERYCRAFT_BACKEND_URL": "http://localhost:8000"
      }
    }
  }
}

Chapter 3

Query & Inspection Commands

querycraft ask "<prompt>"

Translates any natural language question to SQL using Llama 3.1 70B, evaluates safety with Pre-Flight Cost Guard, executes against your database workspace, and prints an aligned ASCII table.

Natural Language Query (zsh)

$querycraft ask "show all active users"
  🧠 QueryCraft AI  [Workspace: Production | User: nitindeep65@gmail.com]
  Question: show all active users
  Thinking, grounding schema, evaluating safety...
  Generated SQL Query:
  SELECT * FROM users WHERE is_active = TRUE LIMIT 50;
  Executing query on database...
  Results (5 rows in 12.4ms):
  ┌──────────────────────────────────┬───────────────┬─────────────────────────────┬──────────┬───────────┐
  │ id                               │ name          │ email                       │ role     │ is_active │
  ├──────────────────────────────────┼───────────────┼─────────────────────────────┼──────────┼───────────┤
  │ e1a9b2c3-4d5e-6f7a-8b9c-0d1e2f.. │ Alex Rivera   │ alex.rivera@enterprise.com  │ customer │ True      │
  │ f2b0c3d4-5e6f-7a8b-9c0d-1e2f3a.. │ Sofia Davis   │ sofia.davis@cloudscale.io   │ customer │ True      │
  │ a3c1d4e5-6f7a-8b9c-0d1e-2f3a4b.. │ Marcus Vance  │ marcus.vance@fintech.co     │ admin    │ True      │
  │ b4d2e5f6-7a8b-9c0d-1e2f-3a4b5c.. │ Elena Rostova │ elena.rostova@datadrive.net │ customer │ True      │
  │ c5e3f6a7-8b9c-0d1e-2f3a-4b5c6d.. │ Liam Chen     │ liam.chen@techcorp.io       │ merchant │ True      │
  └──────────────────────────────────┴───────────────┴─────────────────────────────┴──────────┴───────────┘

querycraft query "<SQL>"

Executes raw read-only SQL queries directly against your connected database with execution latency measurement.

Raw SQL Query (zsh)

$querycraft query "SELECT id, name, email FROM users LIMIT 3;"
  ⚡ QueryCraft SQL Execution  [Workspace: Production]
  Executing: SELECT id, name, email FROM users LIMIT 3;
  Results (3 rows in 9.8ms):
  ┌──────────────────────────────────┬───────────────┬─────────────────────────────┐
  │ id                               │ name          │ email                       │
  ├──────────────────────────────────┼───────────────┼─────────────────────────────┤
  │ e1a9b2c3-4d5e-6f7a-8b9c-0d1e2f.. │ Alex Rivera   │ alex.rivera@enterprise.com  │
  │ f2b0c3d4-5e6f-7a8b-9c0d-1e2f3a.. │ Sofia Davis   │ sofia.davis@cloudscale.io   │
  │ a3c1d4e5-6f7a-8b9c-0d1e-2f3a4b.. │ Marcus Vance  │ marcus.vance@fintech.co     │
  └──────────────────────────────────┴───────────────┴─────────────────────────────┘

querycraft schema

Introspects tables, column data types, Primary Keys [PK], and Foreign Key relations [FK].

Introspect Schema (zsh)

$querycraft schema
  📋 Introspecting Database Schema...  [User: nitindeep65@gmail.com]
  Database Type: Cloud PostgreSQL (Supabase / Neon / AWS RDS)
  Total Tables: 5
  • users  (8 columns) — Registered user accounts and credentials
    └─ id: UUID [PK]
    └─ email: VARCHAR(255)
    └─ name: VARCHAR(100)
    └─ role: VARCHAR(50)
    └─ is_active: BOOLEAN
  • orders  (7 columns) — Customer transactions and purchase orders
    └─ id: UUID [PK]
    └─ user_id: UUID [FK]
    └─ total_amount: NUMERIC(12,2)
    └─ status: VARCHAR(50)

querycraft connect <URI> [--workspace <name>]

Links a live PostgreSQL, Supabase, Neon, RDS, or MongoDB Atlas cluster connection string to your workspace.

Connect Live Database (zsh)

$querycraft connect postgresql://postgres:pass@db.supabase.co:5432/postgres --workspace Production
  🔌 Connecting Database...
  Target Workspace: Production
  Testing connection and introspecting schema...
  ✓ Database Connected Successfully!
  Host: db.supabase.co  │  Database: postgres
  Introspected: 12 tables

Parameter / Flag	Type	Default	Description
uri	string	required	Full database connection string (postgresql://... or mongodb+srv://...)
--workspace	string	Production	Target workspace tier (Production, Staging, Analytics)

Chapter 4

GitHub-style (gh auth login) browser OAuth authentication. Spawns a local listener on port 9876, handles the token exchange, and stores credentials in ~/.querycraft/auth.json with 600 file permissions.

Browser OAuth Login (zsh)

$querycraft auth login
  🔑 Opening browser for authentication...
  Waiting for authentication on http://localhost:9876/callback...
  ✅ Logged in as: nitindeep65@gmail.com
  Session token saved to ~/.querycraft/auth.json (valid for 30 days)

querycraft auth whoami

Verifies current authenticated session token, user email, and backend status:

Check Identity (zsh)

$querycraft auth whoami
  ✅ Logged in as: nitindeep65@gmail.com
  Session created: 2026-08-31  |  Expires: 2026-09-30
  Backend: http://localhost:8000

querycraft auth logout

Clears and deletes stored session tokens from ~/.querycraft/auth.json:

Logout (zsh)

$querycraft auth logout
  👋 Logged out successfully. Stored credentials removed.

Chapter 5

Workspaces & Environments (`querycraft workspaces list`)

Lists all database workspaces configured for your account, showing database engine, environment tier, and connection status.

List Workspaces (zsh)

$querycraft workspaces list
  📁 Workspaces for nitindeep65@gmail.com (3 total):
  • Production (ws-default)  [ACTIVE]
    Engine: postgres  │  Environment: Production  │  Connected: Yes
  • Staging (ws-staging)
    Engine: postgres  │  Environment: Staging     │  Connected: Yes
  • Analytics (ws-analytics)
    Engine: mongodb   │  Environment: Analytics   │  Connected: No

Chapter 6

Environment Variables & Reference

Configure network endpoints and model parameters in your environment:

Parameter / Flag	Type	Default	Description
QUERYCRAFT_BACKEND_URL	string	http://localhost:8000	FastAPI microservice backend base URL
QUERYCRAFT_FRONTEND_URL	string	http://localhost:3000	Next.js Web Studio and OAuth login receiver base URL
NVIDIA_API_KEY	string	—	Optional API key for direct Llama 3.1 70B compilation via NVIDIA NIM

Command Cheat Sheet

querycraft setup1-Click auto-configure Claude Desktop, Cursor & Antigravity

querycraft ask "<prompt>"Natural language English to SQL query with table results

querycraft query "<SQL>"Execute raw read-only SQL directly with execution timing

querycraft schemaIntrospect tables, data types, primary keys, and foreign keys

querycraft connect <URI>Connect live PostgreSQL, Supabase, Neon, or MongoDB

querycraft auth loginGitHub-style browser OAuth login

querycraft auth whoamiCheck current logged-in identity and session status

querycraft auth logoutClear stored credentials and session tokens

querycraft workspaces listList all database workspaces configured for your user

Next Chapter

Web Dashboard Studio

Advanced Feature

Autonomous Canvas Mode

Official CLI Reference

QueryCraft CLI & MCP Documentation

Authenticate, introspect schemas, run natural language queries with Llama 3.1 70B, and hook directly into Claude Desktop, Cursor IDE, Antigravity, and ChatGPT.

Chapter 1

Overview & Architecture

The QueryCraft CLI (`querycraft`) bridges your local development environment directly to your live database clusters and AI coding agents via the Model Context Protocol (MCP).

🧠 Zero-Hallucination

Grounds prompts strictly in live introspected database schemas and types.

🛡️ Pre-Flight Cost Guard

Dry-runs PostgreSQL EXPLAIN to detect expensive scans before execution.

🔒 Tenant-Isolated

OAuth tokens stored locally in `~/.querycraft/auth.json` with 600 permissions.

Installation Options

Universal Shell Installer (bash)

# Downloads, builds, and symlinks /usr/local/bin/querycraft
curl -fsSL https://raw.githubusercontent.com/Nitindeep65/TTSC/main/setup-mcp.sh | bash

3-Step Quickstart

Run querycraft auth login to link your QueryCraft account in 1 tap.

Connect your Database (or use sandbox)

Run querycraft connect postgresql://user:pass@host/db to link your live database.

Ask Questions in Plain English

Run querycraft ask "show active users" to get instant SQL + table data.

Chapter 2

1-Click Universal AI Setup (`querycraft setup`)

Automatically detects installed AI tools on your system (Claude Desktop, Cursor IDE, Antigravity, Windsurf) and configures their Model Context Protocol (MCP) configuration in 1 millisecond.

Run 1-Click AI Configuration (zsh)

$querycraft setup
  🔍 Detecting installed AI assistants & IDEs...
  ✓ Claude Desktop: Configured (~/Library/Application Support/Claude/claude_desktop_config.json)
  ✓ Cursor IDE: Configured (~/.cursor/mcp.json)
  ✓ Antigravity: Configured (~/.gemini/config/mcp_config.json)
  🎉 3 AI tools configured successfully!
  Restart your editor or Claude to start querying databases naturally.

Manual MCP Configuration Reference

If you prefer manual configuration, add this to your MCP configuration file:

claude_desktop_config.json / mcp.json (json)

{
  "mcpServers": {
    "querycraft": {
      "command": "querycraft",
      "args": ["ai", "mcp-stdio"],
      "env": {
        "QUERYCRAFT_BACKEND_URL": "http://localhost:8000"
      }
    }
  }
}

Chapter 3

Query & Inspection Commands

querycraft ask "<prompt>"

Translates any natural language question to SQL using Llama 3.1 70B, evaluates safety with Pre-Flight Cost Guard, executes against your database workspace, and prints an aligned ASCII table.

Natural Language Query (zsh)

$querycraft ask "show all active users"
  🧠 QueryCraft AI  [Workspace: Production | User: nitindeep65@gmail.com]
  Question: show all active users
  Thinking, grounding schema, evaluating safety...
  Generated SQL Query:
  SELECT * FROM users WHERE is_active = TRUE LIMIT 50;
  Executing query on database...
  Results (5 rows in 12.4ms):
  ┌──────────────────────────────────┬───────────────┬─────────────────────────────┬──────────┬───────────┐
  │ id                               │ name          │ email                       │ role     │ is_active │
  ├──────────────────────────────────┼───────────────┼─────────────────────────────┼──────────┼───────────┤
  │ e1a9b2c3-4d5e-6f7a-8b9c-0d1e2f.. │ Alex Rivera   │ alex.rivera@enterprise.com  │ customer │ True      │
  │ f2b0c3d4-5e6f-7a8b-9c0d-1e2f3a.. │ Sofia Davis   │ sofia.davis@cloudscale.io   │ customer │ True      │
  │ a3c1d4e5-6f7a-8b9c-0d1e-2f3a4b.. │ Marcus Vance  │ marcus.vance@fintech.co     │ admin    │ True      │
  │ b4d2e5f6-7a8b-9c0d-1e2f-3a4b5c.. │ Elena Rostova │ elena.rostova@datadrive.net │ customer │ True      │
  │ c5e3f6a7-8b9c-0d1e-2f3a-4b5c6d.. │ Liam Chen     │ liam.chen@techcorp.io       │ merchant │ True      │
  └──────────────────────────────────┴───────────────┴─────────────────────────────┴──────────┴───────────┘

querycraft query "<SQL>"

Executes raw read-only SQL queries directly against your connected database with execution latency measurement.

Raw SQL Query (zsh)

$querycraft query "SELECT id, name, email FROM users LIMIT 3;"
  ⚡ QueryCraft SQL Execution  [Workspace: Production]
  Executing: SELECT id, name, email FROM users LIMIT 3;
  Results (3 rows in 9.8ms):
  ┌──────────────────────────────────┬───────────────┬─────────────────────────────┐
  │ id                               │ name          │ email                       │
  ├──────────────────────────────────┼───────────────┼─────────────────────────────┤
  │ e1a9b2c3-4d5e-6f7a-8b9c-0d1e2f.. │ Alex Rivera   │ alex.rivera@enterprise.com  │
  │ f2b0c3d4-5e6f-7a8b-9c0d-1e2f3a.. │ Sofia Davis   │ sofia.davis@cloudscale.io   │
  │ a3c1d4e5-6f7a-8b9c-0d1e-2f3a4b.. │ Marcus Vance  │ marcus.vance@fintech.co     │
  └──────────────────────────────────┴───────────────┴─────────────────────────────┘

querycraft schema

Introspects tables, column data types, Primary Keys [PK], and Foreign Key relations [FK].

Introspect Schema (zsh)

$querycraft schema
  📋 Introspecting Database Schema...  [User: nitindeep65@gmail.com]
  Database Type: Cloud PostgreSQL (Supabase / Neon / AWS RDS)
  Total Tables: 5
  • users  (8 columns) — Registered user accounts and credentials
    └─ id: UUID [PK]
    └─ email: VARCHAR(255)
    └─ name: VARCHAR(100)
    └─ role: VARCHAR(50)
    └─ is_active: BOOLEAN
  • orders  (7 columns) — Customer transactions and purchase orders
    └─ id: UUID [PK]
    └─ user_id: UUID [FK]
    └─ total_amount: NUMERIC(12,2)
    └─ status: VARCHAR(50)

querycraft connect <URI> [--workspace <name>]

Links a live PostgreSQL, Supabase, Neon, RDS, or MongoDB Atlas cluster connection string to your workspace.

Connect Live Database (zsh)

$querycraft connect postgresql://postgres:pass@db.supabase.co:5432/postgres --workspace Production
  🔌 Connecting Database...
  Target Workspace: Production
  Testing connection and introspecting schema...
  ✓ Database Connected Successfully!
  Host: db.supabase.co  │  Database: postgres
  Introspected: 12 tables

Parameter / Flag	Type	Default	Description
uri	string	required	Full database connection string (postgresql://... or mongodb+srv://...)
--workspace	string	Production	Target workspace tier (Production, Staging, Analytics)

Chapter 4

Browser OAuth Login (zsh)

$querycraft auth login
  🔑 Opening browser for authentication...
  Waiting for authentication on http://localhost:9876/callback...
  ✅ Logged in as: nitindeep65@gmail.com
  Session token saved to ~/.querycraft/auth.json (valid for 30 days)

querycraft auth whoami

Verifies current authenticated session token, user email, and backend status:

Check Identity (zsh)

$querycraft auth whoami
  ✅ Logged in as: nitindeep65@gmail.com
  Session created: 2026-08-31  |  Expires: 2026-09-30
  Backend: http://localhost:8000

querycraft auth logout

Clears and deletes stored session tokens from ~/.querycraft/auth.json:

Logout (zsh)

$querycraft auth logout
  👋 Logged out successfully. Stored credentials removed.

Chapter 5

Workspaces & Environments (`querycraft workspaces list`)

Lists all database workspaces configured for your account, showing database engine, environment tier, and connection status.

List Workspaces (zsh)

$querycraft workspaces list
  📁 Workspaces for nitindeep65@gmail.com (3 total):
  • Production (ws-default)  [ACTIVE]
    Engine: postgres  │  Environment: Production  │  Connected: Yes
  • Staging (ws-staging)
    Engine: postgres  │  Environment: Staging     │  Connected: Yes
  • Analytics (ws-analytics)
    Engine: mongodb   │  Environment: Analytics   │  Connected: No

Chapter 6

Environment Variables & Reference

Configure network endpoints and model parameters in your environment:

Parameter / Flag	Type	Default	Description
QUERYCRAFT_BACKEND_URL	string	http://localhost:8000	FastAPI microservice backend base URL
QUERYCRAFT_FRONTEND_URL	string	http://localhost:3000	Next.js Web Studio and OAuth login receiver base URL
NVIDIA_API_KEY	string	—	Optional API key for direct Llama 3.1 70B compilation via NVIDIA NIM

Command Cheat Sheet

querycraft setup1-Click auto-configure Claude Desktop, Cursor & Antigravity

querycraft ask "<prompt>"Natural language English to SQL query with table results

querycraft query "<SQL>"Execute raw read-only SQL directly with execution timing

querycraft schemaIntrospect tables, data types, primary keys, and foreign keys

querycraft connect <URI>Connect live PostgreSQL, Supabase, Neon, or MongoDB

querycraft auth loginGitHub-style browser OAuth login

querycraft auth whoamiCheck current logged-in identity and session status

querycraft auth logoutClear stored credentials and session tokens

querycraft workspaces listList all database workspaces configured for your user

Next Chapter

Web Dashboard Studio

Advanced Feature

Autonomous Canvas Mode

QueryCraft CLI & MCP Documentation

Overview & Architecture

Installation Options

3-Step Quickstart

1-Click Universal AI Setup (querycraft setup)

Manual MCP Configuration Reference

Query & Inspection Commands

querycraft ask "<prompt>"

querycraft query "<SQL>"

querycraft schema

querycraft connect <URI> [--workspace <name>]

Authentication & Tenant Security

querycraft auth whoami

querycraft auth logout

Workspaces & Environments (querycraft workspaces list)

Environment Variables & Reference

Command Cheat Sheet

QueryCraft CLI & MCP Documentation

Overview & Architecture

Installation Options

3-Step Quickstart

1-Click Universal AI Setup (querycraft setup)

Manual MCP Configuration Reference

Query & Inspection Commands

querycraft ask "<prompt>"

querycraft query "<SQL>"

querycraft schema

querycraft connect <URI> [--workspace <name>]

Authentication & Tenant Security

querycraft auth whoami

querycraft auth logout

Workspaces & Environments (querycraft workspaces list)

Environment Variables & Reference

Command Cheat Sheet

1-Click Universal AI Setup (`querycraft setup`)

Workspaces & Environments (`querycraft workspaces list`)

1-Click Universal AI Setup (`querycraft setup`)

Workspaces & Environments (`querycraft workspaces list`)