q — Quick AI Answers from the Command Line

A fast, minimal CLI for getting AI answers directly in your terminal.

When running in an interactive terminal, q shows a small ASCII loading indicator on stderr while it waits for the first response text.

Installation

npm install -g @hongymagic/q

Or download a standalone binary from the releases page.

Or build from source with Bun:

git clone https://github.com/hongymagic/q.git && cd q
bun install && bun run build

Setup

q works without a config file.

1. Free local setup with Ollama

ollama pull gemma3
q --provider ollama --model gemma3 explain this stack trace

2. Free cloud setup with Gemini

export GEMINI_API_KEY="your-key-here"
q explain rust lifetimes

3. Optional: create a pinned config

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

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

Pipe content as context for your question:

cat error.log | q "what's wrong here?"
git diff | q "summarise these changes"

Or pipe the query itself:

echo "how do I restart docker" | q

Options

Option	Description
-p, --provider <name>	Override the default provider
-m, --model <id>	Override the default model
--mode <mode>	Output mode: command (default) or explain
--copy	Copy answer to clipboard
--no-copy	Disable copy (overrides config)
--debug	Enable debug logging to stderr
-h, --help	Show help message
-v, --version	Show version

Output Modes

By default, q returns terse, copy/paste-ready commands. Use --mode explain for detailed explanations:

q how do I restart docker               # Returns the command(s)
q --mode explain how do I restart docker # Returns a detailed explanation

Commands

q config path    # Print config file path
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 optional. q starts with built-in provider presets and per-provider defaults, then applies overrides (later overrides earlier):

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:

[default]
provider = "google"
# model = "gemini-2.5-flash"         # Optional global default

[providers.google]
type = "google"
api_key_env = "GEMINI_API_KEY"
model = "gemini-2.5-flash"           # Optional per-provider default

See 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	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

Portkey is an AI gateway that provides unified access to multiple LLM providers with features like load balancing, caching, and observability. Use the portkey provider type for self-hosted or cloud deployments.

Self-hosted gateway:

[default]
provider = "portkey_internal"
model = "us.anthropic.claude-sonnet-4-20250514-v1:0"

[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"

Configuration options:

Field	Description
base_url	Your Portkey gateway URL
provider_slug	Provider identifier (maps to x-portkey-provider header)
api_key_env	Environment variable for Portkey API key (maps to x-portkey-api-key header)
provider_api_key_env	Environment variable for underlying provider's API key (maps to Authorization header)
headers	Additional custom headers (supports env var interpolation for allowlisted vars)

Environment variables:

export PORTKEY_API_KEY="your-portkey-key"
export PROVIDER_API_KEY="your-provider-key"

Self-Evolving System

q includes an autonomous improvement system powered by GitHub Agentic Workflows. AI agents continuously scan, assess, and improve the codebase across multiple dimensions — security, features, maintenance, performance, test coverage, and usability.

Agent	Schedule	Purpose
Security Daily	Daily	Scan and fix security vulnerabilities
Feature Daily	Daily	Detect and implement feature gaps
Maintenance Daily	Daily	Fix dead code, test gaps, docs drift
Self Improve Weekly	Monday	Retrospective on PR quality patterns
Performance Weekly	Tuesday	Binary size, speed, memory optimisation
Coverage Weekly	Wednesday	Expand test coverage
Usability Weekly	Thursday	CLI UX, error messages, help text
Self Evolve Fortnightly	1st & 15th	Meta-agent: improve the agents themselves

All agent PRs are created as drafts and require human approval to merge. The system is governed by .github/CONSTITUTION.md which defines immutable safety rules. All autonomous changes are tracked in .github/EVOLUTION.md.

Troubleshooting

"Setup required" error:

Use one of these quick starts:

export GEMINI_API_KEY="your-key-here"
q explain kubernetes pods

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:

export GEMINI_API_KEY="your-key-here"

Diagnose config issues:

Run q config doctor to check config files, environment overrides, built-in defaults, and provider health at a glance.

Failure logs:

Most non-usage failures print a short error plus Full log: <path> on stderr. Logs are written to your platform log directory, for example ~/.local/state/q/errors on Linux.

In an interactive terminal, query failures also offer quick recovery options: press r to retry, Enter to print the full log, or q/Esc to exit.

Debug mode:

Use --debug to keep detailed diagnostics on stderr while still writing the full failure log:

q --debug "how do I list docker containers"

Piped content not working:

Ensure you're piping content correctly. The query should be in arguments:

cat file.txt | q "explain this"   # Correct
cat file.txt | q                   # Uses stdin as query (no context)

Licence

MIT