CLI

The legible command-line tool lets you interact with Legible from your terminal — authenticate, query data with natural language, manage models, and connect AI agents via MCP.

Installation

Download the pre-built binary for your platform from the GitHub releases, or build from source:

git clone https://github.com/kubeworkz/legible.git
cd legible/legible-cli
make build
# Binary is at build/legible

Pre-built Binaries

Platform	Binary
macOS (Apple Silicon)	`legible-darwin-arm64`
macOS (Intel)	`legible-darwin-amd64`
Linux (x86_64)	`legible-linux-amd64`
Linux (ARM64)	`legible-linux-arm64`
Windows	`legible-windows-amd64.exe`

Move the binary to somewhere in your PATH and rename it to legible:

# Example for Linux x86_64
chmod +x legible-linux-amd64
sudo mv legible-linux-amd64 /usr/local/bin/legible

Quick Start

1. Log In

Connect the CLI to your Legible server:

legible login

You'll be prompted for:

Endpoint — Your Legible server URL (e.g. https://legible.legiblequery.ai)
API Key — An organization API key (osk-...) created in the UI under Settings → API Keys

The CLI validates credentials against the server, then saves them to ~/.legible/config.yaml.

You can also log in non-interactively:

legible login --endpoint https://legible.legiblequery.ai --api-key osk-your-key-here

2. Select a Project

List available projects and select one:

legible project list
legible project use 1

All subsequent commands operate on the selected project.

3. Ask a Question

Ask a natural language question and get SQL + results + a summary:

legible ask "What are the top 10 customers by revenue?"

Or just generate SQL without executing:

legible sql "How many orders were placed last month?"

4. Run SQL Directly

Execute Legible SQL against your semantic model:

legible run-sql "SELECT * FROM customers LIMIT 10"

Configuration

The CLI stores configuration in ~/.legible/config.yaml:

endpoint: https://legible.legiblequery.ai
api_key: osk-abc123...
project_id: "1"

View or update individual values:

legible config get                    # Show all values
legible config get endpoint           # Show one value
legible config set endpoint https://legible.legiblequery.ai
legible config set api-key osk-new-key
legible config set project-id 2

Connecting to a Database (End-to-End)

This walks through the full flow — from a fresh CLI install to querying a live database.

Prerequisites

A running Legible instance (see Installation)
A database you want to connect (PostgreSQL, MySQL, BigQuery, etc.)
An API key from Settings → API Keys in the UI

Step 1: Authenticate

legible login --endpoint https://your-legible-host.com --api-key osk-your-key

Step 2: Select Your Project

legible project list
# ID  NAME           DATA SOURCE  MODELS  DISPLAY NAME
# 1   my_project     POSTGRES     5       My Project

legible project use 1

Step 3: Verify the Connection

legible whoami
# Endpoint:     https://your-legible-host.com
# User:         admin@example.com
# Organization: My Org (ID: 1)
# Projects:     1
#               - My Project

Step 4: Check Deployed Models

legible model list
# ID  NAME                    SOURCE TABLE              FIELDS  CACHED  DESCRIPTION
# 1   customers               public.customers          8       No
# 2   orders                  public.orders             12      No
# 3   order_items             public.order_items        6       No

Step 5: Query Your Data

Natural language:

legible ask "What are the top 5 customers by total order value?"

Direct SQL:

legible run-sql 'SELECT customer_name, SUM(order_total) as total FROM orders GROUP BY 1 ORDER BY 2 DESC LIMIT 5'

Generate SQL only (no execution):

legible sql "Show revenue by month for the last year" --dialect

Step 6: Deploy Model Changes

After making model changes in the UI, deploy them to the engine:

legible deploy
legible deploy status

Using with MCP

The CLI works alongside the MCP server to enable AI agent access to your data.

Generate a Project API Key

Create a project-scoped API key for MCP authentication:

legible project-key create "MCP Agent Key"
# ⚠ Save this key — it won't be shown again:
# psk-abc123...

Configure an AI Agent

Use the project key to connect Claude Desktop, Cursor, or Cline to the MCP server:

Claude Desktop (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "legible": {
      "url": "https://your-legible-host.com:9000/mcp",
      "headers": {
        "Authorization": "Bearer psk-your-project-key"
      }
    }
  }
}

Cursor — Add an MCP server in settings with URL https://your-legible-host.com:9000/mcp and the Bearer token header.

VS Code Copilot — Add to .vscode/mcp.json:

{
  "servers": {
    "legible": {
      "url": "https://your-legible-host.com:9000/mcp",
      "headers": {
        "Authorization": "Bearer psk-your-project-key"
      }
    }
  }
}

Verify MCP via the CLI

List your project keys to confirm they're active:

legible project-key list
# ID  NAME            KEY PREFIX  CREATED     STATUS
# 1   MCP Agent Key   psk-abc1    2026-03-17  active

Command Reference

Authentication

Command	Description
`legible login`	Interactive login (endpoint + API key)
`legible whoami`	Show current user and organization
`legible config get`	Display configuration
`legible config set <key> <value>`	Update a configuration value

Projects

Command	Description
`legible project list`	List all projects
`legible project use <id>`	Set the active project
`legible project current`	Show the current project
`legible project info [id]`	Show project details
`legible project create <name>`	Create a project
`legible project update [id]`	Update project settings
`legible project delete <id>`	Delete a project

Querying

Command	Description
`legible ask <question>`	Ask in natural language → SQL + results + summary
`legible sql <question>`	Generate SQL from natural language (no execution)
`legible run-sql <sql>`	Execute Legible SQL directly
`legible summary -q <question> -s <sql>`	Generate a summary from question + SQL
`legible chart -q <question> -s <sql>`	Generate a Vega-Lite chart spec

Models & Schema

Command	Description
`legible model list`	List models in the project
`legible model describe <id>`	Show model details
`legible model fields <id>`	List columns/fields of a model
`legible view list`	List views
`legible view show <id>`	Show view details
`legible view create --name <n> --response-id <id>`	Create a view from a thread response
`legible relation list`	List relationships
`legible relation create`	Create a relationship
`legible calc-field list <model-id>`	List calculated fields
`legible calc-field create`	Create a calculated field

Knowledge

Command	Description
`legible sql-pair list`	List question-SQL pairs
`legible sql-pair create -q <question> -s <sql>`	Create a SQL pair
`legible instruction list`	List instructions
`legible instruction create --text <text>`	Create an instruction

Deployment

Command	Description
`legible deploy`	Deploy model changes to the engine
`legible deploy status`	Show current deployment status

API Keys

Command	Description
`legible api-key list`	List organization API keys
`legible api-key create <name>`	Create an org API key (`osk-...`)
`legible project-key list`	List project API keys
`legible project-key create <name>`	Create a project API key (`psk-...`)

Threads & History

Command	Description
`legible thread list`	List conversation threads
`legible thread show <id>`	Show a thread with all responses
`legible history list`	View API request history

Agents

Command	Description
`legible agent create <name>`	Create a new sandboxed agent
`legible agent create <name> --blueprint <bp>`	Create from a blueprint template
`legible agent create <name> --from <source>`	Create from a community sandbox, directory, or image
`legible agent create <name> --profile <profile>`	Set inference profile (from blueprint)
`legible agent create <name> --type <type>`	Set agent type (`claude`, `codex`, `opencode`, `copilot`)
`legible agent create <name> --gpu`	Enable GPU passthrough (experimental)
`legible agent create <name> --cpus <n> --memory <n>`	Set resource limits
`legible agent create <name> --policy <file>`	Apply a custom network policy YAML
`legible agent list`	List running agent sandboxes
`legible agent connect <name>`	Open a shell inside an agent sandbox
`legible agent stop <name>`	Stop and remove an agent sandbox
`legible agent policy <name>`	View the agent's active network policy
`legible agent policy <name> --set <file>`	Apply a new policy to a running agent
`legible agent logs <name>`	Stream agent sandbox logs
`legible agent logs <name> --tail <n>`	Show the last N log lines

The --from flag accepts:

Community sandbox names — e.g. --from ollama (from the NVIDIA OpenShell catalog)
Local directories — e.g. --from ./my-sandbox-dir
Container images — e.g. --from my-registry.example.com/my-image:latest

See Agents for full documentation.

Blueprints

Command	Description
`legible blueprint list`	List available blueprints (built-in + installed)
`legible blueprint show <name>`	Show full blueprint configuration
`legible blueprint validate <path>`	Validate a blueprint YAML file
`legible blueprint install <path> <name>`	Install a custom blueprint to `~/.legible/blueprints/`
`legible blueprint recommend <connector>`	Recommend a blueprint for a data source (e.g. `POSTGRES`)
`legible blueprint for-connector <connector>`	List all blueprints compatible with a connector

See Blueprints for full documentation.

Gateways

Command	Description
`legible gateway status`	Show the gateway for the current organization
`legible gateway list`	List all running gateways
`legible gateway info <id>`	Show detailed gateway information
`legible gateway create`	Create a gateway for the current org
`legible gateway create --cpus <n> --memory <n>`	Create with custom resource limits
`legible gateway create --max-sandboxes <n>`	Set maximum sandbox count (default: 20)
`legible gateway update <id>`	Update gateway status or endpoint
`legible gateway delete <id>`	Delete a stopped gateway

Aliases: gateways, gw. See Gateways for full documentation.

Agent Builder

Command	Description
`legible agent-builder list`	List all agent definitions
`legible agent-builder show <id>`	Show agent definition details
`legible agent-builder create --name <name>`	Create a new agent definition
`legible agent-builder create --name <name> --model <model>`	Create with a specific LLM model
`legible agent-builder create --name <name> --system-prompt <prompt>`	Create with a system prompt
`legible agent-builder create --name <name> --temperature <n>`	Set temperature (0.0–2.0)
`legible agent-builder create --name <name> --max-tokens <n>`	Set max output tokens
`legible agent-builder create --name <name> --tags <a>,<b>`	Set comma-separated tags
`legible agent-builder publish <id>`	Publish a new version
`legible agent-builder publish <id> --note <text>`	Publish with a change note
`legible agent-builder deploy <id>`	Deploy for API access
`legible agent-builder archive <id>`	Archive an agent definition
`legible agent-builder versions <id>`	Show version history
`legible agent-builder chat <id>`	Interactive chat with a deployed agent

Aliases: ab. See Agent Builder for full documentation.

Global Flags

Flag	Description
`--json`	Output results as JSON (works with any command)

Installation​

Pre-built Binaries​

Quick Start​

1. Log In​

2. Select a Project​

3. Ask a Question​

4. Run SQL Directly​

Configuration​

Connecting to a Database (End-to-End)​

Prerequisites​

Step 1: Authenticate​

Step 2: Select Your Project​

Step 3: Verify the Connection​

Step 4: Check Deployed Models​

Step 5: Query Your Data​

Step 6: Deploy Model Changes​

Using with MCP​

Generate a Project API Key​

Configure an AI Agent​

Verify MCP via the CLI​

Command Reference​

Authentication​

Projects​

Querying​

Models & Schema​

Knowledge​

Deployment​

API Keys​

Threads & History​

Agents​

Blueprints​

Gateways​

Agent Builder​

Global Flags​