SQL Agent CLI Documentation

Complete command reference and user guide

Getting Started

After downloading and installing SQL Agent CLI, open your terminal and follow these steps:

  1. Verify installation: sql-agent --help
  2. Login with your license key: sql-agent login YOUR-API-KEY
  3. Configure your AI provider: sql-agent setup-ai
  4. Connect to a database: sql-agent connect --url "postgresql://user:pass@host/db"

Authentication

sql-agent login <api-key>

Authenticate with your API key to enable SQL Agent features.

$ sql-agent login XXXX-XXXX-XXXX-XXXX

Your API key can be found in your cabinet after purchasing a license.

sql-agent logout

Remove stored API key and log out of SQL Agent.

$ sql-agent logout

AI Provider Configuration

sql-agent setup-ai

Interactive wizard to configure your AI provider and model.

$ sql-agent setup-ai
# Follow the prompts to select provider and model

Supported Providers:

  • OpenAI — GPT-4o, GPT-4, GPT-3.5-turbo
  • Anthropic — Claude Opus, Claude Sonnet, Claude Haiku
  • DeepSeek — DeepSeek Chat, DeepSeek Coder
  • Groq — Llama 3.3 70B, Llama 3.1 8B
  • Ollama — Local models (no API key required)

Manual Configuration

You can also configure the AI provider manually:

$ sql-agent configuration llm.provider --value openai
$ sql-agent configuration llm.model --value gpt-4o
$ sql-agent configuration llm.api_key_env --value OPENAI_API_KEY

Database Connection

sql-agent connect --url <database-url>

Connect to a database and start an interactive session.

Options:

  • --url, -u — Database connection URL (required)
  • --profile, -p — Save connection as a named profile
  • --read-only — Connect in read-only mode (default)
  • --write — Enable write operations

Examples:

# PostgreSQL
$ sql-agent connect --url "postgresql://user:pass@localhost:5432/mydb"
# MySQL
$ sql-agent connect --url "mysql://user:pass@localhost:3306/mydb"
# SQLite
$ sql-agent connect --url "sqlite:///path/to/database.db"
# Save as profile
$ sql-agent connect --url "postgresql://..." --profile prod_db

sql-agent use-profile <name>

Connect to a database using a previously saved profile.

$ sql-agent use-profile prod_db

Profile Management

sql-agent profiles

List all saved database connection profiles.

$ sql-agent profiles

sql-agent delete-profile <name>

Remove a saved database profile.

$ sql-agent delete-profile prod_db

sql-agent export-profiles

Export all saved profiles to a JSON file.

$ sql-agent export-profiles --output backup.json
$ sql-agent export-profiles --include-credentials

Configuration Settings

sql-agent configuration [key] [--value value]

View and update configuration settings.

Common Settings:

# View all settings
$ sql-agent configuration --list
# Set LLM provider
$ sql-agent configuration llm.provider --value openai
# Set LLM model
$ sql-agent configuration llm.model --value gpt-4o
# Set query timeout (seconds)
$ sql-agent configuration query_timeout --value 60
# Set conversation history mode
$ sql-agent configuration conversation.history_mode --value long

History Modes:

  • short — ~5 message exchanges
  • medium — ~10 message exchanges (default)
  • long — ~15 message exchanges
  • unlimited — No message limit

Interactive Session Commands

These commands are available after connecting to a database:

Command Description
help Show available interactive commands
schema Display complete database schema with all tables and columns
/insights <table> Get AI-powered insights about a specific table
/explain <query> Show query execution plan with optimization recommendations
/analyze <query> AI-powered query performance analysis with suggestions
history Show recent query history
clear Clear conversation history and start fresh
exit Quit the interactive session

Natural Language Queries

Simply type your question in plain English:

Prompt> Show me all users created in the last week
Prompt> What's the average order value by month?
Prompt> Find customers with no orders

Query History

sql-agent history

View or clear query execution history.

Options:

  • --limit, -n — Number of entries to show (default: 20)
  • --clear — Clear all query history
$ sql-agent history --limit 50
$ sql-agent history --clear

Security Features

Read-Only Mode

By default, SQL Agent connects in read-only mode to protect your data. The following operations are blocked:

  • INSERT, UPDATE, DELETE
  • DROP, TRUNCATE, CREATE, ALTER

To enable write operations, use the --write flag when connecting.

Encrypted Storage

All sensitive data (API keys, database credentials) is encrypted using Fernet encryption and stored locally on your machine. Your data is never transmitted to our servers.

Query Timeout

Queries are automatically terminated after 30 seconds (configurable) to prevent runaway queries.

Need Help?

Check our FAQ or contact our support team for assistance.

View FAQ Contact Support