EasySQL CLI / TUI

Official command-line interface for the EasySQL API · A Clearsoft Product

---

Ask questions in natural language to your local MySQL, PostgreSQL, ClickHouse or SQLite database — straight from your terminal.

The EasySQL CLI is the open-source counterpart to the WordPress plugin. It runs the full EasySQL query flow client-side:

1. You connect a local MySQL, PostgreSQL, ClickHouse or SQLite database. (Or run easysql demo to spin up a sample SQLite database in seconds.)
2. The CLI introspects the schema and pushes only the schema metadata to the EasySQL API — credentials never leave your machine. SQLite connections have no credentials at all.
3. You ask questions in natural language; the API returns SQL.
4. The CLI validates that the SQL is SELECT-only and executes it against your local database.
5. Results are printed as a table — or opened in an interactive TUI shell.

Requirements

Runs on Node.js >= 22.13 (built-in node:sqlite) or Bun >= 1.4.

• Node.js >= 22.13, or Bun >= 1.4 — to run the npm package.
• Or no runtime at all — grab a standalone binary from GitHub Releases.

Both npx / npm i -g and bunx / bun add -g work.

Install

# 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 from GitHub Releases (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

Standalone binaries are published for linux-x64, linux-arm64, darwin-x64, darwin-arm64 and windows-x64.

MySQL, PostgreSQL and ClickHouse 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, bun add @easysql/connector-clickhouse, etc. Without the package, the CLI prints an install hint instead of a module-resolution error.

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 connection (schema is sent to EasySQL, not credentials)
easysql connection 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 connection add \
  --name "Local SQLite" \
  --type sqlite \
  --file /path/to/your.db

# 2d. Or a local ClickHouse server (HTTP interface)
easysql connection add \
  --name "Local ClickHouse" \
  --type clickhouse \
  --connection-url "clickhouse://default:pass@localhost:8123/analytics"

# 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 connection add	Add a local MySQL / Postgres / ClickHouse / SQLite connection
easysql connection sync [name]	Re-introspect and push the schema again
easysql connection list	List connections from EasySQL
easysql connection remove <name>	Remove a connection 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 stay on your machine: they resolve from $EASYSQL_DB_PASSWORD, then your OS keyring (opt-in with connection add --save-password), then a prompt — never to the API.

See SECURITY.md to report a vulnerability.

Self-update

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

Build from source

git clone https://github.com/Clearsoft-net/easysql-cli
cd easysql-cli
bun install
make build          # tsc → dist/
make build-compile  # bun build --compile → bin/easysql (standalone binary)
make test           # bun test
make check          # biome + tsc --noEmit
make deb            # .deb package → bin/easysql_<version>_<arch>.deb
make rpm            # .rpm package → bin/easysql-<version>-<release>.<arch>.rpm

make deb and make rpm package the standalone Linux binary for the host architecture (ARCH=arm64 cross-builds the arm64 package). They need dpkg-deb and/or rpmbuild installed.

See CONTRIBUTING.md for the development workflow and conventions.

License

MIT — see LICENSE.

A Clearsoft product.