cosq

A CLI to query your Azure Cosmos DB instances from the command line.

Quick Start

# Install (macOS / Linux)
brew install mklab-se/tap/cosq

# Or via cargo
cargo install cosq

# Login to Azure
cosq auth login

# Initialize with a Cosmos DB account
cosq init

# Run a query
cosq query "SELECT * FROM c"

# Or just ask
cosq ask "how many orders were cancelled last week, by region?"

# Output as table or CSV
cosq query "SELECT * FROM c" --output table
cosq query "SELECT * FROM c" --output csv

# Pipe-friendly (JSON to stdout, metadata to stderr)
cosq query "SELECT c.name FROM c" -q | jq '.[].name'

Talk to your data

# Natural-language questions, grounded in a cached AI "schema card"
# of your container (fields, types, values, relationships)
cosq ask "top 5 customers by total order value" --save top-customers
cosq schema orders          # inspect the card

# Semantic & full-text search — Cosmos DB's own vector/BM25 engine,
# query embedding via ailloy; no local index
cosq search "refund complaints about late delivery" --top 5

# The query doctor: cost, timings, index usage, concrete fixes
cosq explain "SELECT * FROM c WHERE c.status = 'open' ORDER BY c.created"

Interactive shell

cosq shell

cosq (work) appdb/orders » SELECT TOP 5 c.id FROM c;
cosq (work) appdb/orders » ? which customer ordered the most this month
cosq (work) appdb/orders » ? and what did they order      # follow-ups compose
cosq (work) appdb/orders » :search urgent tickets about billing
cosq (work) appdb/orders » :explain
cosq (work) appdb/orders » :help

Context (profile, database, container, format), tab completion, persistent history — and piped stdin runs the same commands non-interactively.

Fast by default

• Cross-partition queries fan out to partition ranges in parallel
• Queries pinning the partition key are auto-scoped to one partition (--pk forces it; --first N stops early)
• AAD tokens are cached (one az call per hour, not per command)
• Multiple accounts via profiles: cosq init --name work, then --profile work or COSQ_PROFILE=work

Stored Queries

Save and reuse parameterized queries as .cosq files:

# Create a stored query (opens in editor)
cosq queries create recent-users

# List all stored queries
cosq queries list

# Run a stored query (interactive parameter prompts)
cosq run recent-users

# Run with parameters from the command line
cosq run recent-users -- --days 7

# Browse and pick a query interactively
cosq run

Multi-Step Queries

Query across multiple containers in a single stored query:

# ~/.cosq/queries/order-details.cosq
---
description: Get order with customer details
params:
  - name: orderId
    type: string
steps:
  - name: order
    container: orders
  - name: customer
    container: customers
template: |
  Order: {{ order[0].id }}
  Customer: {{ customer[0].name }}
---
-- step: order
SELECT * FROM c WHERE c.id = @orderId

-- step: customer
SELECT * FROM c WHERE c.id = @order.customerId

Steps execute in dependency order — independent steps run in parallel, while steps referencing @step.field wait for that step to complete.

AI Query Generation

Generate stored queries from natural language — the AI samples your actual documents for field-accurate SQL and auto-generates output templates:

# Set up AI (any provider via ailloy: OpenAI, Anthropic, Foundry, Ollama, ...)
cosq ai config

# Fully interactive: pick database, container, describe your query
cosq queries generate

# Or provide a description directly
cosq queries generate "active users by region in the last 30 days"

# Target a specific database/container
cosq queries generate --db mydb --container users "top 10 by login count"

For AI agents

cosq ai skill --emit > ~/.claude/skills/cosq.md gives coding agents a skill with the full command surface; cosq ai skill --reference prints the complete reference they fetch at runtime. cosq is read-only against your data by design.

See INSTALL.md for all installation methods, shell completions, and platform-specific instructions.

Development

cargo build              # Build
cargo test               # Run tests
cargo clippy             # Lint
cargo fmt                # Format

License

MIT