@deaquinodev/querky 0.4.0 → 0.4.1

package/README.md

@@ -25,12 +25,19 @@ A quirky terminal SQL client with vim keybindings, schema-aware autocomplete, qu
 ## Requirements
 
 - Node.js 18+
-- pnpm
 
 ---
 
 ## Install
 
+```bash
+npm install -g @deaquinodev/querky
+```
+
+After that, `querky` is available globally.
+
+### Install from source
+
 ```bash
 git clone https://github.com/arthurdaquinosilva/querky.git
 cd querky
@@ -39,8 +46,6 @@ pnpm build
 pnpm install -g .
 ```
 
-After that, `querky` is available globally.
-
 ---
 
 ## Connecting
@@ -116,10 +121,12 @@ Ollama is the default endpoint (`http://localhost:11434/v1`).
 | `/explain-previous` | Explain the last query you ran |
 | `/databases` | List available databases |
 | `/tables` | List tables in the current database |
+| `/describe <table>` | Show columns, types, and key constraints for a table |
 | `/export csv` | Export last result to a CSV file |
 | `/export json` | Export last result to a JSON file |
 | `/next` | Next page of results |
 | `/prev` | Previous page of results |
+| `/clear` | Clear the screen and scrollback |
 | `/toggle-vim-mode` | Toggle vim keybindings on/off |
 | `/save <name>` | Save the last query as an alias |
 | `/alias <name> <SQL>` | Define an alias inline |
@@ -181,6 +188,7 @@ Users coming from `psql` can use familiar meta-commands:
 |---|---|
 | `\l` | List databases |
 | `\d` or `\dt` | List tables |
+| `\d <table>` | Show columns for a table |
 | `\du` | List users |
 | `\c` | Show current database |
 | `\c <dbname>` | Switch to a different database |
@@ -202,13 +210,28 @@ Querky starts in INSERT mode. Press `Escape` to enter NORMAL mode.
 | `x` / `s` | Delete/substitute character |
 | `D` / `C` | Delete/change to end of line |
 | `yy` / `p` | Yank line / paste |
+| `e` | Open current input in `$EDITOR` |
 
-In INSERT mode, **↑↓** navigates query history.
+In INSERT mode, **↑↓** navigates query history. **Ctrl+E** opens `$EDITOR` from INSERT mode.
 
 Disable vim mode with `/toggle-vim-mode` or pass `--no-vim` for plain input.
 
 ---
 
+## Shell Mode
+
+Prefix any command with `!` to run it in your shell without leaving querky:
+
+```
+! ls -la
+! pg_dump mydb > backup.sql
+! cat results.csv | wc -l
+```
+
+Output appears inline. ANSI colors and pipes are preserved.
+
+---
+
 ## All Flags
 
 | Flag | Default | Description |

package/dist/index.js

@@ -740,6 +740,7 @@ async function* streamExplain(query, baseUrl, model, apiKey) {
   let res;
   const headers = { "Content-Type": "application/json" };
   if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`;
+  const isDefaultOllama = baseUrl === "http://localhost:11434/v1";
   try {
     res = await fetch(`${baseUrl}/chat/completions`, {
       method: "POST",
@@ -751,14 +752,20 @@ async function* streamExplain(query, baseUrl, model, apiKey) {
       })
     });
   } catch {
-    throw new Error("Could not reach Ollama \u2014 is it running? Try: ollama serve");
+    if (isDefaultOllama) {
+      throw new Error(
+        "No AI model configured.\n\nOption A \u2014 run Ollama locally (free, offline):\n  ollama serve\n  ollama pull llama3.2\n\nOption B \u2014 use Groq (free, fast):\n  querky -c <dsn> --ai-url https://api.groq.com/openai/v1 \\\n    --ai-model llama-3.1-8b-instant --api-key YOUR_GROQ_KEY"
+      );
+    }
+    throw new Error(`Could not reach ${baseUrl} \u2014 check your --ai-url and connection.`);
   }
   if (!res.ok) {
     const body = await res.text().catch(() => "");
-    throw new Error(`Ollama error ${res.status}: ${body || res.statusText}`);
+    const provider = isDefaultOllama ? "Ollama" : baseUrl;
+    throw new Error(`${provider} error ${res.status}: ${body || res.statusText}`);
   }
   const reader = res.body?.getReader();
-  if (!reader) throw new Error("No response body from Ollama");
+  if (!reader) throw new Error("No response body from AI provider");
   const decoder = new TextDecoder();
   let buf = "";
   while (true) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deaquinodev/querky",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "A quirky terminal SQL client with vim mode, AI features, and schema-aware autocomplete",
   "main": "dist/index.js",
   "files": [