terminal-ask 0.1.1

  ░█████╗░░██████╗██╗░░██╗
  ██╔══██╗██╔════╝██║░██╔╝
  ███████║╚█████╗░█████═╝░
  ██╔══██║░╚═══██╗██╔═██╗░
  ██║░░██║██████╔╝██║░╚██╗
  ╚═╝░░╚═╝╚═════╝╚═╝░░╚═╝

Your terminal command oracle. Powered by OpenRouter.

$ ask how do I find files larger than 100MB
find / -type f -size +100M
(copied to clipboard)

$ ask --verbose how do I find files larger than 100MB
find / -type f -size +100M

  find      — search for files in a directory hierarchy
  /         — start from the root (use . for current directory)
  -type f   — match files only, not directories
  -size +100M — only files larger than 100 megabytes

Requirements

• Python 3.8+
• An OpenRouter API key
• On Linux: xclip or xsel for clipboard support

Installation

terminal-ask is published on PyPI as terminal-ask and installs the ask command.

Recommended: pipx

pipx install terminal-ask

pip

pip install terminal-ask

From source (editable, good for development)

pip install -e .

Windows helper script

.\install.ps1

This just runs pip install --user -e . for you against the local checkout. If the ask command isn't found afterward, make sure your Python user Scripts directory is on PATH, or use pipx install terminal-ask instead.

After installing, restart your terminal, then:

ask how do I list open ports

First Run

On first use, the setup wizard will guide you through:

1. Pasting your OpenRouter API key
2. Choosing a default model

$ ask how do I create an SSH key
=== ask setup ===

Paste your OpenRouter API key (https://openrouter.ai/keys):
> sk-or-...

You can re-run setup at any time with ask --setup.

Usage

ask [options] <question>

Options

Flag	Description
--verbose	Include an explanation alongside the command
--copy, -c	Copy the result to clipboard
--model <id>	Switch the default model (saved permanently)
--setup	Re-run the setup wizard (key + model selection)
--reset-key	Remove the saved API key
--list-models	List models currently available (live-checked against OpenRouter)
--version	Show the installed version

Examples

# Get a command (auto-copied if single line)
ask how do I list open ports

# Get a command with explanation
ask --verbose how do I recursively delete empty folders

# Switch model
ask --model openai/gpt-4o-mini

# Ask with the new model and copy result
ask -c how do I tar a directory excluding node_modules

Models

The setup wizard offers a curated shortlist, checked against OpenRouter's live model catalog on each run (cached for 24h, with an offline fallback so the tool still works without network access):

Model	Notes
anthropic/claude-haiku-4.5	Default — fast, great for shell/code tasks
openai/gpt-5.6-luna	Fast, cheap, good for shell tasks
google/gemma-4-26b-a4b-it:free	Free tier via OpenRouter

Run ask --list-models to see the current, live-checked shortlist at any time.

You can also set any OpenRouter model directly:

ask --model anthropic/claude-sonnet-4.5

Configuration

Config is stored at ~/.config/ask/config.json:

{
  "api_key": "sk-or-...",
  "model": "anthropic/claude-haiku-4.5"
}

System Prompts

Prompts are bundled as Markdown files inside the package:

• src/ask_cli/prompts/default.md — used for standard (concise) responses
• src/ask_cli/prompts/verbose.md — used when --verbose is passed

Edit these files (and reinstall) to customize the assistant's behavior.

Development

pip install -e ".[dev]"
pytest

CI runs the test suite on Windows and Linux via GitHub Actions (.github/workflows/ci.yml).

Clipboard Behavior

• Single command returned: auto-copied to clipboard
• Multiple commands returned: only copied if --copy / -c is passed

Author

Created and maintained by Ramin Nikzad-Langerodi

info@bottleneck-analytics.com

License

MIT — see LICENSE.