@hongymagic/q 2026.328.0 → 2026.329.0-next.80eeecd

package/README.md

@@ -25,23 +25,37 @@ bun install && bun run build
 
 ## Setup
 
-1. **Create config:**
+`q` works without a config file.
+
+1. **Free local setup with Ollama**
 
 ```bash
-q config init
+ollama pull gemma3
+q --provider ollama --model gemma3 explain this stack trace
 ```
 
-2. **Set your API key:**
+2. **Free cloud setup with Gemini**
 
 ```bash
-export ANTHROPIC_API_KEY="your-key-here"
+export GEMINI_API_KEY="your-key-here"
+q explain rust lifetimes
 ```
 
+3. **Optional: create a pinned config**
+
+```bash
+q config init
+```
+
+`q` auto-detects common provider keys (`GEMINI_API_KEY`, `GROQ_API_KEY`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`) and falls back to local Ollama when available.
+
 ## Usage
 
 ```bash
 q how do I restart docker
+GEMINI_API_KEY="your-key" q explain closures in javascript
 q --copy what is a kubernetes pod
+q --provider ollama --model gemma3 explain this error
 ```
 
 ### Piping Content
@@ -85,47 +99,57 @@ q --mode explain how do I restart docker # Returns a detailed explanation
 
 ```bash
 q config path    # Print config file path
-q config init    # Create example config
-q config doctor  # Diagnose config and provider issues
-q providers      # List configured providers + model and credential status
+q config init    # Create optional config file
+q config doctor  # Diagnose config and setup issues
+q providers      # List available providers + model and credential status
 ```
 
 ## Configuration
 
-Config is loaded from (later overrides earlier):
+Config is optional. `q` starts with built-in provider presets and per-provider defaults, then applies overrides (later overrides earlier):
 
-1. `$XDG_CONFIG_HOME/q/config.toml` (or `~/.config/q/config.toml`)
-2. `./config.toml` (project-specific)
-3. Environment: `Q_PROVIDER`, `Q_MODEL`, `Q_COPY`
+1. Built-in defaults (`google`, `groq`, `anthropic`, `openai`, `ollama`, `azure`, `bedrock`)
+2. `$XDG_CONFIG_HOME/q/config.toml` (or `~/.config/q/config.toml`)
+3. `./config.toml` (project-specific)
+4. Environment: `Q_PROVIDER`, `Q_MODEL`, `Q_COPY`
+5. CLI flags: `--provider`, `--model`
 
 Each provider can specify its own default `model`, which takes precedence over `default.model` but is overridden by `Q_MODEL` or `--model`:
 
 ```toml
 [default]
-provider = "anthropic"
-model = "claude-sonnet-4-20250514"   # Global default
+provider = "google"
+# model = "gemini-2.5-flash"         # Optional global default
 
-[providers.anthropic]
-type = "anthropic"
-api_key_env = "ANTHROPIC_API_KEY"
-model = "claude-sonnet-4-20250514"   # Per-provider default
+[providers.google]
+type = "google"
+api_key_env = "GEMINI_API_KEY"
+model = "gemini-2.5-flash"           # Optional per-provider default
 ```
 
 See [config.example.toml](config.example.toml) for all options.
 
+### Free Setup Options
+
+| Option | Cost | What you need | Notes |
+|------|------|---------------|-------|
+| `ollama` | Free local | Ollama installed and a local model | Best zero-key/offline option |
+| `google` | Free tier | `GEMINI_API_KEY` (or `GOOGLE_API_KEY` / `GOOGLE_GENERATIVE_AI_API_KEY`) | Best free cloud default |
+| `groq` | Free tier | `GROQ_API_KEY` | Fast free cloud fallback |
+
 ### Provider Types
 
-| Type | Description |
-|------|-------------|
-| `anthropic` | Anthropic Claude API |
-| `openai` | OpenAI API |
-| `openai_compatible` | Any OpenAI-compatible API |
-| `ollama` | Local Ollama instance |
-| `portkey` | Portkey AI Gateway (self-hosted or cloud) |
-| `google` | Google Gemini API |
-| `groq` | Groq (ultra-fast Llama, Mixtral inference) |
-| `azure` | Azure OpenAI deployments |
-| `bedrock` | AWS Bedrock (Claude, Titan, Llama) |
+| Type | Built in | Description |
+|------|----------|-------------|
+| `google` | Yes | Google Gemini API |
+| `groq` | Yes | Groq (ultra-fast open models) |
+| `ollama` | Yes | Local Ollama instance |
+| `anthropic` | Yes | Anthropic Claude API |
+| `openai` | Yes | OpenAI API |
+| `azure` | Yes | Azure OpenAI deployments |
+| `bedrock` | Yes | AWS Bedrock (Claude, Titan, Llama) |
+| `openai_compatible` | No | Any OpenAI-compatible API (needs `base_url`) |
+| `portkey` | No | Portkey AI Gateway (needs `base_url` and `provider_slug`) |
 
 ### Portkey Gateway Setup
 
@@ -182,21 +206,32 @@ All agent PRs are created as drafts and require human approval to merge. The sys
 
 ## Troubleshooting
 
-**"Missing API key" error:**
+**"Setup required" error:**
 
-Ensure your API key environment variable is set:
+Use one of these quick starts:
 
 ```bash
-export ANTHROPIC_API_KEY="your-key-here"
+export GEMINI_API_KEY="your-key-here"
+q explain kubernetes pods
 ```
 
-**"Config file not found" error:**
+```bash
+q --provider ollama --model gemma3 explain kubernetes pods
+```
+
+Or create a config file with `q config init`.
+
+**"Missing API key" error:**
+
+Ensure your API key environment variable is set:
 
-Run `q config init` to create a default configuration file.
+```bash
+export GEMINI_API_KEY="your-key-here"
+```
 
 **Diagnose config issues:**
 
-Run `q config doctor` to check config files, environment overrides, and provider health at a glance.
+Run `q config doctor` to check config files, environment overrides, built-in defaults, and provider health at a glance.
 
 **Failure logs:**
 

package/dist/q.js

@@ -14712,7 +14712,7 @@ import { parseArgs } from "node:util";
 // package.json
 var package_default = {
   name: "@hongymagic/q",
-  version: "2026.328.0",
+  version: "2026.329.0-next.80eeecd",
   description: "Quick AI answers from the command line",
   main: "dist/q.js",
   type: "module",
@@ -14796,17 +14796,6 @@ class QError extends Error {
     this.name = "QError";
   }
 }
-
-class ConfigNotFoundError extends QError {
-  path;
-  constructor(path) {
-    super(`Config file not found: ${path}
-Run 'q config init' to create one.`, 2);
-    this.path = path;
-    this.name = "ConfigNotFoundError";
-  }
-}
-
 class ConfigParseError extends QError {
   path;
   details;
@@ -14850,6 +14839,22 @@ class MissingApiKeyError extends QError {
   }
 }
 
+class ModelNotConfiguredError extends QError {
+  providerName;
+  constructor(providerName) {
+    super(`No model configured for provider '${providerName}'. Set --model, Q_MODEL, provider.model, or default.model.`, 2);
+    this.providerName = providerName;
+    this.name = "ModelNotConfiguredError";
+  }
+}
+
+class SetupRequiredError extends QError {
+  constructor() {
+    super("Setup required. Install Ollama, set GEMINI_API_KEY or GROQ_API_KEY, or run 'q config init'.", 2);
+    this.name = "SetupRequiredError";
+  }
+}
+
 class ProviderError extends QError {
   constructor(message, cause) {
     super(message, 1, cause === undefined ? undefined : { cause });
@@ -14874,9 +14879,9 @@ var HELP_TEXT = `q - Quick AI answers from the command line
 USAGE:
   q [options] <query...>       Ask a question
   q config path                Print config file path
-  q config init                Create example config file
-  q config doctor              Diagnose config and provider issues
-  q providers                  List configured providers
+  q config init                Create optional config file
+  q config doctor              Diagnose config and setup issues
+  q providers                  List available providers
 
 OPTIONS:
   -p, --provider <name>        Override the default provider
@@ -14894,7 +14899,7 @@ ENVIRONMENT:
   Q_COPY                       Override default copy behaviour (true/false)
 
 CONFIG:
-  Config is loaded from (in order, later overrides earlier):
+  Config is optional. q uses built-in defaults and then loads overrides from:
     1. ~/.config/q/config.toml (or $XDG_CONFIG_HOME/q/config.toml)
     2. ./config.toml (current directory)
     3. Environment variables (Q_PROVIDER, Q_MODEL, Q_COPY)
@@ -14902,6 +14907,8 @@ CONFIG:
 EXAMPLES:
   q how do I restart docker
   q -p openai --model gpt-4o what is recursion
+  GEMINI_API_KEY=your-key q explain rust lifetimes
+  q --provider ollama --model gemma3 explain this error
   q config init
 `;
 var VERSION = package_default.version;
@@ -28788,6 +28795,273 @@ function formatPrefixedMessage(message, prefix, style) {
   return `${style(prefix)}${remainder}`;
 }
 
+// src/provider-catalog.ts
+var GOOGLE_API_KEY_ENV_VARS = [
+  "GEMINI_API_KEY",
+  "GOOGLE_API_KEY",
+  "GOOGLE_GENERATIVE_AI_API_KEY"
+];
+var DEFAULT_MODEL_BY_PROVIDER_TYPE = {
+  anthropic: "claude-sonnet-4-20250514",
+  openai: "gpt-4o-mini",
+  google: "gemini-2.5-flash",
+  groq: "openai/gpt-oss-20b",
+  ollama: "gemma3",
+  bedrock: "us.anthropic.claude-sonnet-4-20250514-v1:0"
+};
+var ENV_PROVIDER_INFERENCE_ORDER = [
+  "google",
+  "groq",
+  "anthropic",
+  "openai",
+  "bedrock",
+  "azure"
+];
+function dedupe(values) {
+  return [...new Set(values.filter((value) => value.length > 0))];
+}
+function hasAnyEnv(envVars, env3) {
+  return envVars.some((envVar) => Boolean(env3[envVar]));
+}
+function hasAllEnv(envVars, env3) {
+  return envVars.every((envVar) => Boolean(env3[envVar]));
+}
+function formatStatus(present) {
+  return present ? "set" : "missing";
+}
+function describeAnyOf(label, envVars, env3) {
+  const present = hasAnyEnv(envVars, env3);
+  const display = envVars.join(" or ");
+  return {
+    line: `${label}: ${display} (${formatStatus(present)})`,
+    issue: present ? undefined : `${display} is not set`
+  };
+}
+function describeAllOf(label, envVars, env3) {
+  const present = hasAllEnv(envVars, env3);
+  const display = envVars.join(" + ");
+  return {
+    line: `${label}: ${display} (${formatStatus(present)})`,
+    issue: present ? undefined : `${display} is not set`
+  };
+}
+function getGoogleApiKeyEnvVars(configuredEnvVar) {
+  if (!configuredEnvVar) {
+    return [...GOOGLE_API_KEY_ENV_VARS];
+  }
+  if (GOOGLE_API_KEY_ENV_VARS.some((envVar) => envVar === configuredEnvVar)) {
+    return dedupe([configuredEnvVar, ...GOOGLE_API_KEY_ENV_VARS]);
+  }
+  return [configuredEnvVar];
+}
+function getBuiltInProviderConfigs(env3 = process.env) {
+  return {
+    anthropic: {
+      type: "anthropic",
+      api_key_env: "ANTHROPIC_API_KEY"
+    },
+    openai: {
+      type: "openai",
+      api_key_env: "OPENAI_API_KEY"
+    },
+    google: {
+      type: "google",
+      api_key_env: GOOGLE_API_KEY_ENV_VARS[0]
+    },
+    groq: {
+      type: "groq",
+      api_key_env: "GROQ_API_KEY"
+    },
+    ollama: {
+      type: "ollama"
+    },
+    azure: {
+      type: "azure",
+      api_key_env: "AZURE_API_KEY",
+      ...env3.AZURE_RESOURCE_NAME ? { resource_name: env3.AZURE_RESOURCE_NAME } : {}
+    },
+    bedrock: {
+      type: "bedrock",
+      ...env3.AWS_REGION ? { region: env3.AWS_REGION } : {}
+    }
+  };
+}
+function getDefaultModelForProviderType(providerType) {
+  return DEFAULT_MODEL_BY_PROVIDER_TYPE[providerType];
+}
+function getDefaultModelForProvider(providerConfig) {
+  if (!providerConfig) {
+    return;
+  }
+  return providerConfig.model ?? getDefaultModelForProviderType(providerConfig.type);
+}
+function inferProviderFromEnvironment(env3 = process.env) {
+  for (const providerName of ENV_PROVIDER_INFERENCE_ORDER) {
+    switch (providerName) {
+      case "google":
+        if (hasAnyEnv(GOOGLE_API_KEY_ENV_VARS, env3)) {
+          return providerName;
+        }
+        break;
+      case "groq":
+        if (env3.GROQ_API_KEY) {
+          return providerName;
+        }
+        break;
+      case "anthropic":
+        if (env3.ANTHROPIC_API_KEY) {
+          return providerName;
+        }
+        break;
+      case "openai":
+        if (env3.OPENAI_API_KEY) {
+          return providerName;
+        }
+        break;
+      case "bedrock":
+        if (env3.AWS_ACCESS_KEY_ID && env3.AWS_SECRET_ACCESS_KEY || env3.AWS_PROFILE) {
+          return providerName;
+        }
+        break;
+      case "azure":
+        if (env3.AZURE_API_KEY && env3.AZURE_RESOURCE_NAME) {
+          return providerName;
+        }
+        break;
+    }
+  }
+  return;
+}
+async function detectLocalProvider() {
+  try {
+    const response = await fetch("http://127.0.0.1:11434/api/tags", {
+      signal: AbortSignal.timeout(200)
+    });
+    if (response.ok) {
+      return "ollama";
+    }
+  } catch {}
+  return;
+}
+function getProviderStatusSummary(providerConfig, env3 = process.env) {
+  switch (providerConfig.type) {
+    case "ollama":
+      return {
+        lines: ["Auth: none required"],
+        issues: []
+      };
+    case "google": {
+      const apiKey = describeAnyOf("Key", getGoogleApiKeyEnvVars(providerConfig.api_key_env), env3);
+      return {
+        lines: [apiKey.line],
+        issues: apiKey.issue ? [apiKey.issue] : []
+      };
+    }
+    case "azure": {
+      const lines = [];
+      const issues = [];
+      const apiKey = describeAnyOf("Key", [providerConfig.api_key_env ?? "AZURE_API_KEY"], env3);
+      lines.push(apiKey.line);
+      if (apiKey.issue) {
+        issues.push(apiKey.issue);
+      }
+      if (providerConfig.base_url) {
+        lines.push("Endpoint: base_url configured");
+      } else if (providerConfig.resource_name) {
+        lines.push(`Endpoint: resource ${providerConfig.resource_name}`);
+      } else {
+        lines.push("Endpoint: set AZURE_RESOURCE_NAME or base_url");
+        issues.push("AZURE_RESOURCE_NAME or base_url is required");
+      }
+      return { lines, issues };
+    }
+    case "bedrock": {
+      if (providerConfig.access_key_env || providerConfig.secret_key_env) {
+        const credentials = describeAllOf("AWS credentials", [
+          providerConfig.access_key_env ?? "AWS_ACCESS_KEY_ID",
+          providerConfig.secret_key_env ?? "AWS_SECRET_ACCESS_KEY"
+        ], env3);
+        return {
+          lines: [credentials.line],
+          issues: credentials.issue ? [credentials.issue] : []
+        };
+      }
+      return {
+        lines: ["Auth: AWS SDK default credential chain"],
+        issues: []
+      };
+    }
+    case "openai_compatible": {
+      const lines = [];
+      const issues = [];
+      if (providerConfig.api_key_env) {
+        const apiKey = describeAnyOf("Key", [providerConfig.api_key_env], env3);
+        lines.push(apiKey.line);
+        if (apiKey.issue) {
+          issues.push(apiKey.issue);
+        }
+      } else {
+        lines.push("Key: (none required)");
+      }
+      if (providerConfig.base_url) {
+        lines.push("Endpoint: base_url configured");
+      } else {
+        lines.push("Endpoint: missing base_url");
+        issues.push("base_url is required");
+      }
+      return { lines, issues };
+    }
+    case "portkey": {
+      const lines = [];
+      const issues = [];
+      if (providerConfig.api_key_env) {
+        const apiKey = describeAnyOf("Gateway key", [providerConfig.api_key_env], env3);
+        lines.push(apiKey.line);
+        if (apiKey.issue) {
+          issues.push(apiKey.issue);
+        }
+      } else {
+        lines.push("Gateway key: (optional)");
+      }
+      if (providerConfig.provider_api_key_env) {
+        const providerKey = describeAnyOf("Upstream key", [providerConfig.provider_api_key_env], env3);
+        lines.push(providerKey.line);
+        if (providerKey.issue) {
+          issues.push(providerKey.issue);
+        }
+      } else {
+        lines.push("Upstream key: (optional)");
+      }
+      if (!providerConfig.base_url) {
+        issues.push("base_url is required");
+        lines.push("Endpoint: missing base_url");
+      } else {
+        lines.push("Endpoint: base_url configured");
+      }
+      if (!providerConfig.provider_slug) {
+        issues.push("provider_slug is required");
+        lines.push("Provider slug: missing");
+      } else {
+        lines.push(`Provider slug: ${providerConfig.provider_slug}`);
+      }
+      return { lines, issues };
+    }
+    default: {
+      if (!providerConfig.api_key_env) {
+        return {
+          lines: ["Key: (none required)"],
+          issues: []
+        };
+      }
+      const apiKey = describeAnyOf("Key", [providerConfig.api_key_env], env3);
+      return {
+        lines: [apiKey.line],
+        issues: apiKey.issue ? [apiKey.issue] : []
+      };
+    }
+  }
+}
+
 // src/config/index.ts
 var ProviderType = exports_external.enum([
   "openai",
@@ -28815,8 +29089,8 @@ var ProviderConfigSchema = exports_external.object({
   secret_key_env: exports_external.string().optional()
 });
 var DefaultConfigSchema = exports_external.object({
-  provider: exports_external.string(),
-  model: exports_external.string(),
+  provider: exports_external.string().optional(),
+  model: exports_external.string().optional(),
   copy: exports_external.boolean().optional()
 });
 var ConfigSchema = exports_external.object({
@@ -28859,18 +29133,21 @@ class Config {
       Config.tryLoadFile(getXdgConfigPath()),
       Config.tryLoadFile(getCwdConfigPath())
     ]);
-    if (!xdgConfig && !cwdConfig) {
-      throw new ConfigNotFoundError(getXdgConfigPath());
-    }
     const mergedDefault = {
       ...xdgConfig?.default ?? {},
       ...cwdConfig?.default ?? {}
     };
     const mergedProviders = {
+      ...getBuiltInProviderConfigs(),
       ...xdgConfig?.providers ?? {},
       ...cwdConfig?.providers ?? {}
     };
+    const inferredProvider = await Config.inferDefaultProvider(mergedDefault);
+    const providerForDefaultModel = env.Q_PROVIDER ?? mergedDefault.provider ?? inferredProvider;
+    const inferredModel = providerForDefaultModel ? getDefaultModelForProvider(mergedProviders[providerForDefaultModel]) : undefined;
     const finalDefault = {
+      ...inferredProvider ? { provider: inferredProvider } : {},
+      ...inferredModel ? { model: inferredModel } : {},
       ...mergedDefault,
       ...env.Q_PROVIDER ? { provider: env.Q_PROVIDER } : {},
       ...env.Q_MODEL ? { model: env.Q_MODEL } : {},
@@ -28887,8 +29164,21 @@ class Config {
     const interpolated = Config.interpolateEnvVars(result.data);
     return new Config(interpolated);
   }
+  static async inferDefaultProvider(mergedDefault) {
+    if (mergedDefault.provider || env.Q_PROVIDER) {
+      return;
+    }
+    const envProvider = inferProviderFromEnvironment();
+    if (envProvider) {
+      return envProvider;
+    }
+    return detectLocalProvider();
+  }
   getProvider(name) {
     const providerName = name ?? this.default.provider;
+    if (!providerName) {
+      throw new ConfigValidationError("No default provider is configured. Set Q_PROVIDER, pass --provider, install Ollama, set an API key, or run 'q config init'.");
+    }
     const provider = this.providers[providerName];
     if (!provider) {
       throw new ConfigValidationError(`Provider '${providerName}' not found in config.
@@ -28952,6 +29242,8 @@ Consider using HTTPS for non-localhost connections.`);
 var ALLOWED_INTERPOLATION_VARS = new Set([
   "ANTHROPIC_API_KEY",
   "OPENAI_API_KEY",
+  "GEMINI_API_KEY",
+  "GOOGLE_API_KEY",
   "PORTKEY_API_KEY",
   "GOOGLE_GENERATIVE_AI_API_KEY",
   "GROQ_API_KEY",
@@ -28998,18 +29290,22 @@ async function runConfigDoctor() {
     xdgFile.exists(),
     cwdFile.exists()
   ]);
+  const [xdgData, cwdData] = await Promise.all([
+    xdgExists ? safeParseToml(xdgFile) : Promise.resolve(null),
+    cwdExists ? safeParseToml(cwdFile) : Promise.resolve(null)
+  ]);
   const layers = [
     {
       source: "XDG config",
       path: xdgPath,
       found: xdgExists,
-      data: xdgExists ? await safeParseToml(xdgFile) : null
+      data: xdgData
     },
     {
       source: "CWD config",
       path: cwdPath,
       found: cwdExists,
-      data: cwdExists ? await safeParseToml(cwdFile) : null
+      data: cwdData
     }
   ];
   const envOverrides = [
@@ -29030,33 +29326,51 @@ async function runConfigDoctor() {
     }
   ];
   const providerIssues = [];
+  const configuredProviderNames = new Set([
+    ...Object.keys((xdgData ?? {}).providers ?? {}),
+    ...Object.keys((cwdData ?? {}).providers ?? {})
+  ]);
   try {
     const config2 = await Config.load();
-    for (const [name, providerConfig] of Object.entries(config2.providers)) {
-      if (providerConfig.api_key_env) {
-        if (!process.env[providerConfig.api_key_env]) {
-          providerIssues.push({
-            provider: name,
-            issue: `${providerConfig.api_key_env} is not set`
-          });
-        }
+    if (!xdgExists && !cwdExists) {
+      if (config2.default.provider) {
+        providerIssues.push({
+          provider: "(setup)",
+          issue: `No config file found. Using built-in defaults with provider '${config2.default.provider}'.`
+        });
+      } else {
+        providerIssues.push({
+          provider: "(setup)",
+          issue: "No config file or detected provider found. Install Ollama, set GEMINI_API_KEY or GROQ_API_KEY, or run 'q config init'."
+        });
       }
-      if (providerConfig.provider_api_key_env) {
-        if (!process.env[providerConfig.provider_api_key_env]) {
-          providerIssues.push({
-            provider: name,
-            issue: `${providerConfig.provider_api_key_env} is not set`
-          });
-        }
+    }
+    if (config2.default.provider) {
+      configuredProviderNames.add(config2.default.provider);
+    }
+    if (configuredProviderNames.size === 0 && config2.default.provider) {
+      configuredProviderNames.add(config2.default.provider);
+    }
+    for (const name of configuredProviderNames) {
+      const providerConfig = config2.providers[name];
+      if (!providerConfig) {
+        providerIssues.push({
+          provider: name,
+          issue: "Provider is not available."
+        });
+        continue;
+      }
+      const { issues } = getProviderStatusSummary(providerConfig);
+      for (const issue2 of issues) {
+        providerIssues.push({ provider: name, issue: issue2 });
       }
     }
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     providerIssues.push({ provider: "(config)", issue: message });
   }
-  const noConfigAtAll = !xdgExists && !cwdExists;
   const configLoadFailed = providerIssues.some((i) => i.provider === "(config)");
-  const hasErrors = noConfigAtAll || configLoadFailed;
+  const hasErrors = configLoadFailed;
   const hasWarnings = providerIssues.length > 0;
   return {
     layers,
@@ -29123,72 +29437,62 @@ function formatZodErrors(error48) {
 var EXAMPLE_CONFIG = `# q configuration file
 # Location: ~/.config/q/config.toml
 #
-# Config resolution order (later overrides earlier):
-#   1. This file (XDG_CONFIG_HOME/q/config.toml or ~/.config/q/config.toml)
-#   2. ./config.toml in current directory (project-specific)
-#   3. Environment variables: Q_PROVIDER, Q_MODEL, Q_COPY
+# This file is optional. q can run with built-in defaults:
+#   - install Ollama for local usage, or
+#   - set GEMINI_API_KEY / GROQ_API_KEY / ANTHROPIC_API_KEY / OPENAI_API_KEY
+#
+# Add settings here only when you want to pin behaviour or customise providers.
 
 [default]
-provider = "anthropic"
-model = "claude-sonnet-4-20250514"
-# copy = true  # Always copy answer to clipboard (override with --no-copy)
-
-[providers.anthropic]
-type = "anthropic"
-api_key_env = "ANTHROPIC_API_KEY"
-# model = "claude-sonnet-4-20250514"  # Optional per-provider default model
-
-[providers.openai]
-type = "openai"
-api_key_env = "OPENAI_API_KEY"
-# model = "gpt-4o"  # Optional per-provider default model
+# provider = "google"          # Optional: q auto-detects a provider when possible
+# model = "gemini-2.5-flash"   # Optional: q uses provider defaults when omitted
+# copy = true                   # Optional: always copy answer to clipboard
 
-# Example: OpenAI-compatible provider (e.g., local LLM via LM Studio)
-# [providers.local]
-# type = "openai_compatible"
-# base_url = "http://localhost:1234/v1"
-# api_key_env = "LOCAL_API_KEY"
-
-# Example: Portkey Gateway
-# [providers.portkey_internal]
-# type = "portkey"
-# base_url = "https://your-portkey-gateway.internal/v1"
-# provider_slug = "@your-org/bedrock-provider"
-# api_key_env = "PORTKEY_API_KEY"
-# provider_api_key_env = "PROVIDER_API_KEY"
-# headers = { "x-portkey-trace-id" = "\${HOSTNAME}" }  # Only allowlisted env vars
-
-# Example: Ollama (local models)
+# Local-first example
 # [providers.ollama]
 # type = "ollama"
-# base_url = "http://localhost:11434"
+# # base_url = "http://localhost:11434"
+# # model = "gemma3"
 
-# Example: Google Gemini
+# Free cloud example (Google Gemini)
 # [providers.google]
 # type = "google"
-# api_key_env = "GOOGLE_GENERATIVE_AI_API_KEY"
-# # Models: gemini-2.5-pro, gemini-2.5-flash, gemini-2.0-flash
+# # api_key_env = "GEMINI_API_KEY"
+# # model = "gemini-2.5-flash"
 
-# Example: Groq (ultra-fast inference)
+# Free cloud example (Groq)
 # [providers.groq]
 # type = "groq"
-# api_key_env = "GROQ_API_KEY"
-# # Models: llama-3.3-70b-versatile, qwen-qwq-32b, deepseek-r1-distill-llama-70b
+# # api_key_env = "GROQ_API_KEY"
+# # model = "openai/gpt-oss-20b"
+
+# Advanced examples
+# [providers.work_openai]
+# type = "openai"
+# api_key_env = "OPENAI_API_KEY"
+# model = "gpt-4o-mini"
+
+# [providers.local]
+# type = "openai_compatible"
+# base_url = "http://localhost:1234/v1"
+# # api_key_env = "LOCAL_API_KEY"
 
-# Example: Azure OpenAI
 # [providers.azure]
 # type = "azure"
-# resource_name = "my-azure-resource"  # Or use base_url instead
+# resource_name = "my-azure-resource"
 # api_key_env = "AZURE_API_KEY"
-# api_version = "v1"  # Optional, defaults to v1
-# # Model = deployment name (e.g., "gpt-4o-deployment")
+# # model = "gpt-4o-deployment"
 
-# Example: AWS Bedrock
 # [providers.bedrock]
 # type = "bedrock"
-# region = "us-east-1"  # Optional, defaults to AWS_REGION env var
-# # Uses standard AWS env vars: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
-# # Models: anthropic.claude-3-5-sonnet-20241022-v2:0, us.amazon.nova-pro-v1:0
+# region = "us-east-1"
+# # model = "us.anthropic.claude-sonnet-4-20250514-v1:0"
+
+# [providers.portkey]
+# type = "portkey"
+# base_url = "https://api.portkey.ai/v1"
+# provider_slug = "openai"
+# api_key_env = "PORTKEY_API_KEY"
 `;
 async function initConfig() {
   const configPath = getXdgConfigPath();
@@ -29297,7 +29601,7 @@ class QError2 extends Error {
   }
 }
 
-class ConfigNotFoundError2 extends QError2 {
+class ConfigNotFoundError extends QError2 {
   path;
   constructor(path2) {
     super(`Config file not found: ${path2}
@@ -29350,6 +29654,22 @@ class MissingApiKeyError2 extends QError2 {
   }
 }
 
