CLI Reference¶

Ask RITA provides a command-line interface for running queries, testing configurations, starting interactive sessions, and launching the MCP server.

Table of Contents¶

Installation
Commands Overview
Common Flags
askrita query
askrita interactive
askrita test
askrita mcp
Examples
Troubleshooting

Installation¶

The askrita command is installed automatically with the package:

pip install askrita

Verify the installation:

askrita --help

Commands Overview¶

Command	Description
`askrita query`	Run a single natural-language query and print the result
`askrita interactive`	Start an interactive REPL session
`askrita test`	Test your configuration, database, and LLM connections
`askrita mcp`	Start the Model Context Protocol (MCP) server

Common Flags¶

These flags are available on all subcommands:

Flag	Short	Description
`--config PATH`	`-c PATH`	Path to YAML configuration file
`--verbose`	`-v`	Enable debug logging (sets root logger to DEBUG)

The config path is validated:

Must end with .yaml or .yml
Must not contain .. (path traversal)
File must exist

askrita query¶

Run a single natural-language question against your database and print the result.

askrita query [OPTIONS] QUESTION

Arguments¶

Argument	Required	Description
`QUESTION`	Yes	The natural-language question (positional)

Options¶

Flag	Default	Description
`--config PATH`	—	Path to YAML config file
`--format FORMAT`	From config	Output format: `json`, `yaml`, or `text`
`--verbose`	—	Enable debug logging

Output Formats¶

json (default) — Full WorkflowState as JSON:

askrita query -c config.yaml "How many orders last month?" --format json

yaml — Full WorkflowState as YAML:

askrita query -c config.yaml "How many orders last month?" --format yaml

text — Human-readable summary (answer, visualization, SQL, chart data):

askrita query -c config.yaml "How many orders last month?" --format text

Behavior¶

Loads and validates the configuration
Tests database and LLM connections
Runs SQLAgentWorkflow.query(question)
Prints the result in the specified format

askrita interactive¶

Start an interactive REPL session for running multiple queries.

askrita interactive [OPTIONS]

Options¶

Flag	Default	Description
`--config PATH`	—	Path to YAML config file
`--verbose`	—	Enable debug logging

Behavior¶

Loads and validates the configuration
Tests database and LLM connections
Enters a loop that prompts for questions via input()
Each question is run through SQLAgentWorkflow.query()
Results are printed as text (answer and visualization)

Exit Commands¶

Type any of these to exit the session:

exit
quit
q

Example Session¶

$ askrita interactive -c config.yaml

AskRITA Interactive Mode
Type your questions (exit/quit/q to stop)
========================

Ask a question: How many customers do we have?

Answer: There are 1,247 customers in the database.

Ask a question: What is the average order value?

Answer: The average order value is $85.32.

Ask a question: quit
Goodbye!

Note: The interactive mode uses query() per question, not chat(). Each question is processed independently without conversation history. For multi-turn conversations with context, use the Python API with workflow.chat(messages).

askrita test¶

Test your configuration, database connection, and LLM connection.

askrita test [OPTIONS]

Options¶

Flag	Default	Description
`--config PATH`	—	Path to YAML config file
`--verbose`	—	Enable debug logging

Behavior¶

Loads and validates the configuration
Prints a summary of database, LLM, and workflow settings
Tests the database connection
Tests the LLM connection
Reports success or failure for each test

Example Output¶

$ askrita test -c config.yaml

Configuration Summary:
  Database: postgresql://localhost:5432/mydb
  LLM Provider: openai
  LLM Model: gpt-4o

Testing database connection... ✓ Connected
Testing LLM connection... ✓ Connected

All tests passed!

askrita mcp¶

Start the Model Context Protocol (MCP) server for integration with AI assistants like Claude Desktop.

askrita mcp [OPTIONS]

Options¶

Flag	Default	Description
`--config PATH`	—	Path to YAML config file
`--log-level LEVEL`	`INFO`	Log level for the MCP server
`--verbose`	—	Enable debug logging

Behavior¶

Loads the configuration
Starts the MCP server (communicates over stdio)
Exposes askrita_query and askrita_test as MCP tools

Available MCP Tools¶

Tool	Description
`askrita_query`	Run a natural-language query against the configured database
`askrita_test`	Test the configuration and connections

Integration¶

The MCP server is designed to be launched by AI assistants. See the MCP Server Guide and Claude Desktop Setup for configuration details.

Examples¶

Quick Query¶

askrita query -c config.yaml "What are the top 5 products by revenue?"

Query with JSON Output¶

askrita query -c config.yaml --format json "Total sales by month" | jq '.answer'

Verbose Debugging¶

askrita query -c config.yaml -v "Why are sales declining?"

Test Before Running¶

# Verify everything is connected
askrita test -c config.yaml

# Then run your query
askrita query -c config.yaml "Show me the dashboard data"

Multiple Configs¶

# Production database
askrita query -c configs/production.yaml "How many active users?"

# Staging database
askrita query -c configs/staging.yaml "How many active users?"

Troubleshooting¶

Command Not Found¶

Symptom: askrita: command not found

Ensure the package is installed: pip install askrita
If using a virtual environment, make sure it is activated
Check that the virtual environment's bin directory is in your PATH

Config Validation Errors¶

Symptom: Error: Invalid configuration file path

The config path must end with .yaml or .yml
The file must exist at the specified path
Path traversal (..) is not allowed for security

Connection Test Failures¶

Symptom: askrita test reports connection failures.

Database: Check connection string, credentials, and network access
LLM: Check API key environment variables and network/proxy settings
Use --verbose to see detailed error messages

Interactive Mode Hangs¶

Symptom: No prompt appears in interactive mode.

The workflow tests DB and LLM connections at startup — this may take a few seconds
Use --verbose to see what step is blocking
Test connections first with askrita test

See also:

Configuration Guide — Complete YAML configuration reference
MCP Server Guide — Detailed MCP server setup
Claude Desktop Setup — Using Ask RITA with Claude Desktop