CLI

The EasySQL CLI is the official command-line interface for the EasySQL API. Ask questions in natural language to your local MySQL, PostgreSQL or SQLite database — straight from your terminal. The CLI runs the whole flow client-side: only schema metadata is sent to the EasySQL API, credentials never leave your machine.

npm @easysql/cli github Clearsoft-net/easysql-cli release latest

Requirements

Runs on Node.js ≥ 22.13 (built-in node:sqlite) or Bun ≥ 1.4 — or no runtime at all, using a standalone binary from GitHub Releases (published for linux-x64, linux-arm64, darwin-x64, darwin-arm64 and windows-x64).

Installation

# Run without installing
npx @easysql/cli
bunx @easysql/cli

# Or install globally
npm i -g @easysql/cli
bun add -g @easysql/cli

# Or grab a standalone binary (no runtime required)
curl -L https://github.com/Clearsoft-net/easysql-cli/releases/latest/download/easysql-linux-x64 -o easysql
chmod +x easysql && ./easysql --help

MySQL and PostgreSQL drivers are optional: SQLite works out of the box, and the other engines are installed on demand — npm i @easysql/connector-mysql, bun add @easysql/connector-postgres, etc.

Quick start

# 1. Authenticate (API key created in the dashboard)
easysql login

# 2a. (Easiest) Generate a local sample SQLite database and use it immediately
easysql demo
easysql query "Top 3 customers by revenue"

# 2b. Or add a real local database connector (schema is sent to EasySQL, not credentials)
easysql connector add \
  --name "Local Postgres" \
  --type postgresql \
  --host localhost --port 5432 --database mydb --user me --password mypass

# 2c. Or point at a local SQLite file
easysql connector add \
  --name "Local SQLite" \
  --type sqlite \
  --file /path/to/your.db

# 3. Ask a question
easysql query "How many orders did we get last week?"

# 4. SQL-only mode (no local execution)
easysql query "Top 5 customers by revenue" --generate-only

# 5. Open the interactive TUI shell
easysql

Commands

Command	Description
`easysql login`	Authenticate with an EasySQL API key
`easysql logout`	Clear local credentials
`easysql demo`	Generate a local sample SQLite database and register it as `local-demo`
`easysql connector add`	Add a local MySQL / Postgres / SQLite connector
`easysql connector sync [name]`	Re-introspect and push the schema again
`easysql connector list`	List connectors from EasySQL
`easysql connector remove <name>`	Remove a connector from EasySQL and locally
`easysql query "<question>"`	Generate SQL and run it locally
`easysql query "<question>" --generate-only`	Print the SQL without executing
`easysql usage`	Show plan consumption (quota used vs remaining)
`easysql history`	Show the local read-only question log
`easysql update`	Self-update to the latest release
`easysql --help`	List every command, flag, and parameter

Global flags: --api-url, --config, --json, --no-color, -v, -h.

Privacy & security

Credentials never leave your machine. The CLI only introspects your local database to extract schema metadata (tables, columns, types, primary_keys, foreign_keys, row_count_estimate) and sends that — never passwords, hosts, or ports.
Read-only enforcement. Generated SQL is validated server-side by the EasySQL API. The CLI additionally refuses to execute any non-SELECT statement.
API key storage. Stored in ~/.config/easysql/config.json with 0600 permissions.
Database passwords are never persisted: they are re-prompted (or read from $EASYSQL_DB_PASSWORD) on every query.

Self-update

easysql update --check   # report current vs latest
easysql update           # download and replace

Next steps

CLI repository — source, tests, and release notes.
Contributing guide — development workflow, build from source, and conventions.
REST API reference — the HTTP endpoints the CLI talks to.

Documentation