+class ModelNotConfiguredError2 extends QError2 {
+  providerName;
+  constructor(providerName) {
+    super(`No model configured for provider '${providerName}'. Set --model, Q_MODEL, provider.model, or default.model.`, 2);
+    this.providerName = providerName;
+    this.name = "ModelNotConfiguredError";
+  }
+}
+
+class SetupRequiredError2 extends QError2 {
+  constructor() {
+    super("Setup required. Install Ollama, set GEMINI_API_KEY or GROQ_API_KEY, or run 'q config init'.", 2);
+    this.name = "SetupRequiredError";
+  }
+}
+
 class ProviderError2 extends QError2 {
   constructor(message, cause) {
     super(message, 1, cause === undefined ? undefined : { cause });
@@ -29364,7 +29684,7 @@ class UsageError2 extends QError2 {
   }
 }
 function getUserErrorMessage(error48) {
-  if (error48 instanceof ConfigNotFoundError2) {
+  if (error48 instanceof ConfigNotFoundError) {
     return "Config file not found. Run 'q config init'.";
   }
   if (error48 instanceof ConfigParseError2) {
@@ -29379,6 +29699,12 @@ function getUserErrorMessage(error48) {
   if (error48 instanceof MissingApiKeyError2) {
     return `Missing API key. Set ${error48.envVar}.`;
   }
+  if (error48 instanceof ModelNotConfiguredError2) {
+    return getFirstLine(error48.message);
+  }
+  if (error48 instanceof SetupRequiredError2) {
+    return error48.message;
+  }
   if (error48 instanceof ProviderError2) {
     return getProviderUserMessage(error48);
   }
@@ -53202,7 +53528,7 @@ var google = createGoogleGenerativeAI();
 // src/providers/google.ts
 function createGoogleProvider(config2, providerName) {
   return createGoogleGenerativeAI({
-    apiKey: resolveApiKey(config2.api_key_env, providerName),
+    apiKey: resolveApiKeyCandidates(getGoogleApiKeyEnvVars(config2.api_key_env), providerName),
     baseURL: config2.base_url,
     headers: config2.headers
   });
@@ -62837,6 +63163,15 @@ function resolveApiKey(envVarName, providerName) {
   }
   return apiKey;
 }
+function resolveApiKeyCandidates(envVarNames, providerName) {
+  for (const envVarName of envVarNames) {
+    const apiKey = process.env[envVarName];
+    if (apiKey) {
+      return apiKey;
+    }
+  }
+  throw new MissingApiKeyError(envVarNames.join(" or "), providerName);
+}
 
 // src/providers/anthropic.ts
 function createAnthropicProvider(config2, providerName) {
@@ -62861,12 +63196,18 @@ function filterSensitiveFields(config2) {
   }
 }
 function resolveProvider(config2, providerOverride, modelOverride, debug = false) {
-  const providerName = providerOverride ?? config2.default.provider;
+  const providerName = providerOverride ?? env.Q_PROVIDER ?? config2.default.provider;
+  if (!providerName) {
+    throw new SetupRequiredError;
+  }
   const providerConfig = config2.providers[providerName];
   if (!providerConfig) {
     throw new ProviderNotFoundError(providerName);
   }
-  const modelId = modelOverride ?? env.Q_MODEL ?? providerConfig.model ?? config2.default.model;
+  const modelId = modelOverride ?? env.Q_MODEL ?? providerConfig.model ?? config2.default.model ?? getDefaultModelForProvider(providerConfig);
+  if (!modelId) {
+    throw new ModelNotConfiguredError(providerName);
+  }
   logDebug(`Provider config: ${JSON.stringify(filterSensitiveFields(providerConfig), null, 2)}`, debug);
   const model = createModel(providerConfig, providerName, modelId, debug);
   return {
@@ -62915,31 +63256,6 @@ function createModel(config2, providerName, modelId, debug = false) {
     }
   }
 }
-var CREDENTIAL_FIELDS = [
-  "api_key_env",
-  "provider_api_key_env",
-  "access_key_env",
-  "secret_key_env"
-];
-function getCredentialStatuses(providerConfig) {
-  return CREDENTIAL_FIELDS.reduce((acc, field) => {
-    const envVar = providerConfig[field];
-    if (envVar) {
-      acc.push({ envVar, present: Boolean(process.env[envVar]) });
-    }
-    return acc;
-  }, []);
-}
-function formatCredentialLine(statuses) {
-  if (statuses.length === 0) {
-    return "    Key: (none required)";
-  }
-  return statuses.map(({ envVar, present }) => {
-    const status = present ? "set" : "missing";
-    return `    Key: ${envVar} (${status})`;
-  }).join(`
-`);
-}
 function listProviders(config2) {
   const providers = Object.keys(config2.providers);
   const defaultProvider = config2.default.provider;
@@ -62951,18 +63267,19 @@ function listProviders(config2) {
       return `  ${name15} [unknown]`;
     const marker16 = isDefault ? " (default)" : "";
     const header = `  ${name15}${marker16} [${providerConfig.type}]`;
-    const modelDisplay = providerConfig.model ?? "(default)";
+    const modelDisplay = providerConfig.model ?? getDefaultModelForProvider(providerConfig) ?? "(set with --model or config)";
     const modelLine = `    Model: ${modelDisplay}`;
-    const credentialLine = formatCredentialLine(getCredentialStatuses(providerConfig));
-    return [header, modelLine, credentialLine].join(`
+    const credentialLines = getProviderStatusSummary(providerConfig).lines.map((line) => `    ${line}`);
+    return [header, modelLine, ...credentialLines].join(`
 `);
   });
   const lines = [
-    "Configured providers:",
+    "Available providers:",
     "",
     ...providerBlocks,
     "",
-    `Default model: ${defaultModel}`
+    `Default provider: ${defaultProvider ?? "(choose with --provider or env)"}`,
+    `Default model: ${defaultModel ?? "(provider default)"}`
   ];
   return lines.join(`
 `);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hongymagic/q",
-  "version": "2026.328.0",
+  "version": "2026.329.0-next.80eeecd",
   "description": "Quick AI answers from the command line",
   "main": "dist/q.js",
   "type": "module